diff options
Diffstat (limited to 'contrib/cvs/doc')
| -rw-r--r-- | contrib/cvs/doc/ChangeLog | 4762 | ||||
| -rw-r--r-- | contrib/cvs/doc/ChangeLog.fsf | 38 | ||||
| -rw-r--r-- | contrib/cvs/doc/HACKING.DOCS | 46 | ||||
| -rw-r--r-- | contrib/cvs/doc/Makefile.am | 121 | ||||
| -rw-r--r-- | contrib/cvs/doc/Makefile.in | 816 | ||||
| -rw-r--r-- | contrib/cvs/doc/RCSFILES | 276 | ||||
| -rw-r--r-- | contrib/cvs/doc/cvs-paper.ms | 1069 | ||||
| -rw-r--r-- | contrib/cvs/doc/cvs.1 | 3968 | ||||
| -rw-r--r-- | contrib/cvs/doc/cvs.man.footer | 58 | ||||
| -rw-r--r-- | contrib/cvs/doc/cvs.man.header | 61 | ||||
| -rw-r--r-- | contrib/cvs/doc/cvs.texinfo | 14892 | ||||
| -rw-r--r-- | contrib/cvs/doc/cvsclient.texi | 2080 | ||||
| -rwxr-xr-x | contrib/cvs/doc/mdate-sh | 201 | ||||
| -rw-r--r-- | contrib/cvs/doc/mkman.pl | 372 | ||||
| -rw-r--r-- | contrib/cvs/doc/stamp-1 | 4 | ||||
| -rw-r--r-- | contrib/cvs/doc/stamp-vti | 4 | ||||
| -rw-r--r-- | contrib/cvs/doc/version-client.texi | 4 | ||||
| -rw-r--r-- | contrib/cvs/doc/version.texi | 4 |
18 files changed, 28776 insertions, 0 deletions
diff --git a/contrib/cvs/doc/ChangeLog b/contrib/cvs/doc/ChangeLog new file mode 100644 index 0000000..e00073b --- /dev/null +++ b/contrib/cvs/doc/ChangeLog @@ -0,0 +1,4762 @@ +2008-03-10 Mark D. Baushke <mdb@gnu.org> + + * cvs.texinfo (config): Document the IgnoreUnknownConfigKeys + option. + +2008-01-27 Mark D. Baushke <mdb@gnu.org> + + * cvs.texinfo: Document use of --with-ssh flag to configure and + how :extssh: uses the CVS_SSH environment variable or "ssh". + * stamp-vti, version.texi: Regenerated. + + * cvs.texinfo: Update copyright for 2008. + +2008-01-24 Mark D. Baushke <mdb@gnu.org> + + * cvs.texinfo (log options): Document the new cvs log -n + switch to reverse the -N switch. + * cvs.texinfo (annotate & rannotate): Document "blame" as a + synonym for the "annotate" command. + (Patch suggested by "David O'Brien" <obrien@FreeBSD.org>) + + * cvs.1, stamp-1, stamp-vti, version-client.texi, version.texi: + Regenerated. + +2007-05-07 Derek Price <derek@ximbiot.com> + + * cvsclient.text: Remove references to remote `init' command. + +2006-08-25 Derek Price <derek@ximbiot.com> + + * cvsclient.texi (Requests, Responses): Remove reference to the + obsolete checkin & update programs. + +2006-08-21 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (man page nodes): Tweak grammar, especially refs. + (Original patch from Kevin R. Bulgrien <kbulgrien@att.net>.) + + * mkman.pl (do_keyword): Process ref and p?xref differently. + (Original patch from Kevin R. Bulgrien <kbulgrien@att.net>.) + +2006-08-11 Mark D. Baushke <mdb@gnu.org> + + * cvs.texinfo, cvsclient.texi: Fix some typos. + (inspired by Ralf Wildenhues <Ralf.Wildenhues@gmx.de>) + +2006-07-16 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (File permissions): Correct punctuation. + +2006-07-11 Larry Jones <lawrence.jones@ugs.com> + + * cvs.texinfo (log options): -b is a revision selection option, not + a header field option. + +2006-06-22 Larry Jones <lawrence.jones@ugs.com> + + * cvs.texinfo (user-defined logging, Informing others): Remove + references to the obsolete -i module option. + +2006-06-08 Derek Price <derek@ximbiot.com> + + * cvsclient.texi (Requests): Add Empty-conflicts. + +2006-03-20 Mark D. Baushke <mdb@gnu.org> + + [patch #4965] + * cvs.texinfo (Sticky tags, Merging and keywords) + (checkout options, update options): The -A switch + does not reset sticky -k options on modified files. + * cvs.1, stamp-1, stamp-vti, version.texi: Regenerated. + +2006-02-28 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Editing administrative files): Import changes from Wiki. + +2005-12-09 Derek Price <derek@ximbiot.com> + + [patch #4634] + * cvsclient.texi (Root request): Clarify. + +2005-11-10 Larry Jones <lawrence.jones@ugs.com> + + * cvs.texinfo (Common options): -n no longer applies to commit. + (commit): Remove reference to the defunct -n option. + * cvs.1, stamp-vti, version.texi: Regenerated + +2005-10-12 Derek Price <derek@ximbiot.com> + + * cvs.texinfo: Remove text that created unintentional cross-references + in generated info files. + +2005-10-04 Derek Price <derek@ximbiot.com> + + * cvs.texinfo: s/visa versa/vice versa/. (From Wiki.) + +2005-09-26 Derek Price <derek@ximbiot.com> + + * Makefile.am (cvs-paper.ps, cvs-paper.pdf): Remove implicit sources. + Add comments about why implicit rules won't work for these targets. + Make sure the distributed cvs-paper.pdf is created in $(srcdir). Make + cvs-paper.pdf directly from cvs-paper.ms to avoid building it just + because cvs-paper.ps is missing. + + * Makefile.am (EXTRA_DIST): Restore PDFs. + * cvs-paper.ps: Removed. + * texinfo.tex: Update from GNULIB. + +2005-09-25 Derek Price <derek@ximbiot.com> + + * Makefile.am (doc): Finish removing PSs. + + * Makefile.am (EXTRA_DIST): Remove PDFs too until errors go away. + + * Makefile.am (EXTRA_DIST): Dist PDFs rather than PSs. + +2005-09-22 Larry Jones <lawrence.jones@ugs.com> + + * cvs.texinfo (rdiff options): Document -k. + * cvs.1, stamp-vti, version.texi: Regenerated. + +2005-09-20 Larry Jones <lawrence.jones@ugs.com> + + * cvs.texinfo: Move summary and detail contents to the front + where they belong. + +2005-09-14 Derek Price <derek@ximbiot.com> + + * Makefile.am: s#cvs.1#$(srcdir)/cvs.1#. + +2005-09-11 Larry Jones <lawrence.jones@ugs.com> + + * cvs.texinfo (Common options): Note that -r branch for a revision + means the head of the branch. + +2005-09-10 Larry Jones <lawrence.jones@ugs.com> + + * cvs.texinfo (Error messages): Add suggested messages. + +2005-09-09 Larry Jones <lawrence.jones@ugs.com> + + * cvs.texinfo (Error messages): Add signal 11 message. + +2005-09-01 Derek Price <derek@ximbiot.com> + + * cvs.man.footer: Update links. + +2005-09-01 Derek Price <derek@ximbiot.com> + + * cvs.texinfo: Update links and email addresses. + +2005-08-29 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (From scratch): Add checkout to import example, from + wiki. + +2005-08-29 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Removing directories): Correct grammar, from wiki. + +2005-08-29 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (From scratch): Clarify note on `cvs add', inspired from + wiki. + +2005-08-22 Derek Price <derek@ximbiot.com> + + Address bug #13882, submitted by Fred Maranhao. + * cvs.texinfo (log options, admin options, Invoking CVS): Add cross + references for clarity about possible states. + +2005-08-22 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Updating a file): Add note about update -d, inspired by + wiki. + +2005-08-12 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (What is CVS?): Rephrase for clarity, imported from + Wiki. + +2005-08-02 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (What is CVS?, BUGS): s/cvshome/nongnu/. Remove + obsolete Pascal Molli link. + +2005-06-22 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Builds): Update Gunnar Tornblom's email at his request. + +2005-05-03 Derek Price <derek@ximbiot.com> + + * cvsclient.texi (Goals): Remove typo. Resolves cvshome issue #236. + +2005-05-03 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Creating a repository): Provide xref to the remote + repositries section. Resolves issue #203 on cvshome.org. + +2005-05-03 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Moving directories): Clarify instructions on renaming a + directory. Partially resolves issue #246 on cvshome.org. + +2005-05-03 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (update output): Use "working directory" in place of + "source" for clarity. Closes issue #245 on cvshome.org. + +2005-04-28 Derek Price <derek@ximbiot.com> + + * mkman.pl: Minor changes to accomodate Perl 5.8.4. Improve + commenting. + ($nk, $ret, $debug): New globals. + (debug_print): New function. + +2005-04-14 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Administrative files): Add "Trigger Scripts" node to + the menu. + (Trigger Scripts, Trigger Script Security): New nodes. + (syntax): Move under Trigger scripts node. + (commit files, taginfo): Rewrite to reference Trigger Script node. + +2005-04-06 Derek Price <derek@ximbiot.com> + + * Makefile.am (MAINTAINERCLEANFILES): Add cvs.1. + (cvs.1): Create intermediate file so that the original isn't emptied on + error. + +2005-01-31 Derek Price <derek@ximbiot.com> + + * Makefile.am, cvs.man.header, cvs.texinfo: Update copyright notices. + +2005-01-29 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (log options): Note quirky interaction of log options. + (Suggestion from Dan Peterson <dbpete@aol.com>.) + +2004-10-29 Mark D. Baushke <mdb@cvshome.org> + + * cvs.texinfo (Common options): The -r TAG option works with + the cvs annotate command. + (Original patch from Ville Skytta <scop@cvshome.org>.) + +2004-09-25 Derek Price <derek@ximbiot.com> + + * mkman.in: Move to... + * mkman.pl: ...here. + * Makefile.am (cvs.1): mkman is in build dir, not src dir. + +2004-07-17 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Update imports, import): Add notes on requirement that + release tags be unique. + (Original patch from Ilya N. Golubev <gin@mo.msk.ru>.) + +2004-06-10 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (commit files): Remove reference to the obsolete -i + module option. + +2004-05-28 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Global options): Remove reference to global -l option. + (Report from Kevin Bulgrien <Kevin.Bulgrien@TriPointGlobal.com>.) + +2004-05-14 Mark D. Baushke <mdb@cvshome.org> + + * cvs.texinfo: Fix makeinfo error. + + * cvs.texinfo (Adding files): Minor cleanup. + (Using keywords): Minor cleanup. + (annotate): Move into the manual section, split into three nodes. + (annotate options): New node. + (annotate example): New node. + (based on patch from Steve McIntyre <steve@einval.com>.) + (Locks, GSSAPI authenticated): Minor cleanup. + (Sticky tags): Clarify operation. + (Locks): Spelling fix. + (Merging adds and removals): Ditto. + (Invoking CVS): Ditto + (Builds): Grammar fix. + (Line group formats): Ditto + (Line group formats, Line formats): Ditto + (commit files): Ditto. + * cvs.1, stamp-vti, version.texi: Regenerated + +2004-05-12 Derek Price <derek@ximbiot.com> + + * mkman.in: Clarify status messages. + +2004-05-10 Derek Price <derek@ximbiot.com> + + * mkman.in: Organize & tidy comments. Check for unprocessed texinfo + commands. Output better error messages on finding unprocessed texinfo + commands. + (do_keyword, keyword_mode): Accept $file argument for error messages. + +2004-05-06 Derek Price <derek@ximbiot.com> + + * mkman.in: Require Perl 5.005. Add comments. Remove duplicate s///. + Handle @:. + +2004-05-06 Derek Price <derek@ximbiot.com> + + * cvs.man.header: Minor text correction. + * mkman.in: Ignore @need keyword. Restore previous font for nested + keywords. + (do_keyword): Ditto on fonts. Move some functionality to... + (keyword_mode): ...this new function. + +2004-05-06 Derek Price <derek@ximbiot.com> + + * mkman.in: Handle keywords that cross multiple lines. + (do_keyword): New function. + +2004-05-04 Derek Price <derek@ximbiot.com> + + * cvs.man.header, cvs.man.footer: Reference `info CVS' rather than + `info cvs' to send users to the top node. + +2004-05-03 Derek Price <derek@ximbiot.com> + + * Makefile.am: mkman is built in the build dir, not $(srcdir). + (Report from Mark D. Baushke <mdb@cvshome.org>.) + +2004-05-03 Derek Price <derek@ximbiot.com> + + * HACKING.DOCS: Fix spelling error. Add reference for @strong. + (Report from Mark D. Baushke <mdb@cvshome.org>.) + + * HACKING.DOCS: Note dependency on `makeinfo' 3.11 & greater. + +2004-04-30 Derek Price <derek@ximbiot.com> + + * mkman.in: Handle single quotes better. Parse out some redundancy + from node and section names. + * cvs.man.footer: Replace some quotes with the usual bold font. + Reformat links in the SEE ALSO section. + * cvs.1: Regenerated. + +2004-04-30 Derek Price <derek@ximbiot.com> + + * mkman.in: Handle examples better. Protect a few more characters. + * cvs.1, stamp-vti, version.texi: Regenerated. + +2004-04-30 Derek Price <derek@ximbiot.com> + + * cvs.man.header: Add copyright notice. + * cvs.1: Regenerated. + +2004-04-30 Derek Price <derek@ximbiot.com> + + * mkman.in: Add copyright and license notice. + +2004-04-30 Derek Price <derek@ximbiot.com> + + * mkman.in: Handle @@. + * cvs.1: Regenerated. + +2004-04-30 Derek Price <derek@ximbiot.com> + + First pass at closing issue #3 on cvshome.org. + * .cvsignore: Ignore mkman. + * cvs.1, mkman.in, cvs.man.header, cvs.man.footer: New files. + * cvs.texinfo: Add cut tags for mkman. + * Makefile.in (man_MANS): Add cvs.1. + (EXTRA_DIST): Add cvs.man.header & cvs.man.footer. + (cvs.1, mkman): New targets. + * Makefile.in: Regenerated. + +2004-04-23 Derek Price <derek@ximbiot.com> + + * cvs.texinfo: Update years in Copyright. + * stamp-vti, version.texi: Regenerated. + +2004-04-21 Derek Price <derek@ximbiot.com> + + * cvs.texinfo: Use splitrcskeyword macro consistently in a failed + attempt to avoid a warning during PDF generation. + * stamp-vti, version.texi: Regenerated. + +2004-04-18 Derek Price <derek@ximbiot.com> + + * cvs.texinfo: Various spelling, typo, and capitalization fixes. + (Patch from Ville Skyttä <scop@cvshome.org>.) + +2004-04-06 Larry Jones <lawrence.jones@ugsplm.com> + + * cvs.texinfo (Assigning revisions): Note that client/server mode + only considers files sent to the server to determine the major + revision for new files. + (Reported by Krzysztof GORBIEL <Krzysztof_GORBIEL@raiffeisen.pl>.) + * stamp-vti, version.texi: Regenerated. + +2004-03-15 Derek Price <derek@ximbiot.com> + + * stamp-vti, version.texi: Regenerated. + +2004-03-11 Larry Jones <lawrence.jones@ugsplm.com> + + * cvs.texinfo (loginfo, Error messages): Note that not reading all of + the log info can result in a broken pipe signal. + (Reported by Steven Nicoloso <spn@nwmail.wh.lucent.com>.) + * stamp-vti, version.texi: Regenerated. + +2004-02-04 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (File Permissions): Clarify index entry. + * stamp-vti, version.texi: Regenerated. + +2004-01-22 Derek Price <derek@ximbiot.com> + + * stamp-vti, version.texi: Regenerated. + +2004-01-08 Larry Jones <lawrence.jones@ugsplm.com> + + * cvs.texinfo (user-defined logging): Move taginfo stuff from here... + (Administrative files): ...to its own node under here. + +2003-12-18 Derek Price <derek@ximbiot.com> + + * stamp-1, stamp-vti, version-client.texi, version.texi: Regenerated + for 1.11.11.1. + +2003-12-18 Derek Price <derek@ximbiot.com> + + * stamp-1, stamp-vti, version-client.texi, version.texi: Regenerated + for 1.11.11. + +2003-12-05 Derek Price <derek@ximbiot.com> + + * stamp-1, stamp-vti, version-client.texi, version.texi: Regenerated. + +2003-12-04 Derek Price <derek@ximbiot.com> + + * stamp-1, stamp-vti, version-client.texi, version.texi: Regenerated + for 1.11.10.1. + +2003-12-04 Derek Price <derek@ximbiot.com> + + * stamp-1, stamp-vti, version-client.texi, version.texi: Regenerated + for 1.11.10. + +2003-11-18 Derek Price <derek@ximbiot.com> + + * stamp-vti, version.texi: Regenerated. + +2003-11-13 Larry Jones <lawrence.jones@eds.com> + + * cvs.texinfo (Reverting local changes): Use the same vendor tag + in the admin command as was used in the previous import commands. + +2003-11-10 Derek Price <derek@ximbiot.com> + + * stamp-vti, version.texi: Regenerated. + +2003-11-07 Mark D. Baushke <mdb@cvshome.org> + + * cvs.texinfo (CVS commands): Fix typo. + (FreeBSD PR docs/58669 reported by Ceri Davies <ceri@FreeBSD.org>.) + +2003-10-30 Derek Price <derek@ximbiot.com> + + * stamp-vti, version.texi: Regenerated. + +2003-10-30 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (File permissions, Error messages): Add index entries for + CVSROOT/val-tags file. + +2003-10-21 Derek Price <derek@ximbiot.com> + + * cvs.texinfo: Note gnu.cvs.* usenet mirrors of the email lists. + (Suggestion from Paul Edwards, from somewhere in Australia.) + + * cvs.texinfo: Put email addresses in @email{} tags and URLs in @url{} + tags rather than relying on markup like @code{}. + * stamp-vti, version.texi: Regenerated. + +2003-10-14 Derek Price <derek@ximbiot.com> + + * stamp-vti, version.texi: Regenerated. + +2003-10-14 Derek Price <derek@ximbiot.com> + + Port to pedantic POSIX 1003.1-2001 hosts, such as Debian GNU/Linux + testing with _POSIX2_VERSION=200112 in the environment. + + * cvs.texinfo: Suggest 'sed 1q', not 'head -1'. + (Patch from Paul Eggert <eggert@twinsun.com>.) + +2003-10-10 Derek Price <derek@ximbiot.com> + + * stamp-1, stamp-vti, version-client.texi, version.texi: Regenerated + for 1.11.9.1. + +2003-10-10 Derek Price <derek@ximbiot.com> + + * stamp-1, stamp-vti, version-client.texi, version.texi: Regenerated + for 1.11.9. + +2003-10-06 Derek Price <derek@ximbiot.com> + + * cvsclient.texi (Requests): Add recommendation to client developers to + avoid the `Case' request. + * stamp-1, version-client.texi: Regenerated. + +2003-10-02 Derek Price <derek@ximbiot.com> + + * stamp-1, stamp-vti, version-client.texi, version.texi: Regenerated + for 1.11.8.1. + +2003-10-02 Derek Price <derek@ximbiot.com> + + * stamp-1, stamp-vti, version-client.texi, version.texi: Regenerated + for 1.11.8. + +2003-09-29 Derek Price <derek@ximbiot.com> + + * stamp-1, stamp-vti, version-client.texi, version.texi: Regenerated + for 1.11.7.1. + +2003-09-29 Derek Price <derek@ximbiot.com> + + * stamp-1, stamp-vti, version-client.texi, version.texi: Regenerated + for 1.11.7. + +2003-09-12 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (checkoutlist): Document the error messages which may be + specified in this file. + * stamp-vti, version.texi: Regenerated. + +2003-08-27 Larry Jones <lawrence.jones@eds.com> + + * cvs.texinfo (history options): Note the 'P' record type which + has been around for a long time but never actually appeared in + the history file due to bugs in the code. + (Invoking CVS): Ditto. + (config): Ditto. + * stamp-vti, version.texi: Regenerated. + +2003-08-07 Derek Price <derek@ximbiot.com> + + * .cvsignore: Ignore {cvs,cvsclient}.txt. + +2003-08-07 Derek Price <derek@ximbiot.com> + + * cvs.texinfo: Use the @dircategory and @direntry commands from texinfo + rather than rolling our own. + + * stamp-vti, version.texi: Regenerated. + +2003-08-07 Derek Price <derek@ximbiot.com> + + * Makefile.am (POSTSCRIPTS): Rename to... + (PSS): ...to sync with and override Automakes default targets. + (PDFS): Reorder to match PSS. + (SUFFIXES): Remove .pdf and .aux. + (cvs.aux, cvs.pdf, cvsclient.aux, cvsclient.pdf): Remove these targets. + .aux weren't being generated anyhow and .pdf no longer need to be + supplied explicitly. + (cvs-paper.pdf: cvs-paper.ps): Provide ps2pdf rule explicitly. + (.{texinfo,texi,txy}.pdf): Remove these suffix rules - they are now + provided by Automake. + +2003-08-06 Derek Price <derek@ximbiot.com> + + * Makefile.am (CLEANFILES): Move... + (MOSTLYCLEANFILES): ...here and drop PDFs since this is where Automake + cleans PDFs & PSs by default. + (MAINTAINERCLEANFILES): Clean all PostScripts even though they will + have been removed in mostlyclean. That is a bug in Automake. + (doc): Depend on info & ps. + (pdf, ps): Removed in favor of Automake's default targets for these + types. + (cvsclient.* targets): Depened on version-client.texi. + (cvs-paper.pdf): Remove in favor of Automake's default target. + (.{texinfo,texi,txi}.{pdf,txt}): Update these targets based on + Automake's similar treatment of dvi, ps, and info targets. + * .cvsignore: Add cvs.tmp, a `make pdf' generated file. + + * Makefile.in: Regenerated. + +2003-07-18 Derek Price <derek@ximbiot.com> + + * cvs.texinfo: Put a few errant references to bug-cvs inside @code{} + for consistancy. + +2003-07-18 Derek Price <derek@ximbiot.com> + + * cvs.texinfo: Update WARNINGs and Notes for a more consistent + appearance. Remove some obsolete comments. + * stamp-vti: Regenerated. + * version.texi: Regenerated. + +2003-07-12 Larry Jones <lawrence.jones@eds.com> + + * cvs.texinfo (Binary howto): Add note about how to determine whether + a file is marked as binary or not. + (Suggested by Erik Sigra <sigra@home.se>.) + * stamp-vti: Regenerated. + * version.texi: Regenerated. + +2003-06-23 Derek Price <derek@ximbiot.com> + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2003-06-16 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (splitrcskeyword): New macro, now that @ifhtml will work + properly with texi2html (as of version 1.68), to cause output HTML to + contain <i></i> where we used to have @asis{} and prevent RCS keyword + substitution in generated HTML. + (Original patch from Patrice Dumas <dumas@centre-cired.fr>.) + +2003-06-11 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Invoking CVS): Remove `-P' from the list of `cvs export' + options. + (Patch from Alexander Taler <dissent@cvshome.org>.) + +2003-06-11 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Top): Remove out-of-date (by at least 5 years) comment. + (Patch from Alexander Taler <dissent@cvshome.org>.) + +2003-05-27 Derek Price <derek@ximbiot.com> + + * cvs.texinfo: Consolidate copyright notices into a single macro that + is called elsewhere to avoid needing three of them. Update copyright + notice. + (BUGS): Suggest Ximbiot rather than the defunct Signum Support as CVS + consultants. + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2003-05-26 Derek Price <derek@ximbiot.com> + + * stamp-1: Regenerated for 1.11.6.1. + * stamp-vti: Ditto. + * version-client.texi: Ditto. + * version.texi: Ditto. + +2003-05-25 Derek Price <derek@ximbiot.com> + + * stamp-1: Regenerated for 1.11.6. + * stamp-vti: Ditto. + * version-client.texi: Ditto. + * version.texi: Ditto. + +2003-05-21 Derek Price <derek@ximbiot.com> + + * Makefile.in: Regenerate with Automake version 1.7.5. + +2003-04-28 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Working directory storage, Module options, Module + program options): Remove references to Checkin.prog and Update.prog. + (commit options): Remove reference to -n option. + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2003-04-10 Larry Jones <lawrence.jones@eds.com> + + * Makefile.in: Regenerated. + +2003-03-26 Derek Price <derek@ximbiot.com> + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2003-03-25 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Server temporary directory): Reorder list of places + to match code. + (Connection): Add additional example error message and note about + firewall software. + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2003-03-24 Derek Price <derek@ximbiot.com> + + * Makefile.am: Update copyright notice. + + * Makefile.in: Regenerated. + +2003-03-06 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (What is CVS?): Correct date of first post of CVS by + Dick Grune from December to July based on the archive posted on + Google: + <http://groups.google.com/groups?q=Grune+cvs+group:mod.sources.*&hl=en&lr=&ie=UTF-8&selm=122%40mirror.UUCP&rnum=2>. + (Thanks to David A Wheeler <dwheeler@dwheeler.com>.) + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2003-03-05 Mark D. Baushke <mdb@cvshome.org> + + * cvs.texinfo (CVS_LOCAL_BRANCH_NUM): Backout CVS_LOCAL_BRANCH_NUM + feature. + + * cvs.texinfo (CVS_LOCAL_BRANCH_NUM): Document new environment + variable. + +2003-02-27 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Environment variables): Make the information on + CVS_CLIENT_PORT slightly clearer. + (Kerberos authenticated): XREF the Environment variables node. + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2003-02-25 Derek Price <derek@ximbiot.com> + + * Makefile.in: Regenerated. + * stamp-1: Ditto. + * version-client.texi: Ditto. + +2003-02-06 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Working directory storage, Module options, + Module program options): Correct description of where Checkin.prog + and Update.prog are run. Provide more index entries and cross + references. Remove some FIXME comments. Add a FIXCVS THEN FIXME. + (Thanks to Art Manion at the CERT Coordination Center <cert@cert.org>.) + +2003-02-04 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (File status): Mention the "Unresolved Conflict" status + which was apparently and erroneously removed from the doc at some + point in the past. + +2003-02-03 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Merging a branch): Mention the GCA as opposed to the + "branch point" as the implicit revision when merging a branch. + +2003-02-03 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Remote repositories): :METHOD: is optional. + +2003-02-03 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Committing your changes): Move index entries closer to + their corresponding references. + (Environment variables): Include $VISUAL in order of + preference. Add index entries. Reference Global options node. + (Variables): Change order of list to match the Env. Variables node + mentioned above. + + * stamp-1: Regenerated. + * stamp-vti: Ditto. + * version-client.texi: Ditto. + * version.texi: Ditto. + +2003-02-14 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Watch Information, Editing files, Getting Notified, + Setting a watch): Edit usage specs for correctness and uniformity. + (Sticky tags): Use ref rather than xref to avoid a warning from + makeinfo. + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2003-01-23 Derek Price <derek@ximbiot.com> + + * stamp-1: Regenerated. + * stamp-vti: Ditto. + * version-client.texi: Ditto. + * version.texi: Ditto. + +2003-01-22 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (config): Correct LogHistory default (U was omitted). + +2003-01-16 Derek Price <derek@ximbiot.com> + + * stamp-1: Regenerated for version (1.11.5). + * stamp-vti: Ditto. + * version-client.texi: Ditto. + * version.texi: Ditto. + +2003-01-16 Derek Price <derek@ximbiot.com> + + * stamp-1: Regenerated for dev version (1.11.4.1). + * stamp-vti: Ditto. + * version-client.texi: Ditto. + * version.texi: Ditto. + +2002-12-28 Derek Price <derek@ximbiot.com> + + * stamp-1: Regenerated for version 1.11.4. + * stamp-vti: Ditto. + * version-client.texi: Ditto. + * version.texi: Ditto. + +2002-12-27 Derek Price <derek@ximbiot.com> + + * stamp-1: Regenerated for dev version 1.11.3.1. + * stamp-vti: Ditto. + * version-client.texi: Ditto. + * version.texi: Ditto. + +2002-12-27 Derek Price <derek@ximbiot.com> + + * stamp-1: Regenerated. + * stamp-vti: Ditto. + * version-client.texi: Ditto. + * version.texi: Ditto. + +2002-11-18 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (commitinfo): Explain the environment of commands + run by commitinfo a little more fully. + (Original patch from Fred L. Drake, Jr. <fdrake@acm.org>.) + + * cvs.texinfo: Change the wording of some of the commit index entries + for consistency and clarity. + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2002-09-24 Derek Price <derek@ximbiot.com> + + * Makefile.in: Regenerated using Automake 1.6.3. + +2002-09-24 Derek Price <derek@ximbiot.com> + + * Makefile.in: Regenerated. + +2002-09-20 Derek Price <derek@ximbiot.com> + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2002-08-16 Derek Price <derek@ximbiot.com> + + * cvs.texinfo (Error messages): Update CVS_BADROOT notes to specify + new configure option instead. + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2002-08-12 Derek Price <oberon@umich.edu> + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2002-08-06 Derek Price <oberon@umich.edu> + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2002-08-05 Derek Price <oberon@umich.edu> + + * cvs.texinfo: Correct typo. + (Thanks to Chandra Mouleeswaran <chandra@openharbor.com>.) + +2002-04-30 Derek Price <oberon@umich.edu> + + * Makefile.in: Regenerated with automake 1.6. + +2002-04-18 Derek Price <oberon@umich.edu> + + * Makefile.am: Add FIXME comment about an automake bug. + * Makefile.in: Regenerated. + +2002-04-18 Derek Price <oberon@umich.edu> + + * stamp-1: Regenerated for 1.11.2.1 version update. + * stamp-vti: Ditto. + * version-client.texi: Ditto. + * version.texi: Ditto. + +2002-04-17 Derek Price <oberon@umich.edu> + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2002-04-17 Derek Price <oberon@umich.edu> + + * cvs.texinfo: Add index entries for inetd and xinetd. + +2002-03-26 Derek Price <oberon@umich.edu> + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2002-03-17 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (log options): Add new -S option. + +2002-03-12 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (diff options): Add missing menu for new subsections. + (Patch from Pavel Roskin <proski@gnu.org>.) + +2002-03-09 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Update imports): Suggest merging with two rel tags + instead of the branch tag and a date and explain why. + +2002-02-26 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (diff options): Document all the diff options. + +2002-01-10 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (log options): Update -r :: to match code changes. + (Variables): Document LOGNAME and USER environment variables. + +2001-12-03 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Invoking CVS): Add -F option for annotate and + rannotate. + +2001-11-28 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (File permissions): Add note about SGID being required + on some systems. Add note about LockDir. + +2001-10-18 Derek Price <dprice@collab.net> + + * Makefile.am: Add --batch to texi2dvi invocations. + (Thanks to Akim Demaille <akim@epita.fr> for the suggestion.) + + * Makefile.in: Regenerated. + +2001-10-04 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Connecting via rsh): Add : between host name and + root directory in example since some versions of CVS require it. + (Reported by Trevor Jim <trevor@research.att.com>.) + +2001-09-14 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (commit files): Make following sections (commitinfo, + verifymsg, editinfo, and loginfo) subsections of this one. + +2001-09-06 Derek Price <dprice@collab.net> + + * cvs.texinfo (Watch information): Cleanup some watch/edit + explanations and discourage the belief that files should be + releasable. + + * stamp-vti: Regenerated. + * version.texi: Ditto. + (Patch from Eric Siegerman <erics@telepres.com>.) + +2001-09-05 Derek Price <dprice@collab.net> + + * cvsclient.texi: Use version-client.texi instead of version.texi so + cvsclient.* can have a different build date than cvs.texinfo. + + * Makefile.in: Regenerated. + * stamp-1: New file. + * version-client.texi: Ditto. + (Reported by Alexey Mahotkin <alexm@hsys.msk.ru>.) + +2001-09-04 Derek Price <dprice@collab.net> + + * Makefile.in: Regenerated with automake 1.5. + * version.texi: Ditto. + +2001-08-24 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Error messages): Add new message about root not + being allowed to do commit. + +2001-08-24 Derek Price <dprice@collab.net> + + * cvs.texinfo (config): Add a new RereadLogAfterVerify + CVSROOT/config option to control how verifymsg scripts deal with + read-write log messages. + (Patch from Mark D. Baushke <mdb@cvshome.org>.) + + * cvs.texinfo (verifymsg): The verification script may now modify + the log message. + (Patch from Mark D. Baushke <mdb@cvshome.org>.) + + * cvs.texinfo (config, verifymsg): Correct default, changes for clarity, + and add a warning about `stat' and large repositories. + + * version.texi: Regenerated. + * stamp-vti: Ditto. + +2001-08-20 Derek Price <dprice@collab.net> + + * Makefile.am: Reformat comment for 80 chars. + + * Makefile.in: Regenerated. + +2001-08-10 Derek Price <dprice@collab.net> + + * cvs.texinfo (Default options and the ~/.cvsrc file): Added a few more + "standard" options to the example. + + * stamp-vti: Regenerated. + * version.texi: Ditto. + +2001-08-06 Derek Price <dprice@collab.net> + + * Makefile.in: Regenerated. + +2001-07-17 Derek Price <dprice@collab.net> + + * version.texi: Regenerated. + * stamp-vti: Ditto. + +2001-07-06 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Variables): Add index entry for CVS_USER. + (Reported by Jens Schweikhardt <Jens.Schweikhardt@marconi.com>.) + (Working directory storage): Fix Emptydir index entry: Emptydir + is a directory, not a file. + +2001-07-05 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Working directory storage): Add Emptydir to index. + +2001-07-04 Derek Price <dprice@collab.net> + + * Makefile.in: Regenerated with new Automake release candidate 1.4h. + +2001-06-28 Derek Price <dprice@collab.net> + + * Makefile.am: Reference to CVSvn.texi removed. + * cvs.texinfo: @include version.texi and change CVSVN to VERSION. + * cvsclient.texi: Ditto. + + * version.texi: New file. + * stamp-vti: Ditto. + * mdate-sh: New File. Work-around bug in Automake 1.4f by copying + top-level mdate-sh here. + + * CVSvn.texi.in: Removed. + * CVSvn.texi: Ditto. + + * Makefile.in: Regenerated. + (Patch from Alexey Mahotkin <alexm@hsys.msk.ru>.) + +2001-06-27 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (loginfo): Note that format string expansion is + quoted and contains escapes. + +2001-06-22 Derek Price <dprice@collab.net> + + * cvs.texinfo (checkout options): Fix transliteration typo in co + example. + (Patch from Adrian Aichner <adrian@xemacs.org>.) + +2001-06-12 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Global options): Note that -T only affects the local + process in client/server mode. + (Environment variables): Note that CVS_SERVER can include arguments + as well as a program name, and note that it applies to :fork: as well + as to :ext: and :server:, although the default value is different. + +2001-06-08 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (config): Mention using LockDir on in-memory + filesystem to speed up locking. + +2001-06-07 Derek Price <dprice@collab.net> + + * Makefile.am (EXTRA_DIST): Remove *.aux. + (MOSTLYCLEAN_FILES): Remove this macro since the Automake bug it was + working around has been fixed. + +2001-06-07 Derek Price <dprice@collab.net> + + * HACKING.DOCS: Add link to the main texinfo documentation. + +2001-06-07 Derek Price <dprice@collab.net> + + * README.DOCS: Rename to + * HACKING.DOCS: this. + +2001-06-07 Derek Price <dprice@collab.net> + + * README.DOCS: New file attempting to document some of our texinfo + conventions. + +2001-06-06 Derek Price <dprice@collab.net> + + (Reformatting, rewording, & additions to a patch from + Stephen Cameron <steve.cameron@compaq.com>.) + + * cvs.texinfo (Invoking cvs, Modifying tags) + document new -B option of rtag and tag commands. + +2001-06-04 Derek Price <dprice@collab.net> + + * Makefile.am: Remove commented out DISTFILES & + AUTOMAKE_OPTIONS=no-texinfo.tex. + (Reported by Alexey Mahotkin <alexm@hsys.msk.ru>.) + * Makefile.in: Regenerated. + +2001-06-04 Larry Jones <larry.jones@sdrc.com> + + * Makefile.am: Fix rules for cvs-paper (.pdf rule actually generated + .ps and vice versa). + (Reported by Alexey Mahotkin <alexm@hsys.msk.ru>.) + * Makefile.in: Regenerated. + +2001-05-29 Derek Price <dprice@collab.net> + + * cvs.texinfo (Repository): Fix explanation of CVSROOT parsing + algorithm. + +2001-05-29 Derek Price <dprice@collab.net> + patch from Pavel Roskin <proski@gnu.org> + + * Makefile.am (CVSvn.texi): Double hash comment in rule since single + hash comments are not portable. + + * Makefile.in: Regenerated. + +2001-05-21 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Error messages): Fix ordering; add "cannot commit + files as root". + + * cvs.texinfo (Invoking CVS): Add entries for kserver, pserver, + rannotate, rlog, and server. + + * cvs.texinfo: Lots of minor editorial corrections. Mostly adding + @noindent after examples where the following text is intended to + be a continuation of the preceding text, not a new paragraph. + + * cvs.texinfo (Connection): Replace information about unsetting + $HOME for people with old releases. + + + * cvs.texinfo (Connecting via rsh): Use @samp{} instead of @file{} + where it seemed appropriate. + (Patch from Alexey Mahotkin <alexm@hsys.msk.ru>). + +2001-05-18 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Password authentication server): Add xinetd info. + (Connection): Add "broken pipe" to possible error messages. + +2001-05-18 Derek Price <dprice@collab.net> + + * cvs.texinfo (update output): Change wording to something that sounds + a bit more like english. + +2001-05-02 Derek Price <dprice@collab.net> + + * cvs.texinfo (Top): Change @ifinfo to @ifnottex to placate HTML + generators. + +2001-04-27 Derek Price <dprice@collab.net> + + * CVSvn.texi: Regenerated. + +2001-04-27 Derek Price <dprice@collab.net> + + * CVSvn.texi: Regenerated. + +2001-04-25 Derek Price <dprice@collab.net> + + * Makefile.in: Regenerated using AM 1.4e as of today at 18:10 -0400. + * CVSvn.texi: Regenerated. + +2001-03-30 Larry Jones <larry.jones@sdrc.com> + + * cvsclient.texi (Dates, Requests): Add rannotate and rlog. + +2001-03-26 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (admin options): Fix typo: should be @pxref, not @xref. + +2001-03-26 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (admin options): Update description of -u option to + refer back to notify. + +2001-03-23 Derek Price <derek.price@openavenue.com> + + * Makefile.am (ps): Make 'ps' an alias for 'doc'. + (doc, pdf, ps, txt): declare as '.PHONY'. + + * Makefile.in: Regenerated. + +2001-03-23 Derek Price <derek.price@openavenue.com> + + * Makefile.am (MOSTLYCLEANFILES): Add cvs.cps & cvs.fns as a temporary + workaround for an Automake deficiency. + + * Makefile.in: Regenerated. + +2001-03-14 Derek Price <derek.price@openavenue.com> + + * Makefile.in: Regenerated + +2001-02-20 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (BUGS): There's only one company listed now, not two. + +2001-02-13 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Password authentication server, First import): Use + @ref instead of @xref when not at the beginning of a sentence. + +2001-02-01 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Connection): Add still more notes about common + pserver error messages. + +2001-01-18 Derek Price <derek.price@openavenue.com> + + * cvs.texinfo (Quick reference to CVS commands): add index entry for + version subcommand + +2001-01-18 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (log options): Document new :: syntax for -r. + +2001-01-10 Derek Price <derek.price@openavenue.com> + + * Makefile.am (CVSvn.texi): specify $(srcdir) explicitly in target rule + so CVSvn.texi gets built properly for all makes. + (cvs_TEXINFOS): specify $(srcdir) explicitly for CVSvn.texi + (cvsclient_TEXINFOS): ditto + * Makefile.in: regenerated + +2000-12-26 Derek Price <derek.price@openavenue.com> + + * Makefile.in: update timestamp + * CVSvn.texi: ditto + +2000-12-26 Derek Price <derek.price@openavenue.com> + + * Makefile.am: new target for creation of CVSvn.texi + (EXTRA_DIST): add CVSvn.texi.in & CVSvn.texi + * Makefile.in: Regenerated + * CVSvn.texi: new file + * .cvsignore: remove CVSvn.texi since it is now included in dist + +2000-12-22 Derek Price <derek.price@openavenue.com> + + * Makefile.in: Regenerated + +2000-12-21 Derek Price <derek.price@openavenue.com> + + * cvs-paper.ps: Backout accidental regeneration. + +2000-12-21 Derek Price <derek.price@openavenue.com> + + * .cvsignore: Added *.pdf versions of the *.ps docs + * CVSvn.texi.in: Use configure to generate CVSvn.texi + * Makefile.am: New file needed by Automake + * Makefile.in: Regenerated + * cvs-paper.ps: Regenerated + * texinfo.tex: New file added to placate Automake. Apparently, its + inclusion is mandated by the GNU coding standards. + +2000-12-14 Derek Price <derek.price@openavenue.com> + Linus Tolke <linus@epact.se> + + * cvs.texinfo (Merging a branch): changed some references to "BRANCH" + to "BRANCHNAME" for consistancy. Add a warning about merging using a + single tagname reference with an xref to "Merging adds and removals" + for the long explanation + (Merging adds and removals): Add the long explanation of why merging + from a single tagname can be tricky + (update): Add a warning about merging using a single tagname reference + with an xref to "Merging adds and removals" for the long explanation + +2000-11-13 Derek Price <derek.price@openavenue.com> + + * cvs.texinfo: use '@sc{cvs}' instead of 'CVS' in various locations + +2000-11-08 Derek Price <derek.price@openavenue.com> + + * cvs.texinfo (settitle): stick a 'v' in front of the version number + to make it harder to confuse with chapter, section, and page numbers. + +2000-11-08 Derek Price <derek.price@openavenue.com> + + * cvs.texinfo (settitle): add the version number to the title string + so that it is easier to find on HTML pages and the like. + +2000-10-20 Jim Kingdon <http://sourceforge.net/users/kingdon/> + + * cvs.texinfo (Variables): Document CVS_USER. + +2000-10-17 Derek Price <derek.price@openavenue.com> + + * cvs.texinfo (Remote repositories): added a comment about specifying + a password in the repository name when performaing a checkout. + +2000-10-17 Derek Price <derek.price@openavenue.com> + + * cvs.texinfo (Remote repositories, password authenticated, GSSAPI + authenticated, Kerberos authenticated, Environment variables): + Documented CVSROOT spec change & CVS_CLIENT_PORT. + +2000-10-10 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Connection): Add additional notes about common + pserver error messages. Remove information about unsetting $HOME + since CVS no longer pays any attention to it in server mode. + +2000-09-07 Larry Jones <larry.jones@sdrc.com> + + * Makefile.in: Use @bindir@, @libdir@, @infodir@, and @mandir@ + from autoconf. + +2000-08-21 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Removing directories, export): Note that export always + prunes directories and remove references to the non-existent -P flag. + +2000-07-28 Larry Jones <larry.jones@sdrc.com> + + * cvsclient.texi (Requests): Ensure that all rootless requests say + that they're rootless. + +2000-07-12 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Module program options): Remove note that commit and + update programs only working locally; they've worked client/server + for quite some time. + +2000-07-10 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Invoking CVS): Document new version command. + * cvsclient.texi (Requests): Document new version request. + +2000-07-06 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (admin options): Remove note about -t not working + in client/server. + +2000-04-03 Pavel Roskin <pavel_roskin@geocities.com> + + * cvs.texinfo (Telling CVS to notify you): Remove backslashes + before quotes. + +2000-05-24 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (From files): Clean up @var{wdir}/@var{rdir} vs. + @var{dir} usage. + +2000-05-19 Larry Jones <larry.jones@sdrc.com> + + * cvsclient.texi (Requests): Note that Global_option is now + valid without Root. + +2000-04-17 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Variables): Clarify what USER means in pserver. + +2000-03-08 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Connection): Add note about inetd rate limit. + (ErrorMessages): Add root home directory permission messages. + +2000-02-12 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo: Clean up text/formatting of previous change. + +2000-02-21 K.J. Paradise <kj@sourcegear.com> + + * cvs.texinfo : Adding John Cavanaugh's patch to allow + the history file to log actions based on the CVSROOT/config + file. (To limit which cvs actions actually make it into the + history file) + +2000-02-17 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo: Remove references to PreservePermissions. + + * cvs.texinfo (history options): Note default report type. + +2000-01-18 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Global options): Document compression levels. + +2000-01-18 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo: Minor editorial changes from Ken Foskey + <waratah@zip.com.au>. + +2000-01-11 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo: Add index entries for "Compression" and "Gzip". + Correct typography in many index entries (English phrases should + have initial caps, subcommands/files/etc. should be as-is). + +2000-01-10 Karl Fogel <kfogel@red-bean.com> + + * cvs.texinfo (loginfo): correctly describe CVSROOT/loginfo's + %-expansion behavior. Thanks to Karl Heinz Marbaise + <kama@hippo.fido.de> for noticing the error. + +2000-01-07 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Password authentication server): Use -f in example + inetd.conf line. + (Connection): Add advice about using shell script or env to avoid + problems with inetd setting HOME in the server's environment. + (various): Use @file for inetd.conf. + +2000-01-02 John P Cavanaugh <cavanaug@sr.hp.com> + + * cvs.texinfo: document new -C option to update, now that it works + both remotely and locally. + (Re-applied by Karl Fogel <kfogel@red-bean.com>.) + +1999-12-11 Karl Fogel <kfogel@red-bean.com> + + * Revert previous change -- it doesn't work remotely yet. + +1999-12-10 John P Cavanaugh <cavanaug@sr.hp.com> + + * cvs.texinfo: document new -C option to update. + (Applied by Karl Fogel <kfogel@red-bean.com>.) + +1999-11-20 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo(history options): Document -f, -n, and -z. + +1999-11-09 Jim Kingdon <http://developer.redhat.com/> + + * cvsclient.texi (Requests): Document the arguments to "log", now + that I've changed log.c to be more specific in terms of what it + will send. + +1999-11-05 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo: Revert Karl's change once again since the code is now + fixed. Add "Variables" and "User variables" to index. + +1999-11-04 Karl Fogel <kfogel@red-bean.com> + + * log.c (log_usage): Revert Jim Kingdon's reversion of my change + of 1999-11-03. Allowing a space between option and argument + results in lossage; here is a reproduction recipe: run this from + the top of a remote copy of the cvs source tree + + cvs log -d '>1999-03-01' > log-out.with-space + + and then run this (note there's no space after -d now): + + cvs log -d'>1999-03-01' > log-out.no-space + + The resulting files differ; furthermore, a glance at the output of + cvs shows that the first command failed to recurse into + subdirectories. Until this misbehavior can be fixed in the source + code, the documentation should reflect the true state of affairs: + if one simply omits the space, everything works fine. + +1999-11-04 Jim Kingdon <http://developer.redhat.com/> + + * cvs.texinfo (log options): Revert Karl's change regarding -d and + -s. A space is allowed (see sanity.sh for example). + + * cvs.texinfo (Password authentication server): The name of the + file is "passwd" not "password". + + * cvsclient.texi (Top): Add @dircategory and @direntry. + +1999-11-04 Karl Fogel <kfogel@red-bean.com> + + * cvs.texinfo (Password authentication server, Password + authentication client): Rewritten to accommodate the [new] + possibility of empty passwords. + +1999-11-03 Karl Fogel <kfogel@red-bean.com> + + * cvs.texinfo (Invoking CVS): correct documentation for -d and -s + options (as did elsewhere, earlier today). + +1999-11-03 Karl Fogel <kfogel@red-bean.com> + + * cvs.texinfo (Setting a watch): describe `watch off' behavior + more accurately. + +1999-11-03 Karl Fogel <kfogel@red-bean.com> + + * cvs.texinfo (log options): correct documentation for -d and -s + options. There can be no space between these options and their + arguments. + + Also, make sure all @sc{cvs} codes refer to "cvs" in lower case; + this avoids makeinfo warnings. And use @code for the CVSEDITOR + environment variable, not @sc. + +1999-09-24 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo: Misc. formatting cleanups. + +1999-07-16 Tom Tromey <tromey@cygnus.com> + + * cvs.texinfo (admin): Mention admin -k exception. Add cvsadmin + to index. + +1999-07-14 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo (Password authentication server): Note inetd limits + and suggest using shell script to avoid. + +1999-06-01 Jim Kingdon <http://www.cyclic.com> + + * cvsclient.texi (Requests): For the import command, the + repository given to the Directory requests is ignored. + +1999-05-27 Jim Kingdon <http://www.cyclic.com> + + * cvsclient.texi (Requests): Clarify that Modified, Is-modified, + Notify and Unchanged must specify a file within the current + directory. + +1999-05-24 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (checkoutlist): New node, contains more complete + documentation of this feature. + (CVSROOT storage): Refer to the new node when mentioning + checkoutlist. + (Administrative files): Update the menu entry for Wrappers. + +1999-05-17 Jim Kingdon <http://www.cyclic.com> + + * cvsclient.texi (Requests): For Notify request, strike duplicate + "Response expected: no" and fix "a edit" -> "an edit". + +1999-05-14 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (Working directory storage): Try to be more clear + about the conflict field. + +1999-05-11 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (config): Use comma after @xref (thanks to Pavel + Roskin for the report/fix). + +1999-05-10 Jim Kingdon <http://www.cyclic.com> + + * cvsclient.texi (Requests): Document restrictions on characters + in Notify requests. + +1999-05-04 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (Password authentication security): Remove sentence + about how no one has audited pserver for holes; a lot of holes + have been closed, looking for, &c, since that was written. + In the summary, reword to reflect the fact that sniffing a + readonly password does not imply general system access (as far as + I know, of course). + + * cvs.texinfo (Connection): Also suggest inetd -d. + +1999-04-28 Jim Kingdon <http://www.cyclic.com> + + * cvsclient.texi (Requests): Say what goes in the "watches" field + of the "Notify" request. + + * cvs.texinfo (Common options): -r is for branches too. + + * cvs.texinfo (Error messages): Add "no such tag" message. + (Common options): -f does not override val-tags check. + +1999-04-26 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (Locks): #cvs.rfl locks must start with "#cvs.rfl." + not just "#cvs.rfl". As far as I know CVS has always implemented + the former behavior, and this just fixes the documentation. + +1999-04-23 Yoshiki Hayashi of u-tokyo.ac.jp + + * cvs.texinfo (verifymsg): Correct wrong file name (bugid.edit -> + bugid.verify). + +1999-04-22 Jim Kingdon <http://www.cyclic.com> + + * cvsclient.texi (Responses): The text in the "M" response is not + designed for machine parsing. Likewise for "error" in regular + protocol. Likewise for "E" and "error" in authentication protocol. + +1999-04-19 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (Error messages): Add "Cannot check out files into + the repository itself". + +1999-04-16 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (Other problems): Add the Windows problem with home + directory ending in a slash. + +1999-04-14 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (CVS in repository): Include the format of the + fileattr file here, rather than referring to the CVS source code. + +1999-04-09 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (Working directory storage): Whether the timestamp + in CVS/Entries is local or universal actually depends on the system. + +1999-04-05 Derek Price + <http://www-personal.engin.umich.edu/~oberon/resume.html> + + * cvs.texinfo (export options): Remove notation that the -r + tag is sticky. 'cvs export' doesn't store that data. + +1999-04-08 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (Error messages): Add "EOF in RCS file" and + "unexpected EOF" (in RCS file) messages. + +1999-03-25 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (admin options): Say there can be no space between + -e and its argument (since the previous sentence said the argument + can be omitted, this is the only possibility). + +1999-02-26 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (Merging and keywords): When including conflict + markers, put @asis{} at the start of the line, in case this file + itself is in CVS. Thanks to Derek Price for pointing this out. + +1999-02-25 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo: Refer to "keywords" not "RCS keywords". We had + only used the latter term in a few places, and it seems like a + somewhat odd term in that this style of keyword is by no means + specific to RCS. + (Merging a branch): Remove spurious ")". Use ref, not xref, after + "see". + (Merging a branch, Substitution modes): Make sure that @ref is + followed by comma, since info wants that. + (Merging and keywords): Use samp not code for "-kk". Something of + a judgement call, but the rest of the manual uses samp and that + seems better to me. + (Merging and keywords): Rewrite, to (a) better motivate the + discussion based on what the user wants to do, (b) fix up lots of + convoluted sentences, (c) move the discussion of the binary files + to the end, that is get across the basic idea first and then + embellish it. Remove a few unnecessary index entries. Expand + example. Just tell people to avoid -kk with binary files (comment + out the discussion of using -A after the commit). + +1999-01-29 Derek Price + <http://www-personal.engin.umich.edu/~oberon/resume.html> + + * cvs.texinfo: Added new node/section on merging and keywords. It + contains advice on how to avoid RCS keyword conflicts when merging + and avoid corrupting your binary files while doing it. + +1999-02-24 Jim Kingdon <http://www.cyclic.com> + + * cvsclient.texi (Request intro): Add paragraph about transmitting + more than one command. + +1999-01-29 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo: Use EXAMPLE.COM EXAMPLE.ORG and EXAMPLE.NET instead + of domains which might conflict with actual (current or future) + domains. The EXAMPLE domains are registered for this purpose. + +1999-01-22 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (Sticky tags): Refer to -j as the better way to undo + a change. + (Merging two revisions): Also talk about undoing removals and + adds. Move the index entries to here. + +1999-01-21 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (Error messages): Add "waiting for USER's lock". + +1999-01-16 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (Wrappers): Comment out all the -t/-f documentation, + since that feature is currently disabled. + +1999-01-14 Jim Kingdon <http://www.cyclic.com> + + * cvs.texinfo (Connecting via rsh): Add some more index entries so + that people who want to use SSH and such are slightly less lost. + +1999-01-12 Jim Kingdon <http://www.cyclic.com> + + * cvs-paper.ms: Remove comments which contained the FSF's old + address; it has changed. + +1998-12-29 Jim Kingdon <http://www.cyclic.com> + + * cvsclient.texi (Dates): Numeric timezones are preferred. + Also mention the Checkin-time request. + +1998-12-23 Jim Kingdon <http://www.cyclic.com> + + * RCSFILES: Add clarification about certain character set issues + from Paul Eggert, the RCS maintainer. The last paragraph and the + change from Shift-JIS to JIS as an example of a character set + which contains 0x40 bytes which are not '@' characters are mine; + the rest is directly from Paul Eggert. + +1998-12-22 Martin Buchholz <martin@xemacs.org> + + * cvs.texinfo: Fixed various trivial typos. + +1998-12-17 Jim Kingdon + + * cvsclient.texi (Responses): Explicitly say that Mod-time need + not be sent for all files. + +1998-12-16 Jim Kingdon + + Thanks to Ram Rajadhyaksha of the MacCVS Pro team for raising the + following issues. + * cvs.texinfo (Working directory storage): The deal about storing + files as text files applies to all the CVS/* files, not just + CVS/Entries. State the rationale too. + Document CVSROOT/Emptydir in CVS/Repository. + There is no set order in CVS/Entries. + Explicitly say that writing Entries.Log is optional. + +1998-12-03 Jim Kingdon + + * cvs.texinfo (Error messages): Add "unrecognized auth response". + (Password authentication server): Remove comment about + "unrecognized auth response" and link to the troubleshooting + section. + +1998-12-02 Jim Kingdon + + * cvs.texinfo (Multiple repositories): Add an example. + +1998-11-18 Jim Kingdon + + * cvs.texinfo (Invoking CVS): Change "-r tag" to "-r rev". We + already use "tag" as the name of the tag we are adding. + +1998-11-13 Jim Kingdon + + * cvs.texinfo (CVS commands): Add comment about whether part of + the manual should be organized by command. + +1998-11-06 Jim Kingdon + + Clean up various confusions between modules and directories: + * cvs.texinfo: In "are you sure you want to release" message, + change module to directory. CVS was changed some time ago. + (Tags): "working copy of the module" -> "working directory". + (Merging two revisions): Remove unnecessary text "that make up a + module". + (Recursive behavior): Change "module" to "directory". + (Removing files): Likewise. + (Tracking sources): Remove "a module" from titles. + (Moving directories): Change "module" to "parent-dir". + (Inside): Remove "of the module". + (Inside): Change "module" to "dir". + (Rename by copying): Change "module" to "dir". + (Rename by copying): Remove "of the module". + (Moving directories): "copy of the module" -> "checked out copy of + the directory"; remove second "of the module". Change "check out + the module" to " check out again". + (Moving directories): Remove "of the module". + (Keyword substitution): "your working copy of a module" -> "a + working directory". + (CVS commands): Change "module" to "directory". + (release examples): "module" -> "tc directory". + (commitinfo): "relative path to the module" -> "directory in the + repository". + (verifymsg): Change "module" to "directory". + (Updating a file): "working copy of a module" -> "working directory". + +1998-10-25 Jim Kingdon + + * cvs.texinfo (Branches and revisions): Fix error in branch + numbering which was introduced with change of 4 May 1997. + +1998-10-20 Jim Kingdon + + * cvs.texinfo (Tags): Point to Invoking CVS node so people aren't + left wondering what the syntax is. When introducing -r option, + warn people about sticky tags right off. + (Tagging the working directory, Tagging by date/tag, Modifying + tags, Tagging add/remove): New sections. + (Invoking CVS): Adjust tag and rtag to point to the new sections, + and to add tag -c which had been omitted. Delete tag -n; there is + no such option. + (rtag, tag): Removed; no longer needed. + (commit examples): Update xref. + +1998-10-15 Jim Kingdon + + * cvsclient.texi (Requests): It is OK to send Set before Root. + +1998-10-13 Jim Kingdon + + * cvsclient.texi (Protocol Notes): Remove item about "cvs update" + sending modified files to the server; there are some better ideas + at http://www.cyclic.com/cvs/dev-update.txt + Add mention of www.cyclic.com. + +1998-09-30 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Committing your changes, Environment variables): + Document VISUAL. + +1998-09-27 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Password authentication server): Say explicitly + that you edit passwd directly, many users get confused by this. + +1998-09-24 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Connecting via fork): :fork: may be of interest to + users, for example those who prefer CVS to prompt for one log + message per checkin, rather than one per directory. + (Connecting via fork): Document CVS_SERVER. + +1998-09-24 Noel Cragg <noel@swish.red-bean.com> + + * cvs.texinfo (Connecting via fork): new node about the fork + access method. + +1998-09-22 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Environment variables): Document + CVS_IGNORE_REMOTE_ROOT in the CVS 1.10 context. + (Moving a repository): Update comments concerning surgery on + CVS/Root and CVS/Repository files. + +1998-09-21 Noel Cragg <noel@swish.red-bean.com> + + * cvs.texinfo (Environment variables): remove information about + CVS_IGNORE_REMOTE_ROOT, since it's no longer used. + +1998-09-21 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (config): Mention that CVS 1.10 doesn't have + LockDir. + +1998-09-18 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Keyword list): Describe $Name and checking out with + a revision. + +1998-09-16 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: RFC2346 is out; update comment. + +1998-09-13 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Keyword list, Substitution modes): In describing + $Locker and -kkvl, refer to cvs admin -l. + + * cvsclient.texi (Requests): Re-word description of Sticky to + allow room for "Ntagname" (or other, future, values). + + * cvs.texinfo (tag): Remove confusing wording about supplying + revision numbers "implicitly". + +1998-09-10 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (rdiff options): Thanks to the diff library, -u is + supported regardless of your diff program. + +1998-09-07 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (config): Add LockDir. + +1998-09-01 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): "Directory" and "Argument" are + requests, not commands. Likewise for "other-request". A command, + roughly, is a request that uses "Argument"s, but we might want to + phase out the use of that term more so than codify it, I'm not sure. + +1998-09-01 Noel Cragg <noel@swish.red-bean.com> + + * cvsclient.texi (Requests): added a detailed explanation of the + Directory request and how it is handled, both for pre-1.10 and + post-1.10 servers. + +1998-09-01 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Multiple repositories): Also describe the CVS 1.10 + behavior. Looking at a mismatched version of the manual seems to + be a reasonably common occurrence. + + * cvs.texinfo (Environment variables): Revert change regarding + CVS_SERVER_SLEEP*; having that kind of debugging code in the main + CVS is getting out of hand. + +1998-09-01 Noel Cragg <noel@swish.red-bean.com> + + * cvs.texinfo (Multiple repositories): brief mention that cvs now + handles a working directory composed of multiple repositories. + (Environment variables): add note about CVS_SERVER_SLEEP2. + +1998-08-21 Ian Lance Taylor <ian@cygnus.com> + + * cvsclient.texi (Text tags): Document importmergecmd tag. + +1998-08-20 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Common options): Replace out of date URL concerning + ISO8601 dates with a more general statement and a few comments. + +1998-08-18 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Add "Checkin-time" request. + +Sun Jul 26 02:42:20 1998 Noel Cragg <noel@swish.red-bean.com> + + * cvs.texinfo (config): TopLevelAdmin variable. + + * cvsclient.texi (Requests): fix typo. + +1998-07-14 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): "remove" is like "add" in the sense + that it is the "ci" request which does most of the work. + +1998-06-23 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Excluding directories): Fix order of + "!first-dir/sdir" and "first-dir" to match what CVS actually + accepts. Reported by Tim McIntosh of sterling.com. + +1998-06-09 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Using keywords): Rewrite to be less specific to + source code in C. The old text was worse than that; it was + specific to certain versions of GCC (not even current GCC's, I + don't think) (reported most recently by Mitchell Perilstein; + if memory serves by others before that). + +1998-06-08 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Concurrency): Also mention #cvs.lock. Don't + mention #cvs.tfl; it is quite old (before CVS 1.5). + (Locks, Backing up, Concurrency): Add more index entries. + +1998-06-03 Ian Lance Taylor <ian@cygnus.com> + + * cvs.texinfo (Tracking sources): Clarify that the vendor branch + is only made the head revision when you import a new file, not any + time you import a file. + +1998-05-23 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (What is CVS?): info-cvs-request is now at gnu.org + and is no longer handled by a human (hallelujah). + +1998-05-12 Jim Meyering <meyering@ascend.com> + + * cvs.texinfo: Add an info dir entry. + Remove trailing white space. + +1998-05-05 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Wrappers): Be more explicit that -m 'COPY' has no + effect on binary files. + +1998-05-02 Jim Kingdon <kingdon@harvey.cyclic.com> + + * RCSFILES: Add more discussion of the order of the revisions. + +1998-04-27 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (loginfo example): Also give example of sending + mail. Use internal variable $USER rather than expecting CVS to + set the environment variable $USER. Change unnecessary 'sed' + invocation to 'cat' (it suffered from the same problem in terms of + internal variables versus environment variables). + + * cvs.texinfo (Error messages): Add "conflict: removed FILE was + modified by second party". + +1998-04-20 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Common options): Update comment about meaning of + HEAD in cvs diff. + +1998-04-12 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Dates): Also mention log -d. + + * cvs.texinfo (Invoking CVS): No space is allowed between -r or -w + and its argument, for the log command. + +1998-04-11 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Dates): New section, explaining the deal with + date formats. + +1998-04-09 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Global options, Invoking CVS): Fix typo + ("files files" -> "files"). + (Invoking CVS): Make -q and -Q more concise. + (Invoking CVS): Use @var for metavariables in "diff -r". + +1998-03-17 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (~/.cvsrc): In example, put "checkout" rather than + "co" into .cvsrc; we just finished explaining that only the former + works! Thanks to Lenny Foner for reporting this. + + * cvs.texinfo (Copying): Remove this node. This basically + restores the status quo prior to 18 Oct 1996 (before then the node + existed but was empty). + (before Top): Adjust copyright notice accordingly. + +1998-03-12 Tim Pierce <twp@skepsis.com> + + * RCSFILES: Updated description of `hardlinks' newphrases. + +1998-03-07 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Tags, Sticky tags, Creating a branch, Accessing + branches): Rename release-0-1 tag to rel-0-1 and likewise for + release-0-1-patches and release-0-4. This fixes an overfull hbox. + (diff options): Reformat table to fix underfull hboxes and such. + +1998-03-07 Tim Pierce <twp@skepsis.com> + + * cvs.texinfo (Editing files, Special Files): Document hardlinks. + Various cleanups to PreservePermissions text. + * RCSFILES: Document PreservePermissions newphrases. + +1998-03-04 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Special Files): Add notes about client/server CVS + and hard links across directories. + +1998-03-01 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Keeping a checked out copy): The magic loginfo + incantation isn't too likely to work except on unix. + +1998-02-23 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (user-defined logging): Double "@" literal. + +1998-02-18 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (user-defined logging): Add taginfo example. + +1998-02-04 Tim Pierce <twp@skepsis.com> + + * cvs.texinfo (config): PreservePermissions variable. + (Special Files): New. + (Editing files): Add note about PreservePermissions. + +Tue Feb 10 18:07:35 1998 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Connection): New node. + + * cvsclient.texi (Protocol): Fix typo (lots -> lost). + +Sun Feb 8 21:39:22 1998 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Invoking CVS): For admin -b, point to the section + where we talk about reverting to vendor branch. + + * cvs.texinfo (Invoking CVS, rdiff options): Document rdiff -V + option as obsolete, since it was made a fatal error some time ago. + + * cvs.texinfo (Invoking CVS): Add global options, keywords, and + keyword substitution modes. Wording fix in reference to --help + and Index. + +Wed Jan 28 23:09:39 1998 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Excluding directories): Add index entry for "!". + +28 Jan 1998 Karl Fogel and Jim Kingdon + + * cvsclient.texi (Requests, Responses): document + "wrapper-sendme-rcsOptions" and "Wrapper-rcsOption". + +Tue Jan 27 18:37:37 1998 Ian Lance Taylor <ian@cygnus.com> + + * cvs.texinfo (Excluding directories): New node, documenting how + to exclude directories using ! in an alias module. + +Sun Jan 18 18:23:02 1998 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Add Kopt request. + +Thu Jan 1 17:36:42 1998 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (BUGS, Credits): Change @unnumbered to @appendix now + that these are moved from the start to the end. + +Sat Dec 27 10:06:56 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Add "Too many arguments!". + +Fri Dec 26 18:30:26 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (What is CVS?): Just point to the two canonical web + sites (Pascal Molli and Cyclic) concerning CVS downloads. The GNU + URL was out of date and GNU only has source distributions anyway. + + * cvs.texinfo: Change bug-cvs address to gnu.org per email from + Martin Hamilton. + +Tue Dec 23 18:04:09 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Sticky tags): Further cleanups. Fix thinko + (s/subsequent cvs update/& commands/). Remove "vi driver.c" and + commit from example (totally vestigial). Reword start of + paragraph on non-branch sticky tags, so that it better alludes + to branch sticky tags. When introducing sticky tags, make it + clear that even people who aren't trying to use sticky tags + may need to know how to avoid them. Restore comment about + CVS/Tag files. + (Accessing branches): Don't xref to merging here; that is a much + more advanced topic and the "but see" wording didn't tell us what + to see the xref about. + +Tue Dec 23 14:39:08 1997 Karl Fogel <kfogel@floss.red-bean.com> + and Jim Kingdon + + * cvs.texinfo (Creating a branch): Rewritten. Introduce with + `tag', then discuss `rtag' and `-r'. + +Tue Dec 23 10:03:37 1997 Karl Fogel <kfogel@floss.red-bean.com> + and Jim Kingdon + + * cvs.texinfo: Changes to dehairify the "Sticky tags" situation: + (Revisions): "Sticky tags" moved here, description in menu changed + to be a little more informative. + (Sticky tags): Moved from "Branching and merging" to "Revisions". + (Accessing branches): New node in "Branching and merging", + explains how to use checkout vs update to retrieve a branch. + Text and example inherited from "Sticky tags", but text mostly + rewritten. + (Sticky tags): Moved under "Revisions", rewritten somewhat (more + rewrites to follow). + Don't use "-v" in "cvs status" example. + +Mon Dec 22 11:46:05 1997 Karl Fogel <kfogel@floss.red-bean.com> + and Jim Kingdon + + Cleanups related to recent separation of revisions from + branching/merging: + * cvs.texinfo (Revisions): Take paragraph introducing branches, + rewrite it and move it to "Branching and merging". + (Branching and merging): Also rewrite merging intro. + (Revision numbers): Don't go into detail about branch revision + numbers here, just mention that they happen and refer to new + node "Branches and revisions". + (Branches and revisions): New node under "Branching and merging", + inherits text from "Revision numbers". + (Creating a branch): Refer to "Branches and revisions" now, not + "Revision numbers". + (Binary why): Rewrite sentence which refers to merging, so that + it isn't specific to branch merging. + (Branches motivation): Fix typo (select -> elect). Add comment + about what this node is accomplishing, in general. + +Sun Dec 21 20:57:24 1997 Karl Fogel <kfogel@floss.red-bean.com> + and Jim Kingdon + + This is just moving text; related cleanups to follow. + * cvs.texinfo: Changes to put branching and merging together, and + keep it all separate from revisions: + (Revisions): Renamed from "Revisions and branches". + (Branching and merging): Renamed from "Merging". + (Branches motivation, Creating a branch, Sticky tags, Magic branch + numbers): these subnodes moved to "Branching and merging" from + "Revisions". + everywhere: Adjusted cross-references to cope with above. + +Sun Dec 21 20:36:39 1997 Karl Fogel <kfogel@floss.red-bean.com> + and Jim Kingdon + + Note that this is just moving text, not changing it: + * cvs.texinfo: divide top-level menu into sections. + (Multiple developers, Builds, Tracking sources, Keyword + substitution): moved to be in "CVS and the Real World" section. + (Compatibility): moved to be in "References" section. + +Mon Dec 22 08:54:31 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Example): In comment, in citing the BNF style + used in many RFCs, cite RFC2234 not RFC822 (now that the former is + out). + +Sun Dec 21 17:42:22 1997 Karl Fogel <kfogel@floss.red-bean.com> + + * cvs.texinfo (Overview): New node. + (What is CVS?, A sample session): Put under Overview. + (What is CVS not?): New node under Overview. + [text previously was part of "What is CVS?" -kingdon] + (Preface): Removed this node and its contents. + (Checklist): Removed this node and its contents. + (Credits): Now toward end of top-level menu (was under Preface). + (BUGS): Now toward end of top-level menu (was under Preface). + +Sun Dec 14 10:14:25 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Responses): Add MT response. + (Text tags): New node. + + * cvs.texinfo (loginfo): Add comment about which commands run + loginfo. + +Sat Dec 13 08:41:13 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Connection and Authentication): State that + GSSAPI is preferred to kserver. Try to be clearer about what + the term "pserver" means. Introduce GSSAPI and cite the relevant + RFCs. Discuss the limitations of the existing features in + preventing hijacking. + + * cvs.texinfo (GSSAPI authenticated, Kerberos authenticated): + Briefly introduce what GSSAPI and Kerberos are. Be slightly more + emphatic about protecting against downgrade attacks. + +Fri Dec 12 17:36:46 1997 Ian Lance Taylor <ian@cygnus.com> + + * cvs.texinfo (GSSAPI authenticated): New node. + (Global options): Document -a. Mention GSSAPI in -x + documentation. + * cvsclient.texi (Connection and Authentication): Document GSSAPI + authentication. + (Requests): Add Gssapi-encrypt and Gssapi-authenticate. + +Fri Dec 12 09:27:38 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (cvsignore): Add note about comments and the + space-separated nature of the syntax. + +Sun Dec 7 09:33:11 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (checkout): Clarify issues regarding updating + existing working directories. + +Sun Nov 30 20:38:17 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Wrappers): Add comment: we don't document %s. + +Mon Nov 24 23:00:09 1997 Karl Fogel <kfogel@floss.red-bean.com> + and Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi: Move Protocol Notes node to the end. + + * cvsclient.texi (Request intro): new node/section. + (Protocol): added some introductory material. + Rearranged menu into General Conventions, Protocol specification, + and Example etc sections. + (File Modes): replaces Modes, for consistency. + +Sat Nov 22 12:29:58 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Entries Lines): Clarify options in entries line. + +Tue Nov 18 09:23:15 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Be more explicit about "export" and + entries lines. + + * Makefile.in (DISTFILES): Remove DIFFUTILS-2.7-BUG. + +Mon Nov 17 18:20:47 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (tag options): Expand comment with reference to FAQ. + +Fri Nov 14 11:02:37 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Update discussion of "dying gasps". + + * cvs.texinfo (tag options): Add FIXME comment about renaming tags. + +Thu Nov 13 10:20:39 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Common options): Remove also has a -f option with a + different meaning than most. + +Wed Nov 12 21:57:40 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (File permissions, Connecting via rsh, Environment + variables): When putting an environment variable in the index, say + it is an environment variable. Don't index the same name twice. + + * cvs.texinfo: Many edits to reflect the fact that CVS no longer + invokes external RCS programs. + +Tue Nov 11 15:15:49 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Locks, CVS in repository): New nodes, document the + locking scheme and briefly outline CVS and CVS/fileattr. + +Sun Nov 9 17:39:41 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * DIFFUTILS-2.7-BUG: Removed; the bug is fixed and the testcases + are incorporated into sanity.sh. + +Sat Nov 8 09:49:38 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Binary why): Try to be a little clearer about how + merges fit into CVS. Say it may be error prone to have developers + doing merges manually. + +Tue Nov 4 13:02:22 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (admin options): Add discussion of what happens if + there are tags. + +Fri Oct 31 00:04:09 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (admin options): Rewrite discussion of -o to + hopefully be clearer and to also document the new :: syntax. + (admin examples): Removed; incorporated into admin options. + (Invoking CVS): Wording fix for admin -o. + + * cvs.texinfo (Binary why): New node, talks about diff and merge. + (Binary howto): Renamed from Binary files. + (Binary files): Now just contains an introduction. + + * cvs.texinfo (Error messages): Add "could not merge" message. In + discussion of "Binary files . . . differ" message, mention that + this is only an issue with old verisons of CVS. + +Thu Oct 30 15:55:21 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Add "authorization failed" message. + +Wed Oct 29 11:52:05 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Remove fake RCSid; we decided to remove rcsid's a + while ago. Cleanups suggested by Stephen Gildea (CVSROOT/passwd + has 2 or 3 fields; /user -> /usr; noone -> no one; in used -> in + use). Add comment about making compilers happy about rcsids. + +Sat Oct 25 00:58:24 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * RCSFILES: rcsfile.5 is correct about {num} after next being + optional. + +Wed Oct 22 10:08:27 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Add message about unrecognized + response from cvs server. + +1997-10-11 Noel Cragg <noel@swish.red-bean.com> + + * cvs.texinfo (checkout options): describe how the `-d' and `-N' + flags really work. Give examples. + (export options): refer the reader to the descriptions for `-d' + and `-N' in checkout options, since the behavior is the same. + +Thu Oct 9 12:01:35 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (log options): Add comment about "cvs log -r". + +Wed Oct 8 10:24:19 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (rtag options): Add comment about how this is + confusing. + +Tue Sep 30 12:31:25 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Working directory storage): Add comment about + Entries.Static. + +Thu Sep 25 23:52:57 1997 Noel Cragg <noel@swish.red-bean.com> + + * cvsclient.texi (Responses): description of Module-expansion was + missing a carriage return after the @item clause. + +Wed Sep 24 12:04:42 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Remote repositories): Add comment about pserver + vs. having users create their own repositories. + +Sat Sep 20 00:59:53 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Keyword list): Change title from "RCS Keywords" to + "Keyword list" as it is CVS that expands them. + (Avoiding substitution): Change "rcs" to "cvs", in the context of + the program which expands keywords. + +Fri Sep 19 22:57:24 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * RCSFILES: Grammar fix in first paragraph. Re-word section on + dead newphrase. Add item about what it means if "expand" is omitted. + + * cvs.texinfo (Magic branch numbers): Change example branch number + from 1.2.3 to 1.2.4; CVS assigns even branch numbers and I don't + think vendor branches are very relevant to this example. + +Wed Sep 17 17:21:33 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (admin options): Add comment about "cvs admin -b" + (with no argument to the -b). + + * RCSFILES: "next" is optional, not required. + +Tue Sep 16 15:13:22 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Binary files): Add comment about another possible + way to auto-detect binary files. + +Sun Sep 14 12:38:56 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Conflicts example): Adjust text and comments + regarding conflict markers to reflect change in CVS. + +Wed Sep 10 12:44:04 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Server requirements): Add comment about server + disk usage in /tmp. + + * cvs.texinfo (Common options): More comments about date formats: + "now", "yesterday", and the "3 weeks ago" family. + +Tue Sep 9 13:09:58 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * DIFFUTILS-2.7-BUG: Eggert patch is preferred to Rittle one. + +Sun Sep 7 18:38:23 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (history options): Revise -e to say that it includes + future record types (and remove out of date list of what record + types it implies). + + * cvs.texinfo (Environment variables): Expand/correct discussion + of HOME, HOMEDRIVE, and HOMEPATH. + (Error messages): Add "could not find out home directory". + + * cvs.texinfo (update options): Reword -r doc to hopefully be + clearer that it takes either numeric or symbolic revision. + + * cvs.texinfo (syntax): Add comment about how regexp syntax may + be, er, creatively altered, by configure.in. + +Sat Sep 6 11:29:15 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Working directory storage): Document Baserev and + Baserev.tmp. + (Working directory storage): Adjust comment regarding CVS/* being + text files. + +Fri Sep 5 14:42:39 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (BUGS): Remove mention of unsupported resources page + on http://www.cyclic.com, as it might go away in a future + reorganization. + + * DIFFUTILS-2.7-BUG: Further info from Eggert. + +1997-09-05 Paul Eggert <eggert@twinsun.com> + + * DIFFUTILS-2.7-BUG: Explain how this bug will probably be + fixed in the next diffutils release. + +Thu Sep 4 17:09:57 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Binary files): Reword the section on what you need + to do with cvs admin -kb to hopefully be a bit clearer. Still not + ideal (see comment). + + * cvs.texinfo (modules): Break node into separate nodes for alias + modules, regular modules, ampersand modules, and options. Expand + text with more examples and explanations. Add index entries. + +Wed Sep 3 14:49:43 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Multiple developers): Add idea about cvs editors + and reserved checkouts. + +Sun Aug 31 19:36:21 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Rewrite paragraph on cvs add on a + filename containing '/'. + +Thu Aug 28 14:13:50 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (diff options): Add comment about "cvs diff" + vs. "cvs diff -r HEAD". + + * cvs.texinfo (Global options): Add comment about -w not + overriding cvs watch on. + +Wed Aug 27 08:09:31 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Password authentication server): Grammar fix ("under + as the username" -> "as the username"). + + * cvs.texinfo: Fix doubled 'the the' typos. Reported by + karlb@atg.com. + +Tue Aug 26 12:25:42 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Checklist): Reword xref to point to Binary files + rather than Keyword expansion. Credit goes to jeff@alum.mit.edu + (Jeff Breidenbach) for reporting the problem. + +Mon Aug 18 17:23:18 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (modules): Suggest taginfo instead of -t. Add + comment with some of the reasons. Add comment about -u and -i + problems. + +Sat Aug 16 10:19:06 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Add note about how "could not + check out foo.c" seems to also have been observed on Irix. + +Fri Aug 15 17:28:01 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Add "could not check out foo.c". + +Thu Aug 14 23:57:53 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Wrappers): Document new -m 'COPY' behavior. + +Tue Aug 12 20:56:40 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Sticky tags): Add comment about how we should be + documenting sticky tags. + +Fri Aug 8 10:01:03 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (File status): Add comment about "working revision" + in cvs status for a locally removed file. + +Thu Aug 7 22:53:45 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (From other version control systems): Mention + pvcs_to_rcs alongside sccs2rcs. + +Tue Aug 5 17:22:50 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Compatibility): Add comment about how CVS probably + could be detecting the case of dead files killed by CVS 1.3. + + * cvs.texinfo (From other version control systems): Add paragraph + about converting from systems which don't export RCS files. + +Sun Aug 3 21:03:14 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Responses): Cite RFC1321 for MD5. + + * cvs.texinfo (A sample session): Nuke index entry for "A sample + session". The fact that this isn't "sample session" is totally + bogus, but in general the table of contents is probably better for + this entry. + + * cvs.texinfo (Error messages): Add comment about wording of error + concerning unknown -x option. + + * cvs.texinfo (Wrappers): Add comment about absolute filter pathname. + +Thu Jul 31 14:40:15 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Use @ref not @xref when reference is not at the + start of a sentence. Avoids capitalizing "See" when we shouldn't. + Fixes to other similar xref problems. + +Wed Jul 30 19:30:31 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Connection and Authentication): Don't use @samp + on BEGIN AUTH REQUEST and friends. Avoids overfull hbox. + +Fri Jul 25 10:40:22 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Remove obsolete sentence regarding + using Directory instead of Repository enabling alternate response + syntax. + + * cvsclient.texi (Response intro): Add discussing of file updating + responses and file update modifying responses. + (Responses): Refer to this description rather than trying to + describe it in each place. The descriptions in each place were + somewhat incomplete and didn't get updated when new file updating + responses were added. + + * cvsclient.texi: Split node Responses into Response intro, + Response pathnames, and Responses. + +Thu Jul 24 23:13:24 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (config): Document SystemAuth. + (Password authentication server): Mention SystemAuth. + +Mon Jul 21 08:57:04 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * Makefile.in (DISTFILES): Add DIFFUTILS-2.7-BUG. + +Sun Jul 20 17:55:52 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (admin options): For options with optional + arguments, specify that there can be no space between the option + and its argument. For -N, add xref to Magic branch numbers. For + -t, talk about reading from stdin. Comment changes. + +Sat Jul 19 22:28:47 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Preface): Make section titles more verbose. + Likewise for the menu. + +Fri Jul 18 08:41:11 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): No need for an external patch if + server and client are current. Add comment with more thoughts + about messages specific to old versions of CVS. + + * cvs.texinfo (Error messages): Add "cannot start server via rcmd". + + * cvs.texinfo (Error messages): Add "cannot open CVS/Root" for cvs + init. + + * cvs.texinfo (Error messages): Add "missing author". + +Tue Jul 15 16:47:08 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Keyword list): Fix documentation of $Log to reflect + the fact that we no longer use the comment leader. + (admin options): Fix documentation of $Log. + (admin examples): Remove example concerning comment leader, since + the example no longer does what it claims to. + (admin, admin options): Fix various parts of the documentation to + not refer to this being implemented via RCS. Say nastier things + about -I and -x. Add comments about options to "rcs" which we + don't document. + +Mon Jul 14 00:04:32 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): The "cannot change permissions on + temporary directory" error has been happening in various test cases. + +Sat Jul 12 11:12:18 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Repository files): Further comments about leading + "-" in filenames. + +Fri Jul 11 21:30:11 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Repository files): Add comment about legal + filenames. + +Wed Jul 9 18:05:26 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Responses): Add Mbinary response. + +Mon Jul 7 12:04:01 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Goals): Add previously unwritten goal about only + one way to do each operation. + + * cvs.texinfo (File permissions): Rewrite paragraph on setuid to + be more verbose and less unix-specific. + +Sat Jul 5 03:16:38 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Connection and Authentication): When we said to + "ignore" an unrecogized code we mean to treat it as nonspecific, + not to ignore the response. + + * cvsclient.texi (Example): Refer to RFC2119 when referring to + terminology of MUST, SHALL, &c. + + * cvs.texinfo (Windows permissions): New node. + +Fri Jul 4 15:27:43 1997 Ian Lance Taylor <ian@cygnus.com> + + * cvs.texinfo (Common options): Fix typo (avaliable for + available). + +Tue Jul 1 09:19:02 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Server requirements): Discuss memory used by diff. + + * cvs.texinfo (Substitution modes): Add comment about -A resetting + both sticky tags/dates and sticky options. + + * cvs.texinfo (File permissions): Add paragraph concerning + ownership of the RCS files. + + * cvs.texinfo (Working directory storage): Relative repositories + in CVS/Repository are legal. + +Mon Jun 30 10:48:21 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Top): Add menu item for Password scrambling. + + * cvs.texinfo (Committing your changes): Add comment concerning + documentation of message prompting. + +Fri Jun 27 11:20:34 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Password scrambling): New node. + (Connection and Authentication): Adjust accordingly. + (Protocol Notes): Add long discussion of character sets and + password scrambling. + + * cvs.texinfo (Repository files): Also mention doc/RCSFILES in + documenting RCS file format. + (CVSROOT, storage of files): New node. + +Thu Jun 26 09:18:15 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (File permissions): xref to the pserver thing about + permissions in CVSROOT. + (Kerberos authenticated): Explicitly mention kerberos rsh. + Add various index entries for "security, <foo>". + +Wed Jun 25 13:39:16 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Common options): Rewrite comments concerning HEAD + and testcases and solution. Changing HEAD might be too big a + change; might be better to phase it out. + (Common options, Tags): Add index entries for HEAD and BASE. + +Tue Jun 24 09:37:26 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Add assertion failed. + + * cvsclient.texi (Connection and Authentication): Add "E" and + "error" as responses in authentication protocol. The server + already was in the (formerly bad) habit of sending them, and we + might as well implement this in the client and document it. + + * cvs.texinfo (Password authentication security): Note about + permissions on $CVSROOT also applies to its parent and so on up to + /. + +Mon Jun 23 18:28:18 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Creating a repository): xref to Server requirements + for more details on memory, CPU. + (Server requirements): Add xref to Creating a repository regarding + disk space. + + * cvs.texinfo (Read-only access, Password authentication + security): The known holes which let a read-only user execute + arbitrary programs on the server are gone. + + * cvsclient.texi (Protocol Notes): Remove multisite item; it is + replaced by item 186 in TODO. Add a general reference to TODO. + Rewrite accordingly the sentence about multisite in the item + concerning sending modified files in "cvs update". + +Fri Jun 20 17:00:20 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Add "binary files differ" when + trying to check in a binary file. + +Fri Jun 20 14:01:23 1997 David J MacKenzie <djm@va.pubnix.com> + and Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Fix various formatting, spelling, stylistic, and + factual errors. + +Thu Jun 19 07:11:33 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (config): New node. + (Password authentication server): Talk about RCSBIN in config as + an alternative to -b global option. + * cvsclient.texi (Requests): Specify when Root can/must be used. + + * cvs.texinfo (Error messages): Add + "*PANIC* administration files missing". + + * cvs.texinfo (Password authentication server): Mention + permissions on $CVSROOT and $CVSROOT/CVSROOT as part of the + installation process. + (Password authentication security): Clarify that permissions issue + applies to $CVSROOT as well as $CVSROOT/CVSROOT. + +Wed Jun 18 00:03:25 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Password authentication security): Add paragraph + on write permissions of $CVSROOT/CVSROOT. + + * cvs.texinfo (Adding and removing): New node. Move Adding files, + Removing files, Removing directories, Moving files, and Moving + directories under it. + + * cvs.texinfo (Removing directories): Add sentence about how + one doesn't remove the directory itself. + + * cvs.texinfo (Password authentication server): Document + --allow-root. + +Tue Jun 17 09:58:03 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Add "unknown option" from RCS. + +Fri Jun 13 12:11:09 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Global options): Add note about how -n might affect + CVS's output. + +Thu Jun 12 09:33:40 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Other problems): New node. Add discussion of + problem with old rcsmerge. + + * cvs.texinfo (Environment variables): Add CVSUMASK. + +Mon Jun 2 18:39:57 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Moving a repository): New node. + +Tue May 27 18:27:57 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Working directory storage): Add comment about + timestamps. + * cvsclient.texi (Responses): Add Mod-time. + +Mon May 26 10:04:32 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Wrappers): Add comment concerning -t/-f and + client/server. + +Sun May 25 00:08:39 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Multiple vendor branches): New node. + (First import, import options, Invoking CVS): xref to it. + +Sat May 24 23:47:47 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (File permissions): Add comment about group + ownership in repository and setgid bit on directories. + +Fri May 23 17:14:05 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * RCSFILES: Fix typo in dead newphrase description ("an" -> "a"). + +Fri May 23 16:33:38 1997 Ian Lance Taylor <ian@cygnus.com> + + * RCSFILES: Mention dead as a newphrase. + +Fri May 23 09:45:39 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Builds): In comment, update URL of mk. + +Thu May 22 09:25:56 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Add comment about yet another way + to produce a "cannot open CVS/Entries for reading" error. + +Tue May 20 17:54:55 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Add item about EINVAL in rename. + +Mon May 19 00:21:49 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Keywords in imports): New node. + (Tracking sources): Add comment about what a "vendor" is. + + * cvs.texinfo (Keyword substitution): Where it refers to RCS + having a certain behavior, rewrite to not pass the buck like + that. Saying "RCS file" is still OK; that is a legit CVS + concept. A few other minor edits. + +Sun May 18 10:24:57 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * RCSFILES: Add list of known newphrase extensions. + + * cvs.texinfo (From other version control systems): Fix typo + ("systesm" -> "systems"). + + * cvs.texinfo (Exit status): New node. + (diff): Replace text on exit status with an xref to that node. + The previous text documented a behavior which CVS no longer + implements. + (user-defined logging, commitinfo, verifymsg, Error messages): + Add index entries for "exit status, of <something which CVS invokes>". + + * cvs.texinfo (Administrative files): Add comment concerning + writing triggers and particularly performance issues. + + * cvs.texinfo (rtag options, tag options): Don't discuss what old + versions did with respect to the behavior now controlled by -F; we + don't try to document old versions here. Add comments concerning + how -F should be documented. Add index entries for "renaming + tags" and such pointing to "tag -F". + +Wed May 14 12:16:19 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Binary files): Add text and comment about + automatically detecting binary files. + +Mon May 12 11:55:07 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Connection and Authentication): Add item about + future expansion. + +Thu May 8 11:08:34 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Update imports): Add comment about wdiff + vs. fsf/wdiff in example. + +Wed May 7 13:52:47 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (checkout): Add comment about need for example + regarding what the "module" argument means. + +Tue May 6 18:02:27 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (History browsing): Add comment about looking at old + revisions. + +Tue May 06 15:05:00 1997 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo: More additions/corrections for -R due to recent + changes. + +Mon Dec 16 15:18:00 1996 Larry Jones <larry.jones@sdrc.com> + + * cvs.texinfo: Added/corrected documentation for -R. (Minor edits + by Jim Kingdon to reflect recent changes in cvs.texinfo) + +Sun May 4 14:38:35 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Compatibility): Add comment about "D" lines in + Entries. + + * cvs.texinfo (CVS commands, diff): Change "run diffs" to "show + differences"; the former is jargon. + (CVS commands): Don't refer to "rlog" in describing what log does. + + * Makefile.in (cvsclient.dvi cvsclient.aux): Run texi2dvi rather + than (poorly) emulating it ourself. + + Fix overfull and underfull hboxes: + * cvs.texinfo (What is CVS?): Add words "the newsgroup" before + "comp.sources.unix". + (Credits): Put list of people in @display. + (Repository files): Put /usr/local/cvsroot in @example. + (Connecting via rsh): Change "anklet" to "toe" in example. + (Kerberos authenticated, Password authentication client, Password + authentication server): Change "brickyard" to "yard" in example. + (Read-only access): Use @example and refer to files with a shorter + pathname. + (Server temporary directory): Use @example for pathname. + (Watches Compatibility): Add phony line break. + (Revision numbers): Remove revision 1.2.2.2 and tighten up the + spacing for "the main trunk". + (Tags, Creating a branch): Change /usr/local/cvsroot to /u/cvsroot. + (Merging more than once): Tighten up spacing for "the main trunk". + (Recursive behavior): Put long command in @example. + (First import): Remove word "called". + (Common options): Put long URL in @example. + (loginfo example): Use fewer hyphens in example. + (Variables): Put long command name in @example. + (Copying): Add line break. + (Administrative files): Remove "the" from title. + (Copying): Change "@unnumberedsec" to two "@heading"s. + * cvsclient.texi (Requests): Change /home/kingdon/zwork/cvsroot to + /u/cvsroot. + (Example): Add word "file". + (Example): Change line breaks in example log message. + (Example): Change /home/kingdon/testing/cvsroot to /u/cvsroot. + + * cvs.texinfo (Credits): Don't refer to appendix A and B, they + have been renumbered. Reword so that it works whether the text in + question has since been rewritten or not. + + * cvs.texinfo (BUGS): Rewrite to reflect the many different ways + that one might want to handle bugs. Move information on Signum + and Cyclic from Preface to here. Remove information on known + deficiencies in the manual (some of them I'm not sure were really + things in need of improvement; others were too general to be + useful). For the most part FIXME comments are probably better for + this. Remove "Linkoping, October 1993, Per Cederqvist"--many + parts of the manual are now from other people, dates, and places. + (What is CVS): For the most part, just refer to BUGS concerning + bug-cvs. Also tell people how to subscribe to bug-cvs. + (Credits): Say that list is not comprehensive and refer to + ChangeLog. + +Sat May 3 10:51:58 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (rcsinfo): Add comment about checkoutlist and + related topics. + + * cvs.texinfo (Server temporary directory): New node. + + * cvs.texinfo (Backing up): New node. + + * cvs.texinfo (Repository): Be more explicit about the repository + and the working directory not being subdirectories of each other. + +Mon Apr 28 11:12:56 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Removing files): Use "*.c" not "?.c" in example; + the former should be good for both unix and DOS-like operating + systems. Document -f option. Refer to Invoking CVS for a full + list of options. Add a few comments. + + * cvs.texinfo (Invoking CVS): For checkout and update, call them + "sticky options" not "sticky kopts". + + * cvs.texinfo (Editing files): Add additional comments on get + vs. checkout. + +Sun Apr 27 16:17:06 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (commit): Only document the current flags (where -f + is force and -F file gets the message from a log file). We had + partly made this change on 9 Feb 1997, but some places got missed. + + * RCSFILES: Add discussion of the common concern regarding + applying deltas to get to a branch head. + + * DIFFUTILS-2.7-BUG: New file. + + * cvs.texinfo (File status): Refer to "Invoking CVS", not + "status", for status options. Add paragraph about how "cvs -n -q + update" is another way to display file status. + (update examples): Removed; it had contained the "cvs -n -q + update" material. + (Invoking CVS): xref to "File status" and "Tags", not "status" and + "status options". + (status, status options): Removed. + (update options, checkout options): xref to "Invoking CVS" + not "status". + + * cvsclient.texi (Requests): Clarify how long-lived Sticky and + Static-directory are. + + * cvs.texinfo: Add @finalout. + + * cvs.texinfo (Error messages): Add "cannot change permissions on + temporary directory" message. + +Wed Apr 23 12:53:45 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Document "add" in much more detail. + +Wed Apr 23 00:38:17 1997 Ian Lance Taylor <ian@cygnus.com> + + * cvsclient.texi (Requests): Correct small typo (`a' for `as'). + +Tue Apr 22 14:23:32 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Protocol Notes): Expand ideas on multisite + features somewhat. Add items about the network turnarounds for + pserver authentication and for protocol negotiation. + +Mon Apr 21 08:54:48 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Working directory storage): Describe what to do + with Entries.Log in more detail. + + * cvsclient.texi (Responses): Say "CVS 1.9 and earlier" rather + than "pre version 1.10". The latter increases confusion by + referring to a version which doesn't exist yet. + +Mon Apr 21 01:02:53 1997 Ian Lance Taylor <ian@cygnus.com> + + * cvsclient.texi (Responses): Document Rcs-diff. Indicate that + Patched is now deprecated in favor of Rcs-diff. + +Sun Apr 20 23:42:03 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Working directory storage): Add note about format + of timestamp and the "Result of merge" concept. + +Sat Apr 19 13:42:33 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Responses): It is OK for Copy-file to implement + a rename instead of a copy. + +Fri Apr 18 12:05:48 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Assigning revisions): Say that -r implies -f. + +Thu Apr 17 16:34:14 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (From other version control systems): Add comment + about CMZ and PATCHY. + +Wed Apr 16 12:35:25 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Responses): Add paragraph describing how + Copy-file relates to Merged. + (Responses): Add paragraph about how it is the server which + worries about not clobbering the user's file. + +Tue Apr 15 00:57:31 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * RCSFILES: Add notes on keyword expansion. + + * cvs.texinfo (Rename by copying): Comment out seemingly erroneous + text regarding the revision number that the new file starts with. + +Mon Apr 14 12:37:35 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Clients should try to send + notifications right away. + + * cvsclient.texi (Requests): For Notify request, clarify a few + future expansion situations. Specify the format of the time. + + * cvsclient.texi (Requests): Clarify that arguments to co, rdiff, + and rtag are module names (and how that differs from file/directory + names). + + * cvsclient.texi (Responses): Say that servers need to create + directories one at a time. + +Sat Apr 12 09:32:58 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Committing your changes): Say that editor default + is notepad (not vi) for Windows NT/95. Be more clear about what + "cvs commit" does. Add paragraph about timestamps. + (Environment variables, Global options, editinfo): + Add xrefs to that node. + +Thu Apr 10 15:48:39 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Add "could not patch; will refetch". + +Wed Apr 9 15:21:11 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Working directory storage): New node. + + * cvs.texinfo (Error messages): Add comment about "cvs co ." on + NT. + +Tue Apr 8 14:44:26 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Add diff3 usage message. + +Sun Apr 6 19:03:01 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Removing files): Add comment about undoing a "cvs + remove". + + * cvsclient.texi (Requests): Explicitly mention the idea of + deferring "Notify" requests. + +Tue Apr 1 07:51:38 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Responses): Add paragraph about directory + creation and empty directories. + + * cvs.texinfo (Binary files): Add comment about binary files and + merges. + + * cvsclient.texi (Requests): Add discussion of when to send + Is-modified. + + * cvsclient.texi (Requests): Sending Is-modified is enough to + prevent the file from being considered "lost". + +Sun Mar 30 00:31:47 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Add Is-modified request. Clarify + order of Entry relative to Unchanged or Is-modified (might as well + specify the same thing vis-a-vis Modified while we are at it). + +Sat Mar 29 12:32:40 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi: Change "newline" to "linefeed". Most of the + document already reads "linefeed" and that is what is intended. + (File transmissions): New node, moved here from Requests. + (Goals, Filenames, File transmissions, new node Strings): Add + discussion of character sets and what we expect from the transport + protocol we run on. + + * cvsclient.texi (Requests): Add paragraph about each Directory + request specifying a new local-directory and repository. + + * cvsclient.texi (Requests): Add paragraph about renaming + local-directory in Directory request. Use "local-directory" + consistently instead of "working directory", for clarity. + +Fri Mar 28 13:59:59 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Make it clear that there is no + guarantee that one will get Clear-sticky instead of another + response. Also clarify that clients will tend to store the + repository in a long-term way. + + * cvsclient.texi (Requests): Further clarify Directory example. + + * cvsclient.texi (Requests): Add example and further explanation + of what expand-modules is for. + + * cvsclient.texi (Requests): Add example, hopefully making it + clearer what REPOSITORY and LOCAL-DIRECTORY mean to Directory. + + * cvs.texinfo (Attic): New node. + (rtag options): Adjust discussion of -a accordingly. + (Repository files): Adjust accordingly. + +Thu Mar 27 09:57:05 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): Give exact wording of broken pipe + error message. + + * cvs.texinfo (history database): Add comment about various + problems with the history file. + + * cvs.texinfo (Common options): The ISO8601 web page we had + mentioned in a comment is no more. Replace it with a new one. + + * cvs.texinfo (Common options): "cvs history" also outputs dates. + +Wed Mar 26 10:54:21 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Common options): "cvs editors" also outputs dates. + + * cvs.texinfo (Outside): Fix paragraph which said that revision + numbers start at 1.0. First of all, it is 1.1. Second of all, it + is sometimes 2.1, 3.1, etc. Third of all, the xref should be to + Assigning revisions not commit options. + + * cvs.texinfo (Outside): Comment out sentence which incorrectly + stated that "cvs add" can operate on "foo/bar.c". + +Tue Mar 25 22:21:29 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Error messages): New node. + (Magic branch numbers): Move from Troubleshooting to Revisions and + branches. The former placement never made any sense to me. + (Revision numbers): Remove "Main trunk (intro)" index entry now + that this node is right next to the other "main trunk" index + entry. + (BUGS): Very briefly mention reporting bugs in CVS. + + * cvs.texinfo (Compatibility): Add comment about "Nfoo" in CVS/Tag. + +Mon Mar 24 13:50:24 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Creating a branch): Add comment about -r in branch + example. + + * cvsclient.texi (Responses): Discuss meaning of tagspec and + future expansion in Set-sticky. The behavior described is the one + which CVS has always implemented. + +Fri Mar 21 14:19:05 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Revise meaning of "Case" per change + to CVS. + +Tue Mar 18 15:50:47 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + The following reorganization hopefully presents numeric revisions + in a slightly more coherent fashion. The only new material is the + paragraph about assigning revisions for added files. + * cvs.texinfo (A sample session): Bring in a sentence from Basic + concepts node, defining a repository. + (Revisions and branches): Renamed from Branches (it has always + covered non-branch tags too). Bring in nodes "Revision numbers" and + "Versions revisions releases" from Basic concepts, the former in + particular was way too detailed for an intro section. + (A sample session): Add comment about how we need an introduction + and what might go into one. Also bring in the paragraph from + Basic concepts introducing modules, but comment it out. + (Viewing differences): Add comment about + (Basic concepts): Removed; its content has been farmed out as + described above, and as the comment said, it was fundamentally + flawed. + (Assigning revisions): New node. Incorporates the "New major + release number" subsubsec which was in "commit examples". Add + paragraph concerning how CVS assigns revisions on added files. + (commit options): Refer to that node under -r. + (Invoking CVS): Add comment about text for -r. + +Tue Mar 18 13:04:30 1997 Jim Meyering <meyering@totoro.cyclic.com> + + * Makefile.in: (install-info): Depend on installdirs. + +Sun Mar 16 12:37:12 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (File permissions): CVSUMASK now works for RCS + files; but it is (still) awkward for client/server CVS. + +Sat Mar 15 17:41:12 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Magic branch numbers): Add comment about where this + should go. + +Thu Mar 13 09:11:36 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Credits): Fix grammatical mistake ("manual about" + -> "manual is about"). Reported by Philippe De Muyter. + +Sun Mar 9 09:06:40 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (File permissions): Add comment about val-tags and + CVSUMASK. + +Sun Mar 2 12:33:26 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (From scratch): Add comment about creating + directories with add rather than import. + + * cvs.texinfo (Creating a repository): Add comment about how this + somewhat duplicates Server requirements. + + * cvs.texinfo (Connecting via rsh): Add comment about rsh + vs. remsh. Also wording fix ("incorrect" -> "inapplicable"). + + * cvs.texinfo (Outside): Add comment about renames and annotate. + + * cvs.texinfo (Server requirements): New node. + +Thu Feb 27 15:20:49 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Multiple developers): Reword section on "cvs admin + -l". As nearly as I can tell based on when it came up on info-cvs + and other contexts, people who are into reserved checkouts + generally find that cvs admin -l is OK. Add a bunch more notes + (inside @ignore) about reserved checkout implementation ideas. + +Sun Feb 23 16:12:03 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Common options): Add various additional comments + about date formats. + + * RCSFILES: Remove diff for Id and explain it in words instead. + The previous values for Id had been clobbered by keyword expansion + on the RCSFILES file itself. + +Sat Feb 22 14:16:28 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * Makefile.in (DISTFILES): Fix typo (missing backslash). + +Fri Feb 21 23:08:38 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * RCSFILES: New file. + * Makefile.in (DISTFILES): Add RCSFILES. + +20 Feb 1997 Lenny Foner <foner@media.mit.edu> + + * cvs.texinfo (Checklist): Fix typo ("keword" -> "keyword"). + +Thu Feb 20 21:57:05 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Keeping a checked out copy): Add "web" to index. + +Wed Feb 12 18:44:16 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Password authentication client, Invoking CVS): + Document "cvs logout" command. + +Tue Feb 11 20:42:45 1997 Ian Lance Taylor <ian@cygnus.com> + + * cvs.texinfo (commit options): Document that the -f option to + commit disables recursion. + +Sun Feb 9 13:58:59 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (diff options): Document all the options we pass + through to diff. Remove paragraph about -D sometimes meaning + --ifdef since that is no longer true. + + * cvs.texinfo (Multiple developers): Add lengthy comment about + reserved checkout design issues. + + * cvs.texinfo (Wrappers): Add paragraph about timestamps. + + * cvs.texinfo (commit options): Don't try to document what CVS 1.3 + does with -f and how recent versions differ: 1.3 is pretty old + anyway, we generally only try to document the current version, and + the way it was described here was pretty confusing. + (Environment variables): Likewise for CVSEDITOR. + + * cvs.texinfo (import output): Add index entries for symbolic + links. Add brief mention of whether behavior should be + different. Add comments on other symbolic link issues. + +Wed Feb 5 13:02:37 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Concurrency): Add comment about commit/commit + atomicity. + +Mon Feb 3 10:55:41 1997 joel boutros <nihilis@moral.addiction.com> + + * cvs.texinfo (Connecting via rsh): Fix typo (programs -> problems). + +Fri Jan 31 12:18:47 1997 Ian Lance Taylor <ian@cygnus.com> + + * cvsclient.texi (Connection and Authentication): Correct typo + (``sent'' for ``send''), and rewrite sentence for clarity. + +Fri Jan 24 10:31:57 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (File status): Change "Unresolved Conflict" to "File + had conflicts on merge" per change to CVS. + +Sun Jan 19 16:21:17 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (admin): Add comments about "group" and "compiled in + value". At least one info-cvs poster was confused by this. + +Thu Jan 16 17:54:51 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Wrappers): It is just -t/-f which doesn't work + client/server. -k *does* (well, except for the problem with + import noted in BUGS). -m I don't know and I doubt anyone cares. + +Mon Jan 13 15:41:02 1997 Karl Fogel <kfogel@ynu38.ynu.edu.cn> + + * cvs.texinfo (Read-only access): rephrase to imply that there may + be other administrative files, besides history and locks, which + read-only users can also affect (in the future, for example, the + `passwd' file). + +Wed Jan 8 14:50:47 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * Makefile.in: Remove CVSid; we decided to get rid + of these some time ago. + +Wed Jan 8 09:08:36 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Connection and Authentication): Document + restriction that cvs root sent in the cvs protocol and in the + pserver authentication protocol must be identical. + +Thu Jan 2 13:30:56 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * Makefile.in, cvs.texinfo: Remove "675" paragraph; + see ../ChangeLog for rationale. + +Thu Jan 2 09:34:51 1997 Karl Fogel <kfogel@ynu38.ynu.edu.cn> + + * cvs.texinfo (Read-only access): new node. + (Repository): new menu item for above new node. + (Password authentication server): document the user-aliasing + feature. Why was this undocumented before? + +Wed Jan 1 18:12:11 1997 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Conflicts example): Use @asis in example to prevent + starting a line with a conflict marker. This means that when + maintaining the file with CVS itself, CVS will not think there is + a conflict merely because of the conflict marker in the example. + IMHO, this is totally bogus and CVS needs a better way of figuring + out whether a conflict is resolved (see comments elsewhere in this + node), but until then.... Credit to Fred Fish for reporting the + problem. + + * cvs.texinfo (cvsignore): Add paragraph about how .cvsignore + files in the sources being imported by "cvs import" override + "-I !". Credit goes to Fred Fish for pointing out this problem. + +Thu Dec 19 12:36:46 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Credits): Update Roland Pesch email address per his + request. + +Tue Dec 17 12:57:56 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (verifymsg): In example, remove text "and reedit if + necessary"; it was copied from editinfo and doesn't apply here. + Fix syntax of if statement; remove unnecessary attempt at loop; + don't use -n with echo. Add @appendixsec at start of node. + Add note about how verifymsg cannot change log message. + (editinfo): In paragraph saying editinfo is obsolete, fix various + typos and formatting glitches. Mention -e as well as EDITOR. + (editinfo): In saying that editinfo doesn't get consulted with -m, + -F or client/server, recommend verifymsg. Remove comment which + says, in effect, "we need a feature like verifymsg". + (editinfo example): Change "verifymsg" back to "editinfo" here; + the example is of editinfo not verifymsg. + +Tue Dec 17 12:45:32 1996 Abe Feldman <feldman@cyclic.com> + + * cvs.texinfo (verifymsg): New node. + various places: Say that editinfo is obsolete, or refer to + verifymsg instead of editinfo + +Wed Dec 11 08:55:26 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Compatibility): Add comment about 1.3 and file death. + + * cvs.texinfo (update output, release output): Document "P" as + well as "U". + +Tue Dec 10 16:23:40 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Builds): Change "make" to "implement" and "build"; + in this context "make" is ambiguous. + (Builds): Add new URL of mk web page. + +Mon Dec 9 11:03:37 1996 Jim Blandy <jimb@floss.cyclic.com> + + * cvs.texinfo (Password authentication client, Environment + variables): Remove mention of CVS_PASSWORD. + +Sun Dec 8 22:38:34 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Repository files): Mention differences between RCS + files in RCS and in CVS. + (Tags): Tag names must start with a letter. + +Fri Dec 6 09:08:18 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (syntax): Expand discussion of regular expression + syntax. + +Fri Nov 29 09:06:41 1996 fnf@ninemoons.com (Fred Fish) + and Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo, cvsclient.texi: Make sure @ref and friends are + followed by "," or "." as described in the texinfo manual. This + is a dubious practice as texi2html and texinfo.tex don't require + it, and makeinfo could insert them as needed, but since makeinfo + doesn't do that yet, cope. + + * cvs.texinfo (From files): Suggest "diff -r" rather than "ls -R" + as the way to see that the sources seem to have been imported + correctly. + (Common options): -k is also available with import. + (admin options): Fix typo ("interrested" -> "interested"). + +Mon Nov 25 10:03:56 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Common options): Add comments about two digit + years, year 2000, and ambiguous/nonexistent dates. + +Sun Nov 24 17:27:24 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (First import): Don't say what the wdiff program we + are using as an example does--that is confusing. Also don't show + untarring it--people might be familiar with cpio, ZIP, VMS BACKUP, + etc., instead of tar. + + * cvs.texinfo (Adding files): Update comment about "cvs add -m". + + * cvs.texinfo (Common options): Remove -H; -H is not a command + option. + (Global options): Also list --help and --version. Don't say that + -H gives a list of commands; it doesn't any more (directly). + + * cvs.texinfo: Add comment pointing to paper size web page. + + * cvs.texinfo (Common options): Rewrite section on date formats. + Executive summary is that RFC822 and ISO8601 are now preferred. + +Wed Nov 20 08:39:45 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Getting Notified): Add paragraph clarifying that + watches happen per user, not per working directory. + +Tue Nov 19 09:39:08 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Tags): Suggest that future special tag names might + start with ".". Fix typo. + + * cvs.texinfo (Removing directories): -P is also available with + export. + (Moving directories): Rewrite first paragraph; now says that you + must use -P for the directory to disappear from working + directories. Thanks to Martin Lorentzon + <Martin.Lorentzson@emw.ericsson.se> for reporting this bug. + (various): Where we mention -P, point to Removing directories + node. + +Sat Nov 16 18:03:22 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Example): Rewrite to actually be based on a real + live example (and therefore reflect the way the protocol currently + works). Add comment about formatting of the document itself. + +Thu Nov 14 10:22:58 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Introduction): Use @ref, not @xref, after "see". + (Goals): Rewrite items about locking, about uploading in big + chunks, and about atomicity to be focused more on the protocol + than the current implementation. + (Notes): Remove this node. The attempt to describe the basic + model has pretty much been replaced by the Introduction. + The material about how to start the client is incomplete and + better left to cvs.texinfo. And the item about the lack of + SERVER_FLOWCONTROL is obsolete now that SERVER_FLOWCONTROL is the + default. + (Protocol Notes): Add comment about multisite features. + (Requirements): Use @code for requests and responses. + + * cvs.texinfo (Remote repositories): Add a few sentences defining + "client" and "server"; before we had been using the terms without + defining them. + + * cvs.texinfo (What is CVS?): Add paragraph about reporting bugs. + Reword and expand comp.software.config-mgmt description (and add + comments about other newsgroup facts). Point people at GNU list + of FTP sites rather than directly at prep.ai.mit.edu. + +Wed Nov 6 09:45:08 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Tracking sources): Add comment regarding added and + removed files. + +Tue Nov 5 14:00:31 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Rename node "Invoking CVS" to "CVS commands". + Rewrite the intro and comments to reflect addition of the new + Invoking CVS. + (Invoking CVS): New node, a quick summary of each command. + (annotate): Don't list the options; refer to Invoking CVS and + Common options instead. + +Sun Nov 3 21:22:42 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Compatibility): New node, moved from ../README. + + * cvs.texinfo (Common options): Add comment about how tar manual + contains documentation for getdate date formats. + +Fri Nov 1 14:00:31 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (commit examples): Rewrite "New major release + number" section to tighten up the wording, better motivate the + discussion, and replace the term "rcs revision number" with + "numeric revision". + +Fri Oct 25 07:49:21 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (loginfo): Don't say "a la printf"; the syntax is + only vaguely similar to printf. + + * cvs.texinfo (loginfo): To get just the repository name, suggest + %{} instead of % "standing alone"; the latter is now an error. + +Tue Oct 22 13:08:54 1996 Noel Cragg <noel@gargle.rain.org> + + * cvs.texinfo (loginfo): add information on the new loginfo format + string specification. + +Mon Oct 21 17:33:44 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Builds): New node. + (What is CVS?): Refer to it. + +Sat Oct 19 14:32:21 1996 Jim Meyering <meyering@asic.sc.ti.com> + and Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Choosing a model): Wording/grammar fix. + +Sat Oct 19 14:32:21 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Obsolete): New node. + (Requests): Remove Repository and Lost and adjust Directory, + UseUnchanged, and other places accordingly. + (Required): Directory and Unchanged are now required. + + * cvs.texinfo (Removing files): Don't talk about modules; they are + not relevant in this context. + (Removing directories): New node. + (Common options): Refer to it instead of duplicating information. + +Fri Oct 18 11:05:06 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (First import, import): Add paragraph about the fact + that import doesn't modify the directory which it imports from. + + * cvs.texinfo (Creating a repository): Add paragraph about + resource requirements. + + * cvs.texinfo (Copying): Replace empty node with a copy of the GPL. + +Thu Oct 17 12:10:55 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Adding files): Revise comment to more accurately + reflect the functioning/nonfunctioning status of cvs add -m. + + * cvs.texinfo (Reverting local changes): New node, somewhat based + on the version of this node from 30 Sep 96 change. + (admin options): Refer to it. + + * cvs.texinfo: Reinstate 30 Sep 96 change from A4 to US letter. + + * cvs.texinfo (Concurrency): When telling people how to clean up + locks, tell them to make sure the locks are owned by the person + who has the stale locks. + (update output, release output): Remove text about how CVS doesn't + print "? foo" for directories; CVS has since been changed (see + conflicts-130 in sanity.sh). + +Wed Oct 16 15:01:42 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (history options): Mention new option -x E. + +Mon Oct 14 15:21:25 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Tags): Add paragraph on choosing a convention for + naming tags. + +Thu Oct 10 16:05:26 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (modules): Describe what & does. + +Mon Oct 7 17:20:11 1996 Ian Lance Taylor <ian@cygnus.com> + + * cvs.texinfo (Removing files): Correct apparent cut and paste + error: refer to the removed file, not the added file. + +Tue Oct 1 14:15:33 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Revert all recent changes (the last unscathed one + is the CVSUMASK one from Sunday). For the most part said changes + are for new features which are not appropriate at this stage of + the release process. None of the changes being reverted need to + go into 1.9, that is for sure. + +Mon Sep 30 18:17:34 1996 Greg A. Woods <woods@most.weird.com> + + * cvs.texinfo (Credits): add comment asking if we should update. + Add more detail about printing Letter on A4. + Add some comments about internal comments. + (From files): describe "cvs import -b 1" for importing existing + projects onto the main branch. + (First import): add a couple of helpful hints about naming vendor + and release tags, etc., and regularize the examples with this. + (Tracking sources): noted some reasons why you might use vendor + branches with "cvs import". + (Update imports): mention using "update" in place of "checkout" if + you have an existing working directory. + (Binary files in imports): add sub-menu separator comment. + (Tracking sources): new menu entry "Reverting to vendor release". + (Reverting to vendor release): new node to describe reverting + local changes and optionally using patch(1) to move local changes + forward. + (Global options): describe -D and -g, as well as DIFFBIN and + GREPBIN. + (export examples): add one. + (import options): describe the effect of '-b 1'. + +Mon Sep 30 08:09:53 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Adjust comments concerning A4 vs. US letter, + referring to ../README. + + * cvs.texinfo (Common options): Add comment about dates which CVS + uses in output. + +Sun Sep 29 11:14:16 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Keyword list): Don't mention Name twice. + + * cvs.texinfo (File permissions): Expand CVSUMASK stuff a bit. + (Setting a watch, Environment variables, Global options): Update + index entries for "read-only files, and ...". + + * cvsclient.texi (Requests): State that Gzip-stream is preferred + to gzip-file-contents. Cite RFC1952/1951 rather than just "gzip". + Say that RFC1950/1951 compression is also known as "zlib". + +Sat Sep 28 09:31:45 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Repository): Move all information about the + internal structure of the repository to User modules node. Rename + it to "Repository storage" ("User modules" wasn't particularly + clear). Mention CVSUMASK. Much clarification and + reorganization. + (Basic concepts): Remove material which duplicates what is now in + Repository. Rewrite paragraph introducing modules. + + * cvs.texinfo (Starting a new project): In discussing difficulty + in renaming files, don't refer to "cvs 1.x"--there is no + non-vaporous "cvs 2.x". Reword to reflect that part of the reason + to avoid renames (where possible) is not because of CVS at all, and + to try to give a general impression of how bad CVS issues involved in + renaming are. + +Fri Sep 27 04:23:44 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Adding files): Talk about directories, not modules, + since that is what is meant. Suggest using -kb option to add + rather than running cvs admin after the fact and xref to Binary + files not admin examples. Incorporate information which had been + in "add" node (there was a lot of duplication). Don't document + use of "add" on a directory to take the place of "cvs update -d"; + the latter is simpler and more logical. + (add, add options, add examples): Removed. + (release output, release options): Update xrefs accordingly. + (Adding files, Removing files): Mention the fact that adds and + removes are branch-specific. + (Merging adds and removals): New node. + + * cvs.texinfo (Concurrency): When mentioning RCS locks, use the + term reserved checkouts and xref to the place where we discuss + them in more depth. + +Thu Sep 26 08:26:01 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (log): Add comments about timezones. + (log, Common options): Add index entries for timezone and zone, time. + +Wed Sep 25 11:05:30 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (log options): Add xref to where we describe the + date formats that -d accepts. + (Common options): Don't refer to date formats accepted by co(1); + CVS's rules have never been the same. Add long whiny comment + about what a mess date formats are. + +Tue Sep 24 11:49:02 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (From other version control systems): The RCS file + must not be locked when you copy it to the CVS repository. + + * cvs.texinfo (Editing files): Also discuss how to revert in the + non-watch case. Add some index entries. + + * cvs.texinfo (update output): Add comment about how we *should* + be handling .# files. Mention fact that it is different under + VMS. Add .# to index. + +Fri Sep 20 13:08:33 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Multiple developers): Revise text on reserved + versus unreserved checkouts extensively. Move index entries for + "reserved checkouts" and "RCS-style locking" to here. Add + cross-reference to cvs admin -l. Add new section "Choosing a + model". + (Editing files): Add note about use of the word "checkout". + +Tue Sep 17 00:54:57 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Defining the module): Don't suggest "cvs co + modules"; that depends on a "modules" module being defined which + is not the default which is created by "cvs init". Instead + suggest "cvs co CVSROOT/modules" which should always work. + +Tue Sep 17 00:43:49 1996 VaX#n8 <vax@linkdead.paranoia.com> + and Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Rename by copying): Suggest "cvs tag -d" on the file + "new", not on everything. Also don't suggest deleting branch tags. + +Tue Sep 17 00:34:39 1996 David A. Swierczek <swierczekd@med.ge.com> + + * Makefile.in (install-info): Note whether files are in srcdir and + deal with it rather than cd'ing into srcdir. + +Mon Sep 16 23:33:36 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Wrappers): Add comment about using wrappers to + compress files in the repository. + + * cvs.texinfo (modules): Add comments about how we should be + documenting how -i and friends operate in client/server CVS. + + * cvs.texinfo (File permissions): Describe the need for write + permissions for locks and val-tags. + + * cvs.texinfo (commitinfo): Add comment about using commitinfo to + enforce who has access. + +Wed Jul 24 17:01:41 1996 Larry Jones <larry.jones@sdrc.com> + and Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (checkout): Refer to "update output" node. + (import): Add new import output node. + (release): Correct release output menu entry (used to be + release options instead). + (update output): Say this is output from checkout as well as + update. + +Mon Sep 16 16:18:38 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Common options): Clarify that CVS uses MM/DD/YY dates. + + * cvs.texinfo (Common options): Add comment about what HEAD means. + +Mon Sep 16 10:52:04 1996 Norbert Kiesel <nk@col.sw-ley.de> + + * cvs.texinfo (Global options): Document global '-T' option. + +Sat Sep 14 10:46:58 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Keeping a checked out copy): New node. + +Fri Sep 13 23:55:42 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Magic branch numbers): Delete song and dance about + how cvs log can't cope with magic branches because rlog doesn't + know about them; cvs log no longer calls rlog. Delete item about + how you can't specify a symbolic branch to cvs log; that is fixed. + +Wed Sep 11 22:48:21 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Password authentication server): Add comments + regarding port numbers and troubleshooting. + +Tue Sep 10 10:36:00 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (What is CVS?): Reword text regarding info-cvs, + to avoid overfull hbox. + + * cvs.texinfo (Binary files): Add comment about further issues + with recovering from failure to use -kb. + + * cvs.texinfo (Conflicts example): Describe the "feature" by which + CVS won't check in files with conflicts. + (File status): Expand and revise to document all the possible + statuses from cvs status. Also document "Working revision" and + "Repository revision". Refer to other sections for other aspects + of cvs status. + (status options): Refer to other sections as appropriate. + (update output): Refer user to Conflicts example node. Add + comment regarding purging of .# files. + +Fri Sep 6 11:47:14 1996 Ian Lance Taylor <ian@cygnus.com> + + * cvs.texinfo (Kerberos authenticated): Mention need for + --enable-encryption option in order to use encryption. + (Global options): Likewise, in description of -x option. + +Thu Sep 5 14:31:42 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Connecting via rsh): Discuss :ext:, :server:, and + CVS_RSH. + (Remote repositories): Mention what default is if no access method + is specified. + (Environment variables): Don't discuss CVS_RSH at length here; + rely on reference to "Connecting via rsh" node. + +Mon Aug 26 15:39:18 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Protocol Notes): When talking about having the + client know the original contents of files, suggest cvs edit as a + solution. + +Thu Aug 22 10:44:40 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Keyword list): Document Name keyword. + + * cvs.texinfo (Tags): Revise comment regarding legal tag names. + +Mon Aug 12 14:58:54 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Password authentication security): Add comment + about how some of this is not pserver-specific. + +Tue Aug 6 16:48:53 1996 Ian Lance Taylor <ian@cygnus.com> + + * cvs.texinfo (log, log options): Update for changes to cvs log + now that it no longer invokes rlog. + +Thu Jul 25 10:10:16 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Fix typo (Kerberos-request -> + Kerberos-encrypt). + +Wed Jul 24 18:53:13 1996 Ian Lance Taylor <ian@cygnus.com> + + * cvs.texinfo (Kerberos authenticated): Change the note that the + Kerberos connection is not encrypted. + (Global options): Add documentation for -x. + * cvsclient.texi (Protocol Notes): Remove enhancement note about + Kerberos encryption. + (Requests): Add documentation for Kerberos-encrypt request. + +Thu Jul 18 18:27:40 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Creating a repository): Mention need to be able to + create lock files in the repository. + + * cvsclient.texi (Responses): In F response, make at least a + minimal attempt to define "flush". + + * cvs.texinfo (Wrappers): Document -k. + (From files, Binary files in imports): Say that imports can deal + with binary files and refer to Wrappers node for details. + (Binary files): Likewise for imports and adds. + +Sat Jul 13 18:29:10 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Binary files): Add paragraph concerning the fact + that the keyword expansion mode is not versioned, and why this is + a problem. + +Fri Jul 12 18:55:06 1996 Ian Lance Taylor <ian@cygnus.com> + + * cvsclient.texi (Requests): Document Gzip-stream. + +Thu Jul 11 21:51:45 1996 Ian Lance Taylor <ian@cygnus.com> + + * cvsclient.texi (Responses): Document new "F" response. + +Wed Jul 10 18:46:39 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (log): Don't document "rlog"; it is deprecated. + +Sat Jul 6 22:07:45 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Environment variables): Document more temp + directory nonsense, this time with "patch". + +Fri Jul 5 23:27:40 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Responses): Add comment regarding "/." ending. + +Fri Sep 13 10:52:09 1996 Greg A. Woods <woods@clapton.seachange.com> + + * cvs.texinfo: don't force afourpaper -- Letter prints much better + on A4 than the other way around, believe you me! + (rdiff options): describe -k and new -K. + (RCS keywords): add description of $Name. + (Using keywords): add description of #ident and example of using + $Name. + - also fixed cross references to Substitution modes in various + places. + (import options): mention that -b 1 imports to the trunk. + +Tue Jul 2 22:40:39 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Sticky tags): Update to reflect change in + "resurrected" message. + +Fri Jun 28 10:48:33 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Connecting via rsh): Add comment about what we + might be saying about troubleshooting. + +Sun Jun 23 10:07:45 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Password authentication security): Add comment + regarding anoncvs as practised by OpenBSD. + +Wed Jun 19 15:41:11 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Administrative files): Add xref to Intro + administrative files. + (Intro administrative files): Add comment suggesting future + reorganizations of this material. + (syntax): Add comment regarding this node. + (Getting Notified): Actually document the notify file. It hadn't + really been documented to speak of. + (editinfo,loginfo,rcsfino,cvsignore): Make the index entries + follow the standard "foo (admin file)" format. + +Fri Jun 14 18:14:32 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (editinfo): Discuss the way editinfo falls down in + the face of -m or -F options to commit, or remote CVS. + +Thu Jun 13 15:08:27 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Watches): Add comment discussing the + fact that using cvs edit instead of chmod is not enforced. + + * cvs.texinfo (Setting up): Add index entry for "init (subcommand)". + (Creating a repository): Move contents of node Setting up here... + (Setting up): ...and remove this node. + (Creating a repository): Don't refer to the INSTALL file (it just + refers back to us!). + + * cvsclient.texi (Responses): Document the fact that the server + should send data only when the client is expecting responses. + +Wed Jun 12 16:04:48 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Entries Lines): Add comment regarding specifying + the meaning of "any other" data, in the conflict field. + (Example): Make it clear that using a separate connection for each + command is not required by the protocol. Add some comments + regarding ways in which the example is out of date or wrong. + +Fri Jun 7 18:02:36 1996 Ian Lance Taylor <ian@cygnus.com> + and Jim Kingdon <kingdon@cyclic.com> + + * cvs.texinfo (annotate): Document new -r, -D, and -f options. + +Fri Jun 7 16:59:47 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Invoking CVS): Add comment describing why only some + commands are listed here. + (Structure, Environment variables): Don't describe CVS as a + front-end to RCS. + +Tue Jun 4 21:19:42 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Responses): Document Created and Update-existing. + +Mon Jun 3 17:01:02 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Responses): Clarify "diff -c" versus "diff -u" + format in Patched response. Don't specify how the client must + implement its patch-applying functionality. + +Sun May 26 17:12:24 1996 Norbert Kiesel <nk@col.sw-ley.de> + + * cvs.texinfo (tag options) Document option "-c". + +Thu May 23 21:11:56 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Credits): Rewrite section on FAQ to reflect the + fact that FAQ is no longer maintained. + (What is CVS?): Mention comp.software.config-mgmt as well as + info-cvs. Mention the fact that info-cvs-request can be slow in + responding. + (What is CVS?): Rather than say that cvs is not a configuration + mangement system, say specifically what it lacks (change control, + etc.). I added process control (which was sorely lacking from the + list of configuration management functionality), and deleted some + functions such as tape construction which are not provided by the + well-known configuration management systems. + + * cvs.texinfo (checkout options): Add comment regarding + subdirectories (lack of clarity pointed out by ian@cygnus.com). + Add comment about that infernal "short as possible" wording. + + * cvs.texinfo (Global options): Fix error ("diff" -> "log") + (reported by ian@cygnus.com). + Remove footnote "Yes, this really should be fixed, and it's being + worked on"--it isn't clear what "this" is, and I doubt anyone is + working on it. + +Tue May 21 17:22:18 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Clarify Directory with "." as local + directory, and that filename for Questionable cannot contain "/". + +Mon May 20 13:15:25 1996 Greg A. Woods <woods@most.weird.com> + + * cvs.texinfo (rdiff): description from main.c:cmd_usage + (rtag): description from main.c:cmd_usage + (status): description from main.c:cmd_usage + (tag): description from main.c:cmd_usage + [all for the sake of consistency] + +Fri May 17 11:42:46 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Add index entries for :local:, etc. + (Password authentication server): Revert erroneous change + regarding the format of CVSROOT/passwd file. + +Thu May 16 17:06:46 1996 Noel Cragg <noel@gargle.rain.org> + + * cvsclient.texi (Notes): Removed paragraphs about various server + invocations which are now described in full in node "Connection + and Authentication." + (Requests): Include a note that "gzip-file-contents" doesn't + follow the upper/lowercase convention and that unknown reqests + always elicit a response, regardless of capitalization. + + * cvs.texinfo (Kerberos authenticated): Removed bogus version + number. + (Repository): explain the ":local:" access method. + +Wed May 15 23:43:04 1996 Noel Cragg <noel@gargle.rain.org> + + * cvsclient.texi (Goals): mention access methods. + (Requests): add note about convention: requests starting with a + captial letter don't have any expected response. Made sure each + request has a "Response expected" note. + + * cvs.texinfo (Remote repositories): add info about access + methods; fix pserver info. + +Tue May 14 08:56:41 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Environment variables): Try to document somewhat + more accurately where we put temporary files. + + * cvs.texinfo (From files): Say directory tree instead of module + where that is what we mean. Use @var{wdir} and @var{rdir} in the + example instead of using @var{dir} for two different things. + (From files): Say directory tree instead of module + where that is what we mean. + (Binary files): When using cvs admin -kb, one needs an extra + commit step on non-unix systems. + (Binary files in imports): New node. + (Wrappers): Add comment regarding indent example. + (Top): Don't refer to modules when that is not what we mean. + +Fri May 10 09:39:49 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Sticky tags): Explain what sticky dates and + non-branch sticky tags are good for. + + * cvs.texinfo (Repository): Document that -d overrides CVS/Root. + +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 0000000..2f14099 --- /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/HACKING.DOCS b/contrib/cvs/doc/HACKING.DOCS new file mode 100644 index 0000000..adf6077 --- /dev/null +++ b/contrib/cvs/doc/HACKING.DOCS @@ -0,0 +1,46 @@ +Here's some of the texinfo conventions the CVS documentation uses: + +@code{ ... } command usage & command snippets, including + command names. +@var{ ... } variables - text which the user is expected to + replace with some meaningful text of their own + in actual usage. +@file{ ... } file names +@samp{ ... } for most anything else you need quotes around + (often still misused for command snippets) +@example ... @end example example command usage and output, etc. +@emph{ ... } emphasis - warnings, stress, etc. This will be + bracketed by underline characters in info files + (_ ... _) and in italics in PDF & probably in + postscript & HTML. +@strong{ ... } Similar to @emph{}, but the effect is to + bracket with asterisks in info files (* ... *) + and in bold in PDF & probably in postscript & + HTML. +@noindent Suppresses indentation of the following + paragraph. This can ocassionally be useful + after examples and the like. +@cindex ... Add a tag to the index. +@pxref{ ... } Cross reference in parentheses. +@xref{ ... } Cross reference. + +Preformatted text should be marked as such (use @example... there may be other +ways) since many of the final output formats can use relational fonts otherwise +and marking it as formatted should restrict it to a fixed width font. Keep +this sort of text to 80 characters or less per line since larger may not be +properly viewable for some info users. + +There are dictionary lists and function definition markers. Scan cvs.texinfo +for their usage. There may be table definitions as well but I haven't used +them. + +Use lots of index markers. Scan the index for the current style. Try to reuse +an existing entry if the meaning is similar. + +`makeinfo' 3.11 or greater is required for output generation since earlier +versions do not support the @ifnottex & @ifnothtml commands. There may be +other commands used in `cvs.texinfo' that are unsupported by earlier versions +of `makeinfo' by the time you read this. + +For more on using texinfo docs, see the `info texinfo' documentation or +http://www.gnu.org/manual/texinfo/texinfo.html . diff --git a/contrib/cvs/doc/Makefile.am b/contrib/cvs/doc/Makefile.am new file mode 100644 index 0000000..38d719c --- /dev/null +++ b/contrib/cvs/doc/Makefile.am @@ -0,0 +1,121 @@ +## Process this file with automake to produce Makefile.in +# Makefile for GNU CVS documentation (excluding man pages - see ../man). +# +# Copyright (C) 1986-2005 The Free Software Foundation, Inc. +# +# Portions Copyright (C) 1998-2005 Derek Price, Ximbiot <http://ximbiot.com>, +# and others. + +# 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. + +info_TEXINFOS = cvs.texinfo cvsclient.texi +man_MANS = $(srcdir)/cvs.1 + +PSS = \ + cvs.ps \ + cvs-paper.ps \ + cvsclient.ps + +PDFS = \ + cvs.pdf \ + $(srcdir)/cvs-paper.pdf \ + cvsclient.pdf + +TXTS = \ + cvs.txt \ + cvsclient.txt + +EXTRA_DIST = \ + .cvsignore \ + ChangeLog.fsf \ + RCSFILES \ + mdate-sh \ + $(srcdir)/cvs.1 \ + cvs-paper.ms \ + cvs.man.header \ + cvs.man.footer \ + $(PDFS) + +MOSTLYCLEANFILES = + +CLEANFILES = \ + $(PSS) \ + $(TXTS) + +MAINTAINERCLEANFILES = \ + $(PDFS) \ + $(srcdir)/cvs.1 + +doc: info pdf +.PHONY: doc + +txt: $(TXTS) +.PHONY: txt + +dvi: cvs.dvi cvsclient.dvi +.PHONY: dvi + +# FIXME-AUTOMAKE: +# For some reason if I remove version.texi, it doesn't get built automatically. +# This needs to be fixed in automake. +cvs.txt: cvs.texinfo $(srcdir)/version.texi +cvsclient.txt: cvsclient.texi $(srcdir)/version-client.texi + +# The cvs-paper.pdf target needs to be very specific so that the other PDFs get +# generated correctly. If a more generic .ps.pdf implicit target is defined, +# and cvs.ps is made before cvs.pdf, then cvs.pdf can be generated from the +# .ps.pdf target and the PS source, which contains less information (hyperlinks +# and such) than the usual texinfo source. +# +# It is possible that an implicit .ms.ps target could be safely defined. I +# don't recall looking into it. +cvs-paper.ps: cvs-paper.ms + $(ROFF) -t -p -ms -Tps $(srcdir)/cvs-paper.ms >cvs-paper.ps-t + cp cvs-paper.ps-t $@ + -@rm -f cvs-paper.ps-t + +# This rule introduces some redundancy, but `make distcheck' requires that +# Nothing in $(srcdir) be rebuilt, and this will always be rebuilt when it +# is dependant on cvs-paper.ps and cvs-paper.ps isn't distributed. +$(srcdir)/cvs-paper.pdf: cvs-paper.ms + $(ROFF) -t -p -ms -Tps $(srcdir)/cvs-paper.ms >cvs-paper.ps-t + ps2pdf cvs-paper.ps-t cvs-paper.pdf-t + cp cvs-paper.pdf-t $@ + -@rm -f cvs-paper.pdf-t cvs-paper.ps-t + +MOSTLYCLEANFILES += cvs-paper.pdf-t cvs-paper.ps-t + +# Targets to build a man page from cvs.texinfo. +$(srcdir)/cvs.1: @MAINTAINER_MODE_TRUE@ mkman cvs.man.header cvs.texinfo cvs.man.footer + $(PERL) ./mkman $(srcdir)/cvs.man.header $(srcdir)/cvs.texinfo \ + $(srcdir)/cvs.man.footer >cvs.tmp + cp cvs.tmp $(srcdir)/cvs.1 + -@rm -f cvs.tmp + +# texinfo based targets automake neglects to include +SUFFIXES = .txt +.texinfo.txt: + $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + --no-headers -o $@ `test -f '$<' || echo '$(srcdir)/'`$< +.txi.txt: + $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + --no-headers -o $@ `test -f '$<' || echo '$(srcdir)/'`$< +.texi.txt: + $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + --no-headers -o $@ `test -f '$<' || echo '$(srcdir)/'`$< + +## +## MAINTAINER Targets +## + +# for backwards compatibility with the old makefiles +realclean: maintainer-clean +.PHONY: realclean diff --git a/contrib/cvs/doc/Makefile.in b/contrib/cvs/doc/Makefile.in new file mode 100644 index 0000000..f3a2087 --- /dev/null +++ b/contrib/cvs/doc/Makefile.in @@ -0,0 +1,816 @@ +# Makefile.in generated by automake 1.10 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006 Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# Makefile for GNU CVS documentation (excluding man pages - see ../man). +# +# Copyright (C) 1986-2005 The Free Software Foundation, Inc. +# +# Portions Copyright (C) 1998-2005 Derek Price, Ximbiot <http://ximbiot.com>, +# and others. + +# 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. +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +subdir = doc +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in \ + $(srcdir)/mkman.pl $(srcdir)/stamp-1 $(srcdir)/stamp-vti \ + $(srcdir)/version-client.texi $(srcdir)/version.texi ChangeLog \ + mdate-sh texinfo.tex +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.in +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = mkman +SOURCES = +DIST_SOURCES = +INFO_DEPS = $(srcdir)/cvs.info $(srcdir)/cvsclient.info +am__TEXINFO_TEX_DIR = $(srcdir) +DVIS = cvs.dvi cvsclient.dvi +HTMLS = cvs.html cvsclient.html +TEXINFOS = cvs.texinfo cvsclient.texi +TEXI2PDF = $(TEXI2DVI) --pdf --batch +MAKEINFOHTML = $(MAKEINFO) --html +AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) +DVIPS = dvips +am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)" +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = `echo $$p | sed -e 's|^.*/||'`; +man1dir = $(mandir)/man1 +NROFF = nroff +MANS = $(man_MANS) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CSH = @CSH@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EDITOR = @EDITOR@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +GREP = @GREP@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +KRB4 = @KRB4@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MKDIR_P = @MKDIR_P@ +MKTEMP = @MKTEMP@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +PR = @PR@ +PS2PDF = @PS2PDF@ +RANLIB = @RANLIB@ +ROFF = @ROFF@ +SENDMAIL = @SENDMAIL@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +TEXI2DVI = @TEXI2DVI@ +VERSION = @VERSION@ +YACC = @YACC@ +YFLAGS = @YFLAGS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +ac_prefix_program = @ac_prefix_program@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build_alias = @build_alias@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host_alias = @host_alias@ +htmldir = @htmldir@ +includedir = @includedir@ +includeopt = @includeopt@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +with_default_rsh = @with_default_rsh@ +with_default_ssh = @with_default_ssh@ +info_TEXINFOS = cvs.texinfo cvsclient.texi +man_MANS = $(srcdir)/cvs.1 +PSS = \ + cvs.ps \ + cvs-paper.ps \ + cvsclient.ps + +PDFS = \ + cvs.pdf \ + $(srcdir)/cvs-paper.pdf \ + cvsclient.pdf + +TXTS = \ + cvs.txt \ + cvsclient.txt + +EXTRA_DIST = \ + .cvsignore \ + ChangeLog.fsf \ + RCSFILES \ + mdate-sh \ + $(srcdir)/cvs.1 \ + cvs-paper.ms \ + cvs.man.header \ + cvs.man.footer \ + $(PDFS) + +MOSTLYCLEANFILES = cvs-paper.pdf-t cvs-paper.ps-t +CLEANFILES = \ + $(PSS) \ + $(TXTS) + +MAINTAINERCLEANFILES = \ + $(PDFS) \ + $(srcdir)/cvs.1 + + +# texinfo based targets automake neglects to include +SUFFIXES = .txt +all: all-am + +.SUFFIXES: +.SUFFIXES: .txt .dvi .html .info .pdf .ps .texi .texinfo .txi +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ + && exit 0; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \ + cd $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +mkman: $(top_builddir)/config.status $(srcdir)/mkman.pl + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ + +.texinfo.info: + restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + am__cwd=`pwd` && cd $(srcdir) && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + cd "$$am__cwd"; \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ $<; \ + then \ + rc=0; \ + cd $(srcdir); \ + else \ + rc=$$?; \ + cd $(srcdir) && \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +.texinfo.dvi: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $< + +.texinfo.pdf: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $< + +.texinfo.html: + rm -rf $(@:.html=.htp) + if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) $<; \ + then \ + rm -rf $@; \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ + else \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ + exit 1; \ + fi +$(srcdir)/cvs.info: cvs.texinfo $(srcdir)/version.texi +cvs.dvi: cvs.texinfo $(srcdir)/version.texi +cvs.pdf: cvs.texinfo $(srcdir)/version.texi +cvs.html: cvs.texinfo $(srcdir)/version.texi +$(srcdir)/version.texi: @MAINTAINER_MODE_TRUE@ $(srcdir)/stamp-vti +$(srcdir)/stamp-vti: cvs.texinfo $(top_srcdir)/configure + @(dir=.; test -f ./cvs.texinfo || dir=$(srcdir); \ + set `$(SHELL) $(srcdir)/mdate-sh $$dir/cvs.texinfo`; \ + echo "@set UPDATED $$1 $$2 $$3"; \ + echo "@set UPDATED-MONTH $$2 $$3"; \ + echo "@set EDITION $(VERSION)"; \ + echo "@set VERSION $(VERSION)") > vti.tmp + @cmp -s vti.tmp $(srcdir)/version.texi \ + || (echo "Updating $(srcdir)/version.texi"; \ + cp vti.tmp $(srcdir)/version.texi) + -@rm -f vti.tmp + @cp $(srcdir)/version.texi $@ + +mostlyclean-vti: + -rm -f vti.tmp + +maintainer-clean-vti: +@MAINTAINER_MODE_TRUE@ -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi + +.texi.info: + restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + am__cwd=`pwd` && cd $(srcdir) && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + cd "$$am__cwd"; \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ $<; \ + then \ + rc=0; \ + cd $(srcdir); \ + else \ + rc=$$?; \ + cd $(srcdir) && \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +.texi.dvi: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $< + +.texi.pdf: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $< + +.texi.html: + rm -rf $(@:.html=.htp) + if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) $<; \ + then \ + rm -rf $@; \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ + else \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ + exit 1; \ + fi +$(srcdir)/cvsclient.info: cvsclient.texi $(srcdir)/version-client.texi +cvsclient.dvi: cvsclient.texi $(srcdir)/version-client.texi +cvsclient.pdf: cvsclient.texi $(srcdir)/version-client.texi +cvsclient.html: cvsclient.texi $(srcdir)/version-client.texi +$(srcdir)/version-client.texi: @MAINTAINER_MODE_TRUE@ $(srcdir)/stamp-1 +$(srcdir)/stamp-1: cvsclient.texi $(top_srcdir)/configure + @(dir=.; test -f ./cvsclient.texi || dir=$(srcdir); \ + set `$(SHELL) $(srcdir)/mdate-sh $$dir/cvsclient.texi`; \ + echo "@set UPDATED $$1 $$2 $$3"; \ + echo "@set UPDATED-MONTH $$2 $$3"; \ + echo "@set EDITION $(VERSION)"; \ + echo "@set VERSION $(VERSION)") > 1.tmp + @cmp -s 1.tmp $(srcdir)/version-client.texi \ + || (echo "Updating $(srcdir)/version-client.texi"; \ + cp 1.tmp $(srcdir)/version-client.texi) + -@rm -f 1.tmp + @cp $(srcdir)/version-client.texi $@ + +mostlyclean-1: + -rm -f 1.tmp + +maintainer-clean-1: +@MAINTAINER_MODE_TRUE@ -rm -f $(srcdir)/stamp-1 $(srcdir)/version-client.texi +.dvi.ps: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + $(DVIPS) -o $@ $< + +uninstall-dvi-am: + @$(NORMAL_UNINSTALL) + @list='$(DVIS)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ + rm -f "$(DESTDIR)$(dvidir)/$$f"; \ + done + +uninstall-html-am: + @$(NORMAL_UNINSTALL) + @list='$(HTMLS)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ + rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ + done + +uninstall-info-am: + @$(PRE_UNINSTALL) + @if test -d '$(DESTDIR)$(infodir)' && \ + (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ + install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ + (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \ + echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ + rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ + else :; fi); \ + done + +uninstall-pdf-am: + @$(NORMAL_UNINSTALL) + @list='$(PDFS)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ + rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ + done + +uninstall-ps-am: + @$(NORMAL_UNINSTALL) + @list='$(PSS)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ + rm -f "$(DESTDIR)$(psdir)/$$f"; \ + done + +dist-info: $(INFO_DEPS) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + case $$base in \ + $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$base; then d=.; else d=$(srcdir); fi; \ + base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \ + for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \ + if test -f $$file; then \ + relfile=`expr "$$file" : "$$d/\(.*\)"`; \ + test -f $(distdir)/$$relfile || \ + cp -p $$file $(distdir)/$$relfile; \ + else :; fi; \ + done; \ + done + +mostlyclean-aminfo: + -rm -rf cvs.aux cvs.cp cvs.cps cvs.fn cvs.fns cvs.ky cvs.kys cvs.log cvs.pg \ + cvs.pgs cvs.tmp cvs.toc cvs.tp cvs.tps cvs.vr cvs.vrs \ + cvs.dvi cvs.pdf cvs.ps cvs.html cvsclient.aux cvsclient.cp \ + cvsclient.cps cvsclient.fn cvsclient.fns cvsclient.ky \ + cvsclient.kys cvsclient.log cvsclient.pg cvsclient.pgs \ + cvsclient.tmp cvsclient.toc cvsclient.tp cvsclient.tps \ + cvsclient.vr cvsclient.vrs cvsclient.dvi cvsclient.pdf \ + cvsclient.ps cvsclient.html + +maintainer-clean-aminfo: + @list='$(INFO_DEPS)'; for i in $$list; do \ + i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ + echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ + rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ + done +install-man1: $(man1_MANS) $(man_MANS) + @$(NORMAL_INSTALL) + test -z "$(man1dir)" || $(MKDIR_P) "$(DESTDIR)$(man1dir)" + @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.1*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ + else file=$$i; fi; \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 1*) ;; \ + *) ext='1' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst"; \ + done +uninstall-man1: + @$(NORMAL_UNINSTALL) + @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ + l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ + for i in $$l2; do \ + case "$$i" in \ + *.1*) list="$$list $$i" ;; \ + esac; \ + done; \ + for i in $$list; do \ + ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 1*) ;; \ + *) ext='1' ;; \ + esac; \ + inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ + inst=`echo $$inst | sed -e 's/^.*\///'`; \ + inst=`echo $$inst | sed '$(transform)'`.$$ext; \ + echo " rm -f '$(DESTDIR)$(man1dir)/$$inst'"; \ + rm -f "$(DESTDIR)$(man1dir)/$$inst"; \ + done +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + fi; \ + cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + else \ + test -f $(distdir)/$$file \ + || cp -p $$d/$$file $(distdir)/$$file \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-info +check-am: all-am +check: check-am +all-am: Makefile $(INFO_DEPS) $(MANS) +installdirs: + for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + -test -z "$(MOSTLYCLEANFILES)" || rm -f $(MOSTLYCLEANFILES) + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." + -test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES) +clean: clean-am + +clean-am: clean-generic mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi-am: $(DVIS) + +html: html-am + +html-am: $(HTMLS) + +info: info-am + +info-am: $(INFO_DEPS) + +install-data-am: install-info-am install-man + +install-dvi: install-dvi-am + +install-dvi-am: $(DVIS) + @$(NORMAL_INSTALL) + test -z "$(dvidir)" || $(MKDIR_P) "$(DESTDIR)$(dvidir)" + @list='$(DVIS)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(dvidir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(dvidir)/$$f"; \ + done +install-exec-am: + +install-html: install-html-am + +install-html-am: $(HTMLS) + @$(NORMAL_INSTALL) + test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)" + @list='$(HTMLS)'; for p in $$list; do \ + if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + if test -d "$$d$$p"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f"; \ + else \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(htmldir)/$$f"; \ + fi; \ + done +install-info: install-info-am + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + test -z "$(infodir)" || $(MKDIR_P) "$(DESTDIR)$(infodir)" + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ + for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + if test -f $$ifile; then \ + relfile=`echo "$$ifile" | sed 's|^.*/||'`; \ + echo " $(INSTALL_DATA) '$$ifile' '$(DESTDIR)$(infodir)/$$relfile'"; \ + $(INSTALL_DATA) "$$ifile" "$(DESTDIR)$(infodir)/$$relfile"; \ + else : ; fi; \ + done; \ + done + @$(POST_INSTALL) + @if (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ + install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ + done; \ + else : ; fi +install-man: install-man1 + +install-pdf: install-pdf-am + +install-pdf-am: $(PDFS) + @$(NORMAL_INSTALL) + test -z "$(pdfdir)" || $(MKDIR_P) "$(DESTDIR)$(pdfdir)" + @list='$(PDFS)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(pdfdir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \ + done +install-ps: install-ps-am + +install-ps-am: $(PSS) + @$(NORMAL_INSTALL) + test -z "$(psdir)" || $(MKDIR_P) "$(DESTDIR)$(psdir)" + @list='$(PSS)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(psdir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(psdir)/$$f"; \ + done +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-1 \ + maintainer-clean-aminfo maintainer-clean-generic \ + maintainer-clean-vti + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-1 mostlyclean-aminfo mostlyclean-generic \ + mostlyclean-vti + +pdf: pdf-am + +pdf-am: $(PDFS) + +ps: ps-am + +ps-am: $(PSS) + +uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-man uninstall-pdf-am uninstall-ps-am + +uninstall-man: uninstall-man1 + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic dist-info \ + distclean distclean-generic distdir dvi dvi-am html html-am \ + info info-am install install-am install-data install-data-am \ + install-dvi install-dvi-am install-exec install-exec-am \ + install-html install-html-am install-info install-info-am \ + install-man install-man1 install-pdf install-pdf-am install-ps \ + install-ps-am install-strip installcheck installcheck-am \ + installdirs maintainer-clean maintainer-clean-1 \ + maintainer-clean-aminfo maintainer-clean-generic \ + maintainer-clean-vti mostlyclean mostlyclean-1 \ + mostlyclean-aminfo mostlyclean-generic mostlyclean-vti pdf \ + pdf-am ps ps-am uninstall uninstall-am uninstall-dvi-am \ + uninstall-html-am uninstall-info-am uninstall-man \ + uninstall-man1 uninstall-pdf-am uninstall-ps-am + + +doc: info pdf +.PHONY: doc + +txt: $(TXTS) +.PHONY: txt + +dvi: cvs.dvi cvsclient.dvi +.PHONY: dvi + +# FIXME-AUTOMAKE: +# For some reason if I remove version.texi, it doesn't get built automatically. +# This needs to be fixed in automake. +cvs.txt: cvs.texinfo $(srcdir)/version.texi +cvsclient.txt: cvsclient.texi $(srcdir)/version-client.texi + +# The cvs-paper.pdf target needs to be very specific so that the other PDFs get +# generated correctly. If a more generic .ps.pdf implicit target is defined, +# and cvs.ps is made before cvs.pdf, then cvs.pdf can be generated from the +# .ps.pdf target and the PS source, which contains less information (hyperlinks +# and such) than the usual texinfo source. +# +# It is possible that an implicit .ms.ps target could be safely defined. I +# don't recall looking into it. +cvs-paper.ps: cvs-paper.ms + $(ROFF) -t -p -ms -Tps $(srcdir)/cvs-paper.ms >cvs-paper.ps-t + cp cvs-paper.ps-t $@ + -@rm -f cvs-paper.ps-t + +# This rule introduces some redundancy, but `make distcheck' requires that +# Nothing in $(srcdir) be rebuilt, and this will always be rebuilt when it +# is dependant on cvs-paper.ps and cvs-paper.ps isn't distributed. +$(srcdir)/cvs-paper.pdf: cvs-paper.ms + $(ROFF) -t -p -ms -Tps $(srcdir)/cvs-paper.ms >cvs-paper.ps-t + ps2pdf cvs-paper.ps-t cvs-paper.pdf-t + cp cvs-paper.pdf-t $@ + -@rm -f cvs-paper.pdf-t cvs-paper.ps-t + +# Targets to build a man page from cvs.texinfo. +$(srcdir)/cvs.1: @MAINTAINER_MODE_TRUE@ mkman cvs.man.header cvs.texinfo cvs.man.footer + $(PERL) ./mkman $(srcdir)/cvs.man.header $(srcdir)/cvs.texinfo \ + $(srcdir)/cvs.man.footer >cvs.tmp + cp cvs.tmp $(srcdir)/cvs.1 + -@rm -f cvs.tmp +.texinfo.txt: + $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + --no-headers -o $@ `test -f '$<' || echo '$(srcdir)/'`$< +.txi.txt: + $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + --no-headers -o $@ `test -f '$<' || echo '$(srcdir)/'`$< +.texi.txt: + $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + --no-headers -o $@ `test -f '$<' || echo '$(srcdir)/'`$< + +# for backwards compatibility with the old makefiles +realclean: maintainer-clean +.PHONY: realclean +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/contrib/cvs/doc/RCSFILES b/contrib/cvs/doc/RCSFILES new file mode 100644 index 0000000..4650337 --- /dev/null +++ b/contrib/cvs/doc/RCSFILES @@ -0,0 +1,276 @@ +It would be nice if the RCS file format (which is implemented by a +great many tools, both free and non-free, both by calling GNU RCS and +by reimplementing access to RCS files) were documented in some +standard separate from any one tool. But as far as I know no such +standard exists. Hence this file. + +The place to start is the rcsfile.5 manpage in the GNU RCS 5.7 +distribution. Then look at the diff at the end of this file (which +contains a few fixes and clarifications to that manpage). + +If you are interested in MKS RCS, src/ci.c in GNU RCS 5.7 has a +comment about their date format. However, as far as we know there +isn't really any document describing MKS's changes to the RCS file +format. + +The rcsfile.5 manpage does not document what goes in the "text" field +for each revision. The answer is that the head revision contains the +contents of that revision and every other revision contain a bunch of +edits to produce that revision ("a" and "d" lines). The GNU diff +manual (the version I looked at was for GNU diff 2.4) documents this +format somewhat (as the "RCS output format"), but the presentation is +a bit confusing as it is all tangled up with the documentation of +several other output formats. If you just want some source code to +look at, the part of CVS which applies these is RCS_deltas in +src/rcs.c. + +The rcsfile.5 documentation only _very_ briefly touches on the order +of the revisions. The order _is_ important and CVS relies on it. +Here is an example of what I was able to find, based on the join3 +sanity.sh testcase (and the behavior I am documenting here seems to be +the same for RCS 5.7 and CVS 1.9.27): + + 1.1 -----------------> 1.2 + \---> 1.1.2.1 \---> 1.2.2.1 + +Here is how this shows up in the RCS file (omitting irrelevant parts): + + admin: head 1.2; + deltas: + 1.2 branches 1.2.2.1; next 1.1; + 1.1 branches 1.1.2.1; next; + 1.1.2.1 branches; next; + 1.2.2.1 branches; next; + deltatexts: + 1.2 + 1.2.2.1 + 1.1 + 1.1.2.1 + +Yes, the order seems to differ between the deltas and the deltatexts. +I have no idea how much of this should actually be considered part of +the RCS file format, and how much programs reading it should expect to +encounter any order. + +The rcsfile.5 grammar shows the {num} after "next" as optional; if it +is omitted then there is no next delta node (for example 1.1 or the +head of a branch will typically have no next). + +There is one case where CVS uses CVS-specific, non-compatible changes +to the RCS file format, and this is magic branches. See cvs.texinfo +for more information on them. CVS also sets the RCS state to "dead" +to indicate that a file does not exist in a given revision (this is +stored just as any other RCS state is). + +The RCS file format allows quite a variety of extensions to be added +in a compatible manner by use of the "newphrase" feature documented in +rcsfile.5. We won't try to document extensions not used by CVS in any +detail, but we will briefly list them. Each occurrence of a newphrase +begins with an identifier, which is what we list here. Future +designers of extensions are strongly encouraged to pick +non-conflicting identifiers. Note that newphrase occurs several +places in the RCS grammar, and a given extension may not be legal in +all locations. However, it seems better to reserve a particular +identifier for all locations, to avoid confusion and complicated +rules. + + Identifier Used by + ---------- ------- + namespace RCS library done at Silicon Graphics Inc. (SGI) in 1996 + (a modified RCS 5.7--not sure it has any other name). + dead A set of RCS patches developed by Rich Pixley at + Cygnus about 1992. These were for CVS, and predated + the current CVS death support, which uses a state "dead" + rather than a "dead" newphrase. + +CVS does use newphrases to implement the `PreservePermissions' +extension introduced in CVS 1.9.26. The following new keywords are +defined when PreservePermissions=yes: + + owner + group + permissions + special + symlink + hardlinks + +The contents of the `owner' and `group' field should be a numeric uid +and a numeric gid, respectively, representing the user and group who +own the file. The `permissions' field contains an octal integer, +representing the permissions that should be applied to the file. The +`special' field contains two words; the first must be either `block' +or `character', and the second is the file's device number. The +`symlink' field should be present only in files which are symbolic +links to other files, and absent on all regular files. The +`hardlinks' field contains a list of filenames to which the current +file is linked, in alphabetical order. Because files often contain +characters special to RCS, like `.' and sometimes even contain spaces +or eight-bit characters, the filenames in the hardlinks field will +usually be enclosed in RCS strings. For example: + + hardlinks README @install.txt@ @Installation Notes@; + +The hardlinks field should always include the name of the current +file. That is, in the repository file README,v, any hardlinks fields +in the delta nodes should include `README'; CVS will not operate +properly if this is not done. + +The rules regarding keyword expansion are not documented along with +the rest of the RCS file format; they are documented in the co(1) +manpage in the RCS 5.7 distribution. See also the "Keyword +substitution" chapter of cvs.texinfo. The co(1) manpage refers to +special behavior if the log prefix for the $Log keyword is /* or (*. +RCS 5.7 produces a warning whenever it behaves that way, and current +versions of CVS do not handle this case in a special way (CVS 1.9 and +earlier invoke RCS to perform keyword expansion). + +Note that if the "expand" keyword is omitted from the RCS file, the +default is "kv". + +Note that the "comment {string};" syntax from rcsfile.5 specifies a +comment leader, which affects expansion of the $Log keyword for old +versions of RCS. The comment leader is not used by RCS 5.7 or current +versions of CVS. + +Both RCS 5.7 and current versions of CVS handle the $Log keyword in a +different way if the log message starts with "checked in with -k by ". +I don't think this behavior is documented anywhere. + +Here is a clarification regarding characters versus bytes in certain +character sets like JIS and Big5: + + The RCS file format, as described in the rcsfile(5) man page, is + actually byte-oriented, not character-oriented, despite hints to + the contrary in the man page. This distinction is important for + multibyte characters. For example, if a multibyte character + contains a `@' byte, the `@' must be doubled within strings in RCS + files, since RCS uses `@' bytes as escapes. + + This point is not an issue for encodings like ISO 8859, which do + not have multibyte characters. Nor is it an issue for encodings + like UTF-8 and EUC-JIS, which never uses ASCII bytes within a + multibyte character. It is an issue only for multibyte encodings + like JIS and BIG5, which _do_ usurp ASCII bytes. + + If `@' doubling occurs within a multibyte char, the resulting RCS + file is not a properly encoded text file. Instead, it is a byte + stream that does not use a consistent character encoding that can + be understood by the usual text tools, since doubling `@' messes + up the encoding. This point affects only programs that examine + the RCS files -- it doesn't affect the external RCS interface, as + the RCS commands always give you the properly encoded text files + and logs (assuming that you always check in properly encoded + text). + + CVS 1.10 (and earlier) probably has some bugs in this area on + systems where a C "char" is signed and where the data contains + bytes with the eighth bit set. + +One common concern about the RCS file format is the fact that to get +the head of a branch, one must apply deltas from the head of the trunk +to the branchpoint, and then from the branchpoint to the head of the +branch. While more detailed analyses might be worth doing, we will +note: + + * The performance bottleneck for CVS generally is figuring out which + files to operate on and that sort of thing, not applying deltas. + + * Here is one quick test (probably not a very good test; a better test + would use a normally sized file (say 50-200K) instead of a small one): + + I just did a quick test with a small file (on a Sun Ultra 1/170E + running Solaris 5.5.1), with 1000 revisions on the main branch and + 1000 revisions on branch that forked at the root (i.e., RCS revisions + 1.1, 1.2, ..., 1.1000, and branch revisions 1.1.1.1, 1.1.1.2, ..., + 1.1.1.1000). It took about 0.15 seconds real time to check in the + first revision, and about 0.6 seconds to check in and 0.3 seconds to + retrieve revision 1.1.1.1000 (the worst case). + + * Any attempt to "fix" this problem should be careful not to interfere + with other features, such as lightweight creation of branches + (particularly using CVS magic branches). + +Diff follows: + +(Note that in the following diff the old value for the Id keyword was: + Id: rcsfile.5in,v 5.6 1995/06/05 08:28:35 eggert Exp +and the new one was: + Id: rcsfile.5in,v 5.7 1996/12/09 17:31:44 eggert Exp +but since this file itself might be subject to keyword expansion I +haven't included a diff for that fact). + +=================================================================== +RCS file: RCS/rcsfile.5in,v +retrieving revision 5.6 +retrieving revision 5.7 +diff -u -r5.6 -r5.7 +--- rcsfile.5in 1995/06/05 08:28:35 5.6 ++++ rcsfile.5in 1996/12/09 17:31:44 5.7 +@@ -85,7 +85,8 @@ + .LP + \f2sym\fP ::= {\f2digit\fP}* \f2idchar\fP {\f2idchar\fP | \f2digit\fP}* + .LP +-\f2idchar\fP ::= any visible graphic character except \f2special\fP ++\f2idchar\fP ::= any visible graphic character, ++ except \f2digit\fP or \f2special\fP + .LP + \f2special\fP ::= \f3$\fP | \f3,\fP | \f3.\fP | \f3:\fP | \f3;\fP | \f3@\fP + .LP +@@ -119,12 +120,23 @@ + the minute (00\-59), + and + .I ss +-the second (00\-60). ++the second (00\-59). ++If + .I Y +-contains just the last two digits of the year +-for years from 1900 through 1999, +-and all the digits of years thereafter. +-Dates use the Gregorian calendar; times use UTC. ++contains exactly two digits, ++they are the last two digits of a year from 1900 through 1999; ++otherwise, ++.I Y ++contains all the digits of the year. ++Dates use the Gregorian calendar. ++Times use UTC, except that for portability's sake leap seconds are not allowed; ++implementations that support leap seconds should output ++.B 59 ++for ++.I ss ++during an inserted leap second, and should accept ++.B 59 ++for a deleted leap second. + .PP + The + .I newphrase +@@ -144,16 +156,23 @@ + field in order of decreasing numbers. + The + .B head +-field in the +-.I admin +-node points to the head of that sequence (i.e., contains ++field points to the head of that sequence (i.e., contains + the highest pair). + The + .B branch +-node in the admin node indicates the default ++field indicates the default + branch (or revision) for most \*r operations. + If empty, the default + branch is the highest branch on the trunk. ++The ++.B symbols ++field associates symbolic names with revisions. ++For example, if the file contains ++.B "symbols rr:1.1;" ++then ++.B rr ++is a name for revision ++.BR 1.1 . + .PP + All + .I delta + diff --git a/contrib/cvs/doc/cvs-paper.ms b/contrib/cvs/doc/cvs-paper.ms new file mode 100644 index 0000000..ea9445a --- /dev/null +++ b/contrib/cvs/doc/cvs-paper.ms @@ -0,0 +1,1069 @@ +.\" 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. +.\" +.\" 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.1 b/contrib/cvs/doc/cvs.1 new file mode 100644 index 0000000..70f2bec --- /dev/null +++ b/contrib/cvs/doc/cvs.1 @@ -0,0 +1,3968 @@ +.\" This is the man page for CVS. It is auto-generated from the +.\" cvs.man.header, cvs.texinfo, & cvs.man.footer files. Please make changes +.\" there. A full copyright & license notice may also be found in cvs.texinfo. +.\" +.\" Man page autogeneration, including this header file, is +.\" Copyright 2004-2005 The Free Software Foundation, Inc., +.\" Derek R. Price, & Ximbiot <http://ximbiot.com>. +.\" +.\" This documentation 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 documentation 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 documentation; if not, write to the Free Software +.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +.de Id +.ds Rv \\$3 +.ds Dt \\$4 +.. +.TH CVS 1 "\*(Dt" +.\" Full space in nroff; half space in troff +.de SP +.if n .sp +.if t .sp .5 +.. +.\" quoted command +.de ` +.RB ` "\|\\$1\|" '\\$2 +.. +.SH "NAME" +cvs \- Concurrent Versions System +.SH "SYNOPSIS" +.TP +\fBcvs\fP [ \fIcvs_options\fP ] +.I cvs_command +[ +.I command_options +] [ +.I command_args +] +.SH "NOTE" +.IX "revision control system" "\fLcvs\fR" +.IX cvs "" "\fLcvs\fP \- concurrent versions system" +.IX "concurrent versions system \- \fLcvs\fP" +.IX "release control system" "cvs command" "" "\fLcvs\fP \- concurrent versions system" +.IX "source control system" "cvs command" "" "\fLcvs\fP \- concurrent versions system" +.IX revisions "cvs command" "" "\fLcvs\fP \- source control" +This manpage is a summary of some of the features of +\fBcvs\fP. It is auto-generated from an appendix of the CVS manual. +For more in-depth documentation, please consult the +Cederqvist manual (via the +.B info CVS +command or otherwise, +as described in the SEE ALSO section of this manpage). Cross-references +in this man page refer to nodes in the same. +.SH "CVS commands" +.SS "Guide to CVS commands" +.SP +This appendix describes the overall structure of +\fBcvs\fR commands, and describes some commands in +detail (others are described elsewhere; for a quick +reference to \fBcvs\fR commands, see node `Invoking CVS\(aq in the CVS manual). +.SP +.SH "Structure" +.SS "Overall structure of CVS commands" +.IX "Structure" +.IX "CVS command structure" +.IX "Command structure" +.IX "Format of CVS commands" +.SP +The overall format of all \fBcvs\fR commands is: +.SP +.PD 0 +.SP +.IP "" 2 +cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] + +.PD +.IP "" 0 +.SP +.IP "" 0 +\fBcvs\fR +.IP "" 2 +The name of the \fBcvs\fR program. +.SP +.IP "" 0 +\fBcvs_options\fR +.IP "" 2 +Some options that affect all sub-commands of \fBcvs\fR. These are +described below. +.SP +.IP "" 0 +\fBcvs_command\fR +.IP "" 2 +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 \fBcvs_command\fR: \fBcvs -H\fR elicits a +list of available commands, and \fBcvs -v\fR displays version +information on \fBcvs\fR itself. +.SP +.IP "" 0 +\fBcommand_options\fR +.IP "" 2 +Options that are specific for the command. +.SP +.IP "" 0 +\fBcommand_args\fR +.IP "" 2 +Arguments to the commands. +.SP +There is unfortunately some confusion between +\fBcvs_options\fR and \fBcommand_options\fR. +When given as a \fBcvs_option\fR, some options only +affect some of the commands. When given as a +\fBcommand_option\fR it may have a different meaning, and +be accepted by more commands. In other words, do not +take the above categorization too seriously. Look at +the documentation instead. +.SP +.SH "Exit status" +.SS "CVS\(aqs exit status" +.IX "Exit status, of CVS" +.SP +\fBcvs\fR can indicate to the calling environment whether it +succeeded or failed by setting its \fIexit status\fR. +The exact way of testing the exit status will vary from +one operating system to another. For example in a unix +shell script the \fB$?\fR variable will be 0 if the +last command returned a successful exit status, or +greater than 0 if the exit status indicated failure. +.SP +If \fBcvs\fR is successful, it returns a successful status; +if there is an error, it prints an error message and +returns a failure status. The one exception to this is +the \fBcvs diff\fR command. It will return a +successful status if it found no differences, or a +failure status if there were differences or if there +was an error. Because this behavior provides no good +way to detect errors, in the future it is possible that +\fBcvs diff\fR will be changed to behave like the +other \fBcvs\fR commands. +.SP +.SH "~/.cvsrc" +.SS "Default options and the ~/.cvsrc file" +.IX "\&.cvsrc file" +.IX "Option defaults" +.SP +There are some \fBcommand_options\fR 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 +\fB.cvsrc\fR support, actually) is that many people find the +default output of the \fBdiff\fR command to be very +hard to read, and that either context diffs or unidiffs +are much easier to understand. +.SP +The \fB~/.cvsrc\fR file is a way that you can add +default options to \fBcvs_commands\fR within cvs, +instead of relying on aliases or other shell scripts. +.SP +The format of the \fB~/.cvsrc\fR file is simple. The +file is searched for a line that begins with the same +name as the \fBcvs_command\fR 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 \fIbefore\fR any +options from the command line. +.SP +If a command has two names (e.g., \fBcheckout\fR and +\fBco\fR), 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\(aqs +\fB~/.cvsrc\fR file: +.SP +.PD 0 +.SP +.IP "" 2 +log -N +.IP "" 2 +diff -uN +.IP "" 2 +rdiff -u +.IP "" 2 +update -Pd +.IP "" 2 +checkout -P +.IP "" 2 +release -d + +.PD +.IP "" 0 +.SP +the command \fBcvs checkout foo\fR would have the +\fB-P\fR option added to the arguments, as well as +\fBcvs co foo\fR. +.SP +With the example file above, the output from \fBcvs +diff foobar\fR will be in unidiff format. \fBcvs diff +-c foobar\fR will provide context diffs, as usual. +Getting "old" format diffs would be slightly more +complicated, because \fBdiff\fR doesn\(aqt have an option +to specify use of the "old" format, so you would need +\fBcvs -f diff foobar\fR. +.SP +In place of the command name you can use \fBcvs\fR to +specify global options (see node `Global options\(aq in the CVS manual). For +example the following line in \fB.cvsrc\fR +.SP +.PD 0 +.SP +.IP "" 2 +cvs -z6 + +.PD +.IP "" 0 +.SP +causes \fBcvs\fR to use compression level 6. +.SP +.SH "Global options" +.IX "Options, global" +.IX "Global options" +.IX "Left-hand options" +.SP +The available \fBcvs_options\fR (that are given to the +left of \fBcvs_command\fR) are: +.SP +.IP "" 0 +\fB--allow-root=\fIrootdir\fB\fR +.IP "" 2 +Specify legal \fBcvsroot\fR directory. See +`Password authentication server\(aq in the CVS manual. +.SP +.IX "Authentication, stream" +.IX "Stream authentication" +.IP "" 0 +\fB-a\fR +.IP "" 2 +Authenticate all communication between the client and +the server. Only has an effect on the \fBcvs\fR client. +As of this writing, this is only implemented when using +a GSSAPI connection (see node `GSSAPI authenticated\(aq in the CVS manual). +Authentication prevents certain sorts of attacks +involving hijacking the active \fBtcp\fR connection. +Enabling authentication does not enable encryption. +.SP +.IX "RCSBIN, overriding" +.IX "Overriding RCSBIN" +.IP "" 0 +\fB-b \fIbindir\fB\fR +.IP "" 2 +In \fBcvs\fR 1.9.18 and older, this specified that +\fBrcs\fR programs are in the \fIbindir\fR directory. +Current versions of \fBcvs\fR do not run \fBrcs\fR +programs; for compatibility this option is accepted, +but it does nothing. +.SP +.IX "TMPDIR, overriding" +.IX "Overriding TMPDIR" +.IP "" 0 +\fB-T \fItempdir\fB\fR +.IP "" 2 +Use \fItempdir\fR as the directory where temporary files are +located. Overrides the setting of the \fB$TMPDIR\fR environment +variable and any precompiled directory. This parameter should be +specified as an absolute pathname. +(When running client/server, \fB-T\fR affects only the local process; +specifying \fB-T\fR for the client has no effect on the server and +vice versa.) +.SP +.IX "CVSROOT, overriding" +.IX "Overriding CVSROOT" +.IP "" 0 +\fB-d \fIcvs_root_directory\fB\fR +.IP "" 2 +Use \fIcvs_root_directory\fR as the root directory +pathname of the repository. Overrides the setting of +the \fB$CVSROOT\fR environment variable. See `Repository\(aq in the CVS manual. +.SP +.IX "EDITOR, overriding" +.IX "Overriding EDITOR" +.IP "" 0 +\fB-e \fIeditor\fB\fR +.IP "" 2 +Use \fIeditor\fR to enter revision log information. Overrides the +setting of the \fB$CVSEDITOR\fR and \fB$EDITOR\fR +environment variables. For more information, see +`Committing your changes\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-f\fR +.IP "" 2 +Do not read the \fB~/.cvsrc\fR file. This +option is most often used because of the +non-orthogonality of the \fBcvs\fR option set. For +example, the \fBcvs log\fR option \fB-N\fR (turn off +display of tag names) does not have a corresponding +option to turn the display on. So if you have +\fB-N\fR in the \fB~/.cvsrc\fR entry for \fBlog\fR, +you may need to use \fB-f\fR to show the tag names. +.SP +.IP "" 0 +\fB-H\fR +.IP "" 2 +.IP "" 0 +\fB--help\fR +.IP "" 2 +Display usage information about the specified \fBcvs_command\fR +(but do not actually execute the command). If you don\(aqt specify +a command name, \fBcvs -H\fR displays overall help for +\fBcvs\fR, including a list of other help options. +.SP +.IX "Read-only mode" +.IP "" 0 +\fB-n\fR +.IP "" 2 +Do not change any files. Attempt to execute the +\fBcvs_command\fR, but only to issue reports; do not remove, +update, or merge any existing files, or create any new files. +.SP +Note that \fBcvs\fR will not necessarily produce exactly +the same output as without \fB-n\fR. In some cases +the output will be the same, but in other cases +\fBcvs\fR will skip some of the processing that would +have been required to produce the exact same output. +.SP +.IP "" 0 +\fB-Q\fR +.IP "" 2 +Cause the command to be really quiet; the command will only +generate output for serious problems. +.SP +.IP "" 0 +\fB-q\fR +.IP "" 2 +Cause the command to be somewhat quiet; informational messages, +such as reports of recursion through subdirectories, are +suppressed. +.SP +.IX "Read-only files, and -r" +.IP "" 0 +\fB-r\fR +.IP "" 2 +Make new working files read-only. Same effect +as if the \fB$CVSREAD\fR environment variable is set +(see node `Environment variables\(aq in the CVS manual). The default is to +make working files writable, unless watches are on +(see node `Watches\(aq in the CVS manual). +.SP +.IP "" 0 +\fB-s \fIvariable\fB=\fIvalue\fB\fR +.IP "" 2 +Set a user variable (see node `Variables\(aq in the CVS manual). +.SP +.IX "Trace" +.IP "" 0 +\fB-t\fR +.IP "" 2 +Trace program execution; display messages showing the steps of +\fBcvs\fR activity. Particularly useful with \fB-n\fR to explore the +potential impact of an unfamiliar command. +.SP +.IP "" 0 +\fB-v\fR +.IP "" 2 +.IP "" 0 +\fB--version\fR +.IP "" 2 +Display version and copyright information for \fBcvs\fR. +.SP +.IX "CVSREAD, overriding" +.IX "Overriding CVSREAD" +.IP "" 0 +\fB-w\fR +.IP "" 2 +Make new working files read-write. Overrides the +setting of the \fB$CVSREAD\fR environment variable. +Files are created read-write by default, unless \fB$CVSREAD\fR is +set or \fB-r\fR is given. +.SP +.IP "" 0 +\fB-x\fR +.IP "" 2 +.IX "Encryption" +Encrypt all communication between the client and the +server. Only has an effect on the \fBcvs\fR client. As +of this writing, this is only implemented when using a +GSSAPI connection (see node `GSSAPI authenticated\(aq in the CVS manual) or a +Kerberos connection (see node `Kerberos authenticated\(aq in the CVS manual). +Enabling encryption implies that message traffic is +also authenticated. Encryption support is not +available by default; it must be enabled using a +special configure option, \fB--enable-encryption\fR, +when you build \fBcvs\fR. +.SP +.IP "" 0 +\fB-z \fIgzip-level\fB\fR +.IP "" 2 +.IX "Compression" +.IX "Gzip" +Set the compression level. +Valid levels are 1 (high speed, low compression) to +9 (low speed, high compression), or 0 to disable +compression (the default). +Only has an effect on the \fBcvs\fR client. +.SP +.SP +.SH "Common options" +.SS "Common command options" +.IX "Common options" +.IX "Right-hand options" +.SP +This section describes the \fBcommand_options\fR that +are available across several \fBcvs\fR commands. These +options are always given to the right of +\fBcvs_command\fR. 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 \fBcvs\fR command to the other). +.SP +\fBThe \fBhistory\fB command is an exception; it supports +many options that conflict even with these standard options.\fR +.SP +.IX "Dates" +.IX "Time" +.IX "Specifying dates" +.IP "" 0 +\fB-D \fIdate_spec\fB\fR +.IP "" 2 +Use the most recent revision no later than \fIdate_spec\fR. +\fIdate_spec\fR is a single argument, a date description +specifying a date in the past. +.SP +The specification is \fIsticky\fR when you use it to make a +private copy of a source file; that is, when you get a working +file using \fB-D\fR, \fBcvs\fR 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, see node `Sticky tags\(aq in the CVS manual). +.SP +\fB-D\fR is available with the \fBannotate\fR, \fBcheckout\fR, +\fBdiff\fR, \fBexport\fR, \fBhistory\fR, +\fBrdiff\fR, \fBrtag\fR, and \fBupdate\fR commands. +(The \fBhistory\fR command uses this option in a +slightly different way; see node `history options\(aq in the CVS manual). +.SP +.IX "Timezone, in input" +.IX "Zone, time, in input" +A wide variety of date formats are supported by +\fBcvs\fR. The most standard ones are ISO8601 (from the +International Standards Organization) and the Internet +e-mail standard (specified in RFC822 as amended by +RFC1123). +.SP +ISO8601 dates have many variants but a few examples +are: +.SP +.PD 0 +.SP +.IP "" 4 +1972-09-24 +.IP "" 4 +1972-09-24 20:05 + +.PD +.IP "" 2 +.SP +There are a lot more ISO8601 date formats, and \fBcvs\fR +accepts many of them, but you probably don\(aqt want to +hear the \fIwhole\fR long story :-). +.SP +In addition to the dates allowed in Internet e-mail +itself, \fBcvs\fR also allows some of the fields to be +omitted. For example: +.SP +.PD 0 +.SP +.IP "" 4 +24 Sep 1972 20:05 +.IP "" 4 +24 Sep + +.PD +.IP "" 2 +.SP +The date is interpreted as being in the +local timezone, unless a specific timezone is +specified. +.SP +These two date formats are preferred. However, +\fBcvs\fR currently accepts a wide variety of other date +formats. They are intentionally not documented here in +any detail, and future versions of \fBcvs\fR might not +accept all of them. +.SP +One such format is +\fB\fImonth\fB/\fIday\fB/\fIyear\fB\fR. This may +confuse people who are accustomed to having the month +and day in the other order; \fB1/4/96\fR is January 4, +not April 1. +.SP +Remember to quote the argument to the \fB-D\fR +flag so that your shell doesn\(aqt interpret spaces as +argument separators. A command using the \fB-D\fR +flag can look like this: +.SP +.PD 0 +.SP +.IP "" 4 +$ cvs diff -D "1 hour ago" cvs.texinfo + +.PD +.IP "" 2 +.SP +.IX "Forcing a tag match" +.IP "" 0 +\fB-f\fR +.IP "" 2 +When you specify a particular date or tag to \fBcvs\fR commands, they +normally ignore files that do not contain the tag (or did not +exist prior to the date) that you specified. Use the \fB-f\fR 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). +.SP +Note that even with \fB-f\fR, a tag that you specify +must exist (that is, in some file, not necessary in +every file). This is so that \fBcvs\fR will continue to +give an error if you mistype a tag name. +.SP +\fB-f\fR is available with these commands: +\fBannotate\fR, \fBcheckout\fR, \fBexport\fR, +\fBrdiff\fR, \fBrtag\fR, and \fBupdate\fR. +.SP +\fBWARNING: The \fBcommit\fB and \fBremove\fB +commands also have a +\fB-f\fB option, but it has a different behavior for +those commands. See `commit options\(aq in the CVS manual, and +`Removing files\(aq in the CVS manual.\fR +.SP +.IP "" 0 +\fB-k \fIkflag\fB\fR +.IP "" 2 +Alter the default processing of keywords. +See `Keyword substitution\(aq in the CVS manual, for the meaning of +\fIkflag\fR. Your \fIkflag\fR specification is +\fIsticky\fR when you use it to create a private copy +of a source file; that is, when you use this option +with the \fBcheckout\fR or \fBupdate\fR commands, +\fBcvs\fR associates your selected \fIkflag\fR with the +file, and continues to use it with future update +commands on the same file until you specify otherwise. +.SP +The \fB-k\fR option is available with the \fBadd\fR, +\fBcheckout\fR, \fBdiff\fR, \fBrdiff\fR, \fBimport\fR and +\fBupdate\fR commands. +.SP +.IP "" 0 +\fB-l\fR +.IP "" 2 +Local; run only in current working directory, rather than +recursing through subdirectories. +.SP +Available with the following commands: \fBannotate\fR, \fBcheckout\fR, +\fBcommit\fR, \fBdiff\fR, \fBedit\fR, \fBeditors\fR, \fBexport\fR, +\fBlog\fR, \fBrdiff\fR, \fBremove\fR, \fBrtag\fR, +\fBstatus\fR, \fBtag\fR, \fBunedit\fR, \fBupdate\fR, \fBwatch\fR, +and \fBwatchers\fR. +.SP +.IX "Editor, avoiding invocation of" +.IX "Avoiding editor invocation" +.IP "" 0 +\fB-m \fImessage\fB\fR +.IP "" 2 +Use \fImessage\fR as log information, instead of +invoking an editor. +.SP +Available with the following commands: \fBadd\fR, +\fBcommit\fR and \fBimport\fR. +.SP +.IP "" 0 +\fB-n\fR +.IP "" 2 +Do not run any tag program. (A program can be +specified to run in the modules +database (see node `modules\(aq in the CVS manual); this option bypasses it). +.SP +\fBThis is not the same as the \fBcvs -n\fB +program option, which you can specify to the left of a cvs command!\fR +.SP +Available with the \fBcheckout\fR, \fBexport\fR, +and \fBrtag\fR commands. +.SP +.IP "" 0 +\fB-P\fR +.IP "" 2 +Prune empty directories. See `Removing directories\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-p\fR +.IP "" 2 +Pipe the files retrieved from the repository to standard output, +rather than writing them in the current directory. Available +with the \fBcheckout\fR and \fBupdate\fR commands. +.SP +.IP "" 0 +\fB-R\fR +.IP "" 2 +Process directories recursively. This is on by default. +.SP +Available with the following commands: \fBannotate\fR, \fBcheckout\fR, +\fBcommit\fR, \fBdiff\fR, \fBedit\fR, \fBeditors\fR, \fBexport\fR, +\fBrdiff\fR, \fBremove\fR, \fBrtag\fR, +\fBstatus\fR, \fBtag\fR, \fBunedit\fR, \fBupdate\fR, \fBwatch\fR, +and \fBwatchers\fR. +.SP +.IP "" 0 +\fB-r \fItag\fB\fR +.IP "" 2 +.IX "HEAD, special tag" +.IX "BASE, special tag" +Use the revision specified by the \fItag\fR argument instead of the +default \fIhead\fR revision. As well as arbitrary tags defined +with the \fBtag\fR or \fBrtag\fR command, two special tags are +always available: \fBHEAD\fR refers to the most recent version +available in the repository, and \fBBASE\fR refers to the +revision you last checked out into the current working directory. +.SP +The tag specification is sticky when you use this +with \fBcheckout\fR or \fBupdate\fR to make your own +copy of a file: \fBcvs\fR remembers the tag and continues to use it on +future update commands, until you specify otherwise (for more information +on sticky tags/dates, see node `Sticky tags\(aq in the CVS manual). +.SP +The tag can be either a symbolic or numeric tag, as +described in `Tags\(aq in the CVS manual, or the name of a branch, as +described in `Branching and merging\(aq in the CVS manual. +When a command expects a specific revision, +the name of a branch is interpreted as the most recent +revision on that branch. +.SP +Specifying the \fB-q\fR global option along with the +\fB-r\fR command option is often useful, to suppress +the warning messages when the \fBrcs\fR file +does not contain the specified tag. +.SP +\fBThis is not the same as the overall \fBcvs -r\fB option, +which you can specify to the left of a \fBcvs\fB command!\fR +.SP +\fB-r\fR is available with the \fBannotate\fR, \fBcheckout\fR, +\fBcommit\fR, \fBdiff\fR, \fBhistory\fR, \fBexport\fR, \fBrdiff\fR, +\fBrtag\fR, and \fBupdate\fR commands. +.SP +.IP "" 0 +\fB-W\fR +.IP "" 2 +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 \fB.cvswrappers\fR file. +Available with the following commands: \fBimport\fR, +and \fBupdate\fR. +.SP +.SP +.SH "add" +.SS "Add files and directories to the repository" +.IX "add (subcommand)" +.SP +.IP "\(bu" 2 +Synopsis: add [-k rcs-kflag] [-m message] files... +.IP "\(bu" 2 +Requires: repository, working directory. +.IP "\(bu" 2 +Changes: repository, working directory. +.SP +The \fBadd\fR command is used to present new files +and directories for addition into the \fBcvs\fR +repository. When \fBadd\fR is used on a directory, +a new directory is created in the repository +immediately. When used on a file, only the working +directory is updated. Changes to the repository are +not made until the \fBcommit\fR command is used on +the newly added file. +.SP +The \fBadd\fR command also resurrects files that +have been previously removed. This can be done +before or after the \fBcommit\fR command is used +to finalize the removal of files. Resurrected files +are restored into the working directory at the time +the \fBadd\fR command is executed. +.SP +.SH "add options" +.SP +These standard options are supported by \fBadd\fR +(see node `Common options\(aq in the CVS manual, for a complete description of +them): +.SP +.IP "" 0 +\fB-k \fIkflag\fB\fR +.IP "" 2 +Process keywords according to \fIkflag\fR. See +`Keyword substitution\(aq in the CVS manual. +This option is sticky; future updates of +this file in this working directory will use the same +\fIkflag\fR. The \fBstatus\fR command can be viewed +to see the sticky options. For more information on +the \fBstatus\fR command, see node `Invoking CVS\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-m \fImessage\fB\fR +.IP "" 2 +Use \fImessage\fR as the log message, instead of +invoking an editor. +.SP +.SH "add examples" +.SP +.SS "Adding a directory" +.SP +.PD 0 +.SP +.IP "" 2 +$ mkdir doc +.IP "" 2 +$ cvs add doc +.IP "" 2 +Directory /path/to/repository/doc added to the repository + +.PD +.IP "" 0 +.SP +.SS "Adding a file" +.SP +.PD 0 +.SP +.SP +.IP "" 2 +$ >TODO +.IP "" 2 +$ cvs add TODO +.IP "" 2 +cvs add: scheduling file \`TODO\(aq for addition +.IP "" 2 +cvs add: use \(aqcvs commit\(aq to add this file permanently + +.PD +.IP "" 0 +.SP +.SS "Undoing a \fBremove\fR command" +.SP +.PD 0 +.SP +.IP "" 2 +$ rm -f makefile +.IP "" 2 +$ cvs remove makefile +.IP "" 2 +cvs remove: scheduling \`makefile\(aq for removal +.IP "" 2 +cvs remove: use \(aqcvs commit\(aq to remove this file permanently +.IP "" 2 +$ cvs add makefile +.IP "" 2 +U makefile +.IP "" 2 +cvs add: makefile, version 1.2, resurrected + +.PD +.IP "" 0 +.SP +.SH "admin" +.SS "Administration" +.IX "Admin (subcommand)" +.SP +.IP "\(bu" 2 +Requires: repository, working directory. +.IP "\(bu" 2 +Changes: repository. +.IP "\(bu" 2 +Synonym: rcs +.SP +This is the \fBcvs\fR interface to assorted +administrative facilities. Some of them have +questionable usefulness for \fBcvs\fR but exist for +historical purposes. Some of the questionable options +are likely to disappear in the future. This command +\fIdoes\fR work recursively, so extreme care should be +used. +.SP +.IX "cvsadmin" +On unix, if there is a group named \fBcvsadmin\fR, +only members of that group can run \fBcvs admin\fR +(except for the \fBcvs admin -k\fR command, which can +be run by anybody). This group should exist on the +server, or any system running the non-client/server +\fBcvs\fR. To disallow \fBcvs admin\fR for all users, +create a group with no users in it. On NT, the +\fBcvsadmin\fR feature does not exist and all users +can run \fBcvs admin\fR. +.SP +.SH "admin options" +.SP +Some of these options have questionable usefulness for +\fBcvs\fR but exist for historical purposes. Some even +make it impossible to use \fBcvs\fR until you undo the +effect! +.SP +.IP "" 0 +\fB-A\fIoldfile\fB\fR +.IP "" 2 +Might not work together with \fBcvs\fR. Append the +access list of \fIoldfile\fR to the access list of the +\fBrcs\fR file. +.SP +.IP "" 0 +\fB-a\fIlogins\fB\fR +.IP "" 2 +Might not work together with \fBcvs\fR. Append the +login names appearing in the comma-separated list +\fIlogins\fR to the access list of the \fBrcs\fR file. +.SP +.IP "" 0 +\fB-b[\fIrev\fB]\fR +.IP "" 2 +Set the default branch to \fIrev\fR. In \fBcvs\fR, you +normally do not manipulate default branches; sticky +tags (see node `Sticky tags\(aq in the CVS manual) are a better way to decide +which branch you want to work on. There is one reason +to run \fBcvs admin -b\fR: to revert to the vendor\(aqs +version when using vendor branches (see node `Reverting +local changes\(aq in the CVS manual). +There can be no space between \fB-b\fR and its argument. +.SP +.IX "Comment leader" +.IP "" 0 +\fB-c\fIstring\fB\fR +.IP "" 2 +Sets the comment leader to \fIstring\fR. The comment +leader is not used by current versions of \fBcvs\fR or +\fBrcs\fR 5.7. Therefore, you can almost surely not +worry about it. See `Keyword substitution\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-e[\fIlogins\fB]\fR +.IP "" 2 +Might not work together with \fBcvs\fR. Erase the login +names appearing in the comma-separated list +\fIlogins\fR from the access list of the RCS file. If +\fIlogins\fR is omitted, erase the entire access list. +There can be no space between \fB-e\fR and its argument. +.SP +.IP "" 0 +\fB-I\fR +.IP "" 2 +Run interactively, even if the standard input is not a +terminal. This option does not work with the +client/server \fBcvs\fR and is likely to disappear in +a future release of \fBcvs\fR. +.SP +.IP "" 0 +\fB-i\fR +.IP "" 2 +Useless with \fBcvs\fR. This creates and initializes a +new \fBrcs\fR file, without depositing a revision. With +\fBcvs\fR, add files with the \fBcvs add\fR command +(see node `Adding files\(aq in the CVS manual). +.SP +.IP "" 0 +\fB-k\fIsubst\fB\fR +.IP "" 2 +Set the default keyword +substitution to \fIsubst\fR. See `Keyword +substitution\(aq in the CVS manual. Giving an explicit \fB-k\fR option to +\fBcvs update\fR, \fBcvs export\fR, or \fBcvs +checkout\fR overrides this default. +.SP +.IP "" 0 +\fB-l[\fIrev\fB]\fR +.IP "" 2 +Lock the revision with number \fIrev\fR. If a branch +is given, lock the latest revision on that branch. If +\fIrev\fR is omitted, lock the latest revision on the +default branch. There can be no space between +\fB-l\fR and its argument. +.SP +This can be used in conjunction with the +\fBrcslock.pl\fR script in the \fBcontrib\fR +directory of the \fBcvs\fR 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 \fBREADME\fR 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). +.SP +.IP "" 0 +\fB-L\fR +.IP "" 2 +Set locking to strict. Strict locking means that the +owner of an RCS file is not exempt from locking for +checkin. For use with \fBcvs\fR, strict locking must be +set; see the discussion under the \fB-l\fR option above. +.SP +.IX "Changing a log message" +.IX "Replacing a log message" +.IX "Correcting a log message" +.IX "Fixing a log message" +.IX "Log message, correcting" +.IP "" 0 +\fB-m\fIrev\fB:\fImsg\fB\fR +.IP "" 2 +Replace the log message of revision \fIrev\fR with +\fImsg\fR. +.SP +.IP "" 0 +\fB-N\fIname\fB[:[\fIrev\fB]]\fR +.IP "" 2 +Act like \fB-n\fR, except override any previous +assignment of \fIname\fR. For use with magic branches, +see `Magic branch numbers\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-n\fIname\fB[:[\fIrev\fB]]\fR +.IP "" 2 +Associate the symbolic name \fIname\fR with the branch +or revision \fIrev\fR. It is normally better to use +\fBcvs tag\fR or \fBcvs rtag\fR instead. Delete the +symbolic name if both \fB:\fR and \fIrev\fR are +omitted; otherwise, print an error message if +\fIname\fR is already associated with another number. +If \fIrev\fR is symbolic, it is expanded before +association. A \fIrev\fR consisting of a branch number +followed by a \fB.\fR stands for the current latest +revision in the branch. A \fB:\fR with an empty +\fIrev\fR stands for the current latest revision on the +default branch, normally the trunk. For example, +\fBcvs admin -n\fIname\fB:\fR associates \fIname\fR with the +current latest revision of all the RCS files; +this contrasts with \fBcvs admin -n\fIname\fB:$\fR which +associates \fIname\fR with the revision numbers +extracted from keyword strings in the corresponding +working files. +.SP +.IX "Deleting revisions" +.IX "Outdating revisions" +.IX "Saving space" +.IP "" 0 +\fB-o\fIrange\fB\fR +.IP "" 2 +Deletes (\fIoutdates\fR) the revisions given by +\fIrange\fR. +.SP +Note that this command can be quite dangerous unless +you know \fIexactly\fR what you are doing (for example +see the warnings below about how the +\fIrev1\fR:\fIrev2\fR syntax is confusing). +.SP +If you are short on disc this option might help you. +But think twice before using it\(emthere is no way short +of restoring the latest backup to undo this command! +If you delete different revisions than you planned, +either due to carelessness or (heaven forbid) a \fBcvs\fR +bug, there is no opportunity to correct the error +before the revisions are deleted. It probably would be +a good idea to experiment on a copy of the repository +first. +.SP +Specify \fIrange\fR in one of the following ways: +.SP +.IP "" 2 +\fB\fIrev1\fB::\fIrev2\fB\fR +.IP "" 4 +Collapse all revisions between rev1 and rev2, so that +\fBcvs\fR only stores the differences associated with going +from rev1 to rev2, not intermediate steps. For +example, after \fB-o 1.3::1.5\fR one can retrieve +revision 1.3, revision 1.5, or the differences to get +from 1.3 to 1.5, but not the revision 1.4, or the +differences between 1.3 and 1.4. Other examples: +\fB-o 1.3::1.4\fR and \fB-o 1.3::1.3\fR have no +effect, because there are no intermediate revisions to +remove. +.SP +.IP "" 2 +\fB::\fIrev\fB\fR +.IP "" 4 +Collapse revisions between the beginning of the branch +containing \fIrev\fR and \fIrev\fR itself. The +branchpoint and \fIrev\fR are left intact. For +example, \fB-o ::1.3.2.6\fR deletes revision 1.3.2.1, +revision 1.3.2.5, and everything in between, but leaves +1.3 and 1.3.2.6 intact. +.SP +.IP "" 2 +\fB\fIrev\fB::\fR +.IP "" 4 +Collapse revisions between \fIrev\fR and the end of the +branch containing \fIrev\fR. Revision \fIrev\fR is +left intact but the head revision is deleted. +.SP +.IP "" 2 +\fB\fIrev\fB\fR +.IP "" 4 +Delete the revision \fIrev\fR. For example, \fB-o +1.3\fR is equivalent to \fB-o 1.2::1.4\fR. +.SP +.IP "" 2 +\fB\fIrev1\fB:\fIrev2\fB\fR +.IP "" 4 +Delete the revisions from \fIrev1\fR to \fIrev2\fR, +inclusive, on the same branch. One will not be able to +retrieve \fIrev1\fR or \fIrev2\fR or any of the +revisions in between. For example, the command +\fBcvs admin -oR_1_01:R_1_02 \&.\fR is rarely useful. +It means to delete revisions up to, and including, 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 +\fIthe same\fR 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! In most cases you want to +specify \fIrev1\fR::\fIrev2\fR instead. +.SP +.IP "" 2 +\fB:\fIrev\fB\fR +.IP "" 4 +Delete revisions from the beginning of the +branch containing \fIrev\fR up to and including +\fIrev\fR. +.SP +.IP "" 2 +\fB\fIrev\fB:\fR +.IP "" 4 +Delete revisions from revision \fIrev\fR, including +\fIrev\fR itself, to the end of the branch containing +\fIrev\fR. +.SP +None of the revisions to be deleted may have +branches or locks. +.SP +If any of the revisions to be deleted have symbolic +names, and one specifies one of the \fB::\fR syntaxes, +then \fBcvs\fR will give an error and not delete any +revisions. If you really want to delete both the +symbolic names and the revisions, first delete the +symbolic names with \fBcvs tag -d\fR, then run +\fBcvs admin -o\fR. If one specifies the +non-\fB::\fR syntaxes, then \fBcvs\fR will delete the +revisions but leave the symbolic names pointing to +nonexistent revisions. This behavior is preserved for +compatibility with previous versions of \fBcvs\fR, but +because it isn\(aqt very useful, in the future it may +change to be like the \fB::\fR case. +.SP +Due to the way \fBcvs\fR handles branches \fIrev\fR +cannot be specified symbolically if it is a branch. +See `Magic branch numbers\(aq in the CVS manual for an explanation. +.SP +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 (see node `Merging two revisions\(aq in the CVS manual). +.SP +.IP "" 0 +\fB-q\fR +.IP "" 2 +Run quietly; do not print diagnostics. +.SP +.IP "" 0 +\fB-s\fIstate\fB[:\fIrev\fB]\fR +.IP "" 2 +Useful with \fBcvs\fR. Set the state attribute of the +revision \fIrev\fR to \fIstate\fR. If \fIrev\fR is a +branch number, assume the latest revision on that +branch. If \fIrev\fR is omitted, assume the latest +revision on the default branch. Any identifier is +acceptable for \fIstate\fR. A useful set of states is +\fBExp\fR (for experimental), \fBStab\fR (for +stable), and \fBRel\fR (for released). By default, +the state of a new revision is set to \fBExp\fR when +it is created. The state is visible in the output from +\fIcvs log\fR (see node `log\(aq in the CVS manual), and in the +\fB$\fP\fPLog$\fR and \fB$\fP\fPState$\fR keywords +(see node `Keyword substitution\(aq in the CVS manual). Note that \fBcvs\fR +uses the \fBdead\fR state for its own purposes (see node `Attic\(aq in the CVS manual); to +take a file to or from the \fBdead\fR state use +commands like \fBcvs remove\fR and \fBcvs add\fR +(see node `Adding and removing\(aq in the CVS manual), not \fBcvs admin -s\fR. +.SP +.IP "" 0 +\fB-t[\fIfile\fB]\fR +.IP "" 2 +Useful with \fBcvs\fR. Write descriptive text from the +contents of the named \fIfile\fR into the RCS file, +deleting the existing text. The \fIfile\fR pathname +may not begin with \fB-\fR. The descriptive text can be seen in the +output from \fBcvs log\fR (see node `log\(aq in the CVS manual). +There can be no space between \fB-t\fR and its argument. +.SP +If \fIfile\fR is omitted, +obtain the text from standard input, terminated by +end-of-file or by a line containing \fB.\fR by itself. +Prompt for the text if interaction is possible; see +\fB-I\fR. +.SP +.IP "" 0 +\fB-t-\fIstring\fB\fR +.IP "" 2 +Similar to \fB-t\fIfile\fB\fR. Write descriptive text +from the \fIstring\fR into the \fBrcs\fR file, deleting +the existing text. +There can be no space between \fB-t\fR and its argument. +.SP +.IP "" 0 +\fB-U\fR +.IP "" 2 +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 \fBcvs\fR, strict locking must be +set; see the discussion under the \fB-l\fR option +above. +.SP +.IP "" 0 +\fB-u[\fIrev\fB]\fR +.IP "" 2 +See the option \fB-l\fR above, for a discussion of +using this option with \fBcvs\fR. Unlock the revision +with number \fIrev\fR. If a branch is given, unlock +the latest revision on that branch. If \fIrev\fR 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 the original locker to be sent a \fBcommit\fR +notification (see node `Getting Notified\(aq in the CVS manual). +There can be no space between \fB-u\fR and its argument. +.SP +.IP "" 0 +\fB-V\fIn\fB\fR +.IP "" 2 +In previous versions of \fBcvs\fR, this option meant to +write an \fBrcs\fR file which would be acceptable to +\fBrcs\fR version \fIn\fR, but it is now obsolete and +specifying it will produce an error. +.SP +.IP "" 0 +\fB-x\fIsuffixes\fB\fR +.IP "" 2 +In previous versions of \fBcvs\fR, this was documented +as a way of specifying the names of the \fBrcs\fR +files. However, \fBcvs\fR has always required that the +\fBrcs\fR files used by \fBcvs\fR end in \fB,v\fR, so +this option has never done anything useful. +.SP +.SP +.SH "annotate" +.SS "What revision modified each line of a file?" +.IX "annotate (subcommand)" +.SP +.IP "\(bu" 2 +Synopsis: annotate [options] files\&... +.IP "\(bu" 2 +Requires: repository. +.IP "\(bu" 2 +Synonym: blame +.IP "\(bu" 2 +Changes: nothing. +.SP +For each file in \fIfiles\fR, print the head revision +of the trunk, together with information on the last +modification for each line. +.SP +.SH "annotate options" +.SP +These standard options are supported by \fBannotate\fR +(see node `Common options\(aq in the CVS manual for a complete description of +them): +.SP +.IP "" 0 +\fB-l\fR +.IP "" 2 +Local directory only, no recursion. +.SP +.IP "" 0 +\fB-R\fR +.IP "" 2 +Process directories recursively. +.SP +.IP "" 0 +\fB-f\fR +.IP "" 2 +Use head revision if tag/date not found. +.SP +.IP "" 0 +\fB-F\fR +.IP "" 2 +Annotate binary files. +.SP +.IP "" 0 +\fB-r \fIrevision\fB\fR +.IP "" 2 +Annotate file as of specified revision/tag. +.SP +.IP "" 0 +\fB-D \fIdate\fB\fR +.IP "" 2 +Annotate file as of specified date. +.SP +.SH "annotate example" +.SP +For example: +.SP +.PD 0 +.SP +.IP "" 2 +$ cvs annotate ssfile +.IP "" 2 +Annotations for ssfile +.IP "" 2 +*************** +.IP "" 2 +1.1 (mary 27-Mar-96): ssfile line 1 +.IP "" 2 +1.2 (joe 28-Mar-96): ssfile line 2 + +.PD +.IP "" 0 +.SP +The file \fBssfile\fR currently contains two lines. +The \fBssfile line 1\fR line was checked in by +\fBmary\fR on March 27. Then, on March 28, \fBjoe\fR +added a line \fBssfile line 2\fR, without modifying +the \fBssfile line 1\fR line. This report doesn\(aqt +tell you anything about lines which have been deleted +or replaced; you need to use \fBcvs diff\fR for that +(see node `diff\(aq in the CVS manual). +.SP +The options to \fBcvs annotate\fR are listed in +`Invoking CVS\(aq in the CVS manual, and can be used to select the files +and revisions to annotate. The options are described +in more detail there and in `Common options\(aq in the CVS manual. +.SP +.SH "checkout" +.SS "Check out sources for editing" +.IX "checkout (subcommand)" +.IX "co (subcommand)" +.SP +.IP "\(bu" 2 +Synopsis: checkout [options] modules\&... +.IP "\(bu" 2 +Requires: repository. +.IP "\(bu" 2 +Changes: working directory. +.IP "\(bu" 2 +Synonyms: co, get +.SP +Create or update a working directory containing copies of the +source files specified by \fImodules\fR. You must execute +\fBcheckout\fR before using most of the other \fBcvs\fR +commands, since most of them operate on your working +directory. +.SP +The \fImodules\fR 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 \fBmodules\fR file. +See `modules\(aq in the CVS manual. +.SP +Depending on the modules you specify, \fBcheckout\fR 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. +.SP +Note that \fBcheckout\fR is used to create +directories. The top-level directory created is always +added to the directory where \fBcheckout\fR 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 +\fBcheckout\fR will show the relative path leading to +each file as it is extracted into your private work +area (unless you specify the \fB-Q\fR global option). +.SP +The files created by \fBcheckout\fR are created +read-write, unless the \fB-r\fR option to \fBcvs\fR +(see node `Global options\(aq in the CVS manual) is specified, the +\fBCVSREAD\fR environment variable is specified +(see node `Environment variables\(aq in the CVS manual), or a watch is in +effect for that file (see node `Watches\(aq in the CVS manual). +.SP +Note that running \fBcheckout\fR on a directory that was already +built by a prior \fBcheckout\fR is also permitted. +This is similar to specifying the \fB-d\fR option +to the \fBupdate\fR command in the sense that new +directories that have been created in the repository +will appear in your work area. +However, \fBcheckout\fR takes a module name whereas +\fBupdate\fR takes a directory name. Also +to use \fBcheckout\fR this way it must be run from the +top level directory (where you originally ran +\fBcheckout\fR from), so before you run +\fBcheckout\fR to update an existing directory, don\(aqt +forget to change your directory to the top level +directory. +.SP +For the output produced by the \fBcheckout\fR command, +see node `update output\(aq in the CVS manual. +.SP +.SH "checkout options" +.SP +These standard options are supported by \fBcheckout\fR +(see node `Common options\(aq in the CVS manual for a complete description of +them): +.SP +.IP "" 0 +\fB-D \fIdate\fB\fR +.IP "" 2 +Use the most recent revision no later than \fIdate\fR. +This option is sticky, and implies \fB-P\fR. See +`Sticky tags\(aq in the CVS manual for more information on sticky tags/dates. +.SP +.IP "" 0 +\fB-f\fR +.IP "" 2 +Only useful with the \fB-D \fIdate\fB\fR or \fB-r +\fItag\fB\fR flags. If no matching revision is found, +retrieve the most recent revision (instead of ignoring +the file). +.SP +.IP "" 0 +\fB-k \fIkflag\fB\fR +.IP "" 2 +Process keywords according to \fIkflag\fR. See +`Keyword substitution\(aq in the CVS manual. +This option is sticky; future updates of +this file in this working directory will use the same +\fIkflag\fR. The \fBstatus\fR command can be viewed +to see the sticky options. See `Invoking CVS\(aq in the CVS manual for +more information on the \fBstatus\fR command. +.SP +.IP "" 0 +\fB-l\fR +.IP "" 2 +Local; run only in current working directory. +.SP +.IP "" 0 +\fB-n\fR +.IP "" 2 +Do not run any checkout program (as specified +with the \fB-o\fR option in the modules file; +see node `modules\(aq in the CVS manual). +.SP +.IP "" 0 +\fB-P\fR +.IP "" 2 +Prune empty directories. See `Moving directories\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-p\fR +.IP "" 2 +Pipe files to the standard output. +.SP +.IP "" 0 +\fB-R\fR +.IP "" 2 +Checkout directories recursively. This option is on by default. +.SP +.IP "" 0 +\fB-r \fItag\fB\fR +.IP "" 2 +Use revision \fItag\fR. This option is sticky, and implies \fB-P\fR. +See `Sticky tags\(aq in the CVS manual, for more information on sticky tags/dates. +.SP +In addition to those, you can use these special command +options with \fBcheckout\fR: +.SP +.IP "" 0 +\fB-A\fR +.IP "" 2 +Reset any sticky tags, dates, or \fB-k\fR options. +Does not reset sticky \fB-k\fR options on modified files. +See `Sticky tags\(aq in the CVS manual for more information on sticky tags/dates. +.SP +.IP "" 0 +\fB-c\fR +.IP "" 2 +Copy the module file, sorted, to the standard output, +instead of creating or modifying any files or +directories in your working directory. +.SP +.IP "" 0 +\fB-d \fIdir\fB\fR +.IP "" 2 +Create a directory called \fIdir\fR for the working +files, instead of using the module name. In general, +using this flag is equivalent to using \fBmkdir +\fIdir\fB; cd \fIdir\fB\fR followed by the checkout +command without the \fB-d\fR flag. +.SP +There is an important exception, however. It is very +convenient when checking out a single item to have the +output appear in a directory that doesn\(aqt contain empty +intermediate directories. In this case \fIonly\fR, +\fBcvs\fR tries to \`\`shorten\(aq\(aq pathnames to avoid those empty +directories. +.SP +For example, given a module \fBfoo\fR that contains +the file \fBbar.c\fR, the command \fBcvs co -d dir +foo\fR will create directory \fBdir\fR and place +\fBbar.c\fR inside. Similarly, given a module +\fBbar\fR which has subdirectory \fBbaz\fR wherein +there is a file \fBquux.c\fR, the command \fBcvs co +-d dir bar/baz\fR will create directory \fBdir\fR and +place \fBquux.c\fR inside. +.SP +Using the \fB-N\fR flag will defeat this behavior. +Given the same module definitions above, \fBcvs co +-N -d dir foo\fR will create directories \fBdir/foo\fR +and place \fBbar.c\fR inside, while \fBcvs co -N -d +dir bar/baz\fR will create directories \fBdir/bar/baz\fR +and place \fBquux.c\fR inside. +.SP +.IP "" 0 +\fB-j \fItag\fB\fR +.IP "" 2 +With two \fB-j\fR options, merge changes from the +revision specified with the first \fB-j\fR option to +the revision specified with the second \fBj\fR option, +into the working directory. +.SP +With one \fB-j\fR option, merge changes from the +ancestor revision to the revision specified with the +\fB-j\fR 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 \fB-j\fR option. +.SP +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: +\fB-j\fISymbolic_Tag\fB:\fIDate_Specifier\fB\fR. +.SP +See `Branching and merging\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-N\fR +.IP "" 2 +Only useful together with \fB-d \fIdir\fB\fR. With +this option, \fBcvs\fR will not \`\`shorten\(aq\(aq module paths +in your working directory when you check out a single +module. See the \fB-d\fR flag for examples and a +discussion. +.SP +.IP "" 0 +\fB-s\fR +.IP "" 2 +Like \fB-c\fR, but include the status of all modules, +and sort it by the status string. See `modules\(aq in the CVS manual, for +info about the \fB-s\fR option that is used inside the +modules file to set the module status. +.SP +.SH "checkout examples" +.SP +Get a copy of the module \fBtc\fR: +.SP +.PD 0 +.SP +.IP "" 2 +$ cvs checkout tc + +.PD +.IP "" 0 +.SP +Get a copy of the module \fBtc\fR as it looked one day +ago: +.SP +.PD 0 +.SP +.IP "" 2 +$ cvs checkout -D yesterday tc + +.PD +.IP "" 0 +.SP +.SH "commit" +.SS "Check files into the repository" +.IX "commit (subcommand)" +.SP +.IP "\(bu" 2 +Synopsis: commit [-lRf] [-m \(aqlog_message\(aq | +-F file] [-r revision] [files\&...] +.IP "\(bu" 2 +Requires: working directory, repository. +.IP "\(bu" 2 +Changes: repository. +.IP "\(bu" 2 +Synonym: ci +.SP +Use \fBcommit\fR when you want to incorporate changes +from your working source files into the source +repository. +.SP +If you don\(aqt specify particular files to commit, all of +the files in your working current directory are +examined. \fBcommit\fR is careful to change in the +repository only those files that you have really +changed. By default (or if you explicitly specify the +\fB-R\fR option), files in subdirectories are also +examined and committed if they have changed; you can +use the \fB-l\fR option to limit \fBcommit\fR to the +current directory only. +.SP +\fBcommit\fR 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 \fBupdate\fR (see node `update\(aq in the CVS manual). +\fBcommit\fR does not call the \fBupdate\fR command +for you, but rather leaves that for you to do when the +time is right. +.SP +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 (see node `modules\(aq in the CVS manual, and see node `loginfo\(aq in the CVS manual) +and placed in the \fBrcs\fR file inside the +repository. This log message can be retrieved with the +\fBlog\fR command; see node `log\(aq in the CVS manual. You can specify the +log message on the command line with the \fB-m +\fImessage\fB\fR option, and thus avoid the editor invocation, +or use the \fB-F \fIfile\fB\fR option to specify +that the argument file contains the log message. +.SP +.SH "commit options" +.SP +These standard options are supported by \fBcommit\fR +(see node `Common options\(aq in the CVS manual for a complete description of +them): +.SP +.IP "" 0 +\fB-l\fR +.IP "" 2 +Local; run only in current working directory. +.SP +.IP "" 0 +\fB-R\fR +.IP "" 2 +Commit directories recursively. This is on by default. +.SP +.IP "" 0 +\fB-r \fIrevision\fB\fR +.IP "" 2 +Commit to \fIrevision\fR. \fIrevision\fR must be +either a branch, or a revision on the main trunk that +is higher than any existing revision number +(see node `Assigning revisions\(aq in the CVS manual). You +cannot commit to a specific revision on a branch. +.SP +\fBcommit\fR also supports these options: +.SP +.IP "" 0 +\fB-F \fIfile\fB\fR +.IP "" 2 +Read the log message from \fIfile\fR, instead +of invoking an editor. +.SP +.IP "" 0 +\fB-f\fR +.IP "" 2 +Note that this is not the standard behavior of +the \fB-f\fR option as defined in `Common options\(aq in the CVS manual. +.SP +Force \fBcvs\fR to commit a new revision even if you haven\(aqt +made any changes to the file. If the current revision +of \fIfile\fR is 1.7, then the following two commands +are equivalent: +.SP +.PD 0 +.SP +.IP "" 4 +$ cvs commit -f \fIfile\fR +.IP "" 4 +$ cvs commit -r 1.8 \fIfile\fR + +.PD +.IP "" 2 +.SP +The \fB-f\fR option disables recursion (i.e., it +implies \fB-l\fR). To force \fBcvs\fR to commit a new +revision for all files in all subdirectories, you must +use \fB-f -R\fR. +.SP +.IP "" 0 +\fB-m \fImessage\fB\fR +.IP "" 2 +Use \fImessage\fR as the log message, instead of +invoking an editor. +.SP +.SH "commit examples" +.SP +.SS "Committing to a branch" +.SP +You can commit to a branch revision (one that has an +even number of dots) with the \fB-r\fR option. To +create a branch revision, use the \fB-b\fR option +of the \fBrtag\fR or \fBtag\fR commands +(see node `Branching and merging\(aq in the CVS manual). Then, either \fBcheckout\fR or +\fBupdate\fR can be used to base your sources on the +newly created branch. From that point on, all +\fBcommit\fR 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: +.SP +.PD 0 +.SP +.IP "" 2 +$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module +.IP "" 2 +$ cvs checkout -r FCS1_2_Patch product_module +.IP "" 2 +$ cd product_module +.IP "" 2 +[[ hack away ]] +.IP "" 2 +$ cvs commit + +.PD +.IP "" 0 +.SP +This works automatically since the \fB-r\fR option is +sticky. +.SP +.SS "Creating the branch after editing" +.SP +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 \fBcvs\fR conflict resolution. The scenario might +look like: +.SP +.PD 0 +.SP +.IP "" 2 +[[ hacked sources are present ]] +.IP "" 2 +$ cvs tag -b EXPR1 +.IP "" 2 +$ cvs update -r EXPR1 +.IP "" 2 +$ cvs commit + +.PD +.IP "" 0 +.SP +The \fBupdate\fR command will make the \fB-r +EXPR1\fR option sticky on all files. Note that your +changes to the files will never be removed by the +\fBupdate\fR command. The \fBcommit\fR will +automatically commit to the correct branch, because the +\fB-r\fR is sticky. You could also do like this: +.SP +.PD 0 +.SP +.IP "" 2 +[[ hacked sources are present ]] +.IP "" 2 +$ cvs tag -b EXPR1 +.IP "" 2 +$ cvs commit -r EXPR1 + +.PD +.IP "" 0 +.SP +but then, only those files that were changed by you +will have the \fB-r EXPR1\fR sticky flag. If you hack +away, and commit without specifying the \fB-r EXPR1\fR +flag, some files may accidentally end up on the main +trunk. +.SP +To work with you on the experimental change, others +would simply do +.SP +.PD 0 +.SP +.IP "" 2 +$ cvs checkout -r EXPR1 whatever_module + +.PD +.IP "" 0 +.SP +.SH "diff" +.SS "Show differences between revisions" +.IX "diff (subcommand)" +.SP +.IP "\(bu" 2 +Synopsis: diff [-lR] [-k kflag] [format_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files\&...] +.IP "\(bu" 2 +Requires: working directory, repository. +.IP "\(bu" 2 +Changes: nothing. +.SP +The \fBdiff\fR 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. +.SP +If any file names are given, only those files are +compared. If any directories are given, all files +under them will be compared. +.SP +The exit status for diff is different than for other +\fBcvs\fR commands; for details see node `Exit status\(aq in the CVS manual. +.SP +.SH "diff options" +.SP +These standard options are supported by \fBdiff\fR +(see node `Common options\(aq in the CVS manual for a complete description of +them): +.SP +.IP "" 0 +\fB-D \fIdate\fB\fR +.IP "" 2 +Use the most recent revision no later than \fIdate\fR. +See \fB-r\fR for how this affects the comparison. +.SP +.IP "" 0 +\fB-k \fIkflag\fB\fR +.IP "" 2 +Process keywords according to \fIkflag\fR. See +`Keyword substitution\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-l\fR +.IP "" 2 +Local; run only in current working directory. +.SP +.IP "" 0 +\fB-R\fR +.IP "" 2 +Examine directories recursively. This option is on by +default. +.SP +.IP "" 0 +\fB-r \fItag\fB\fR +.IP "" 2 +Compare with revision \fItag\fR. Zero, one or two +\fB-r\fR options can be present. With no \fB-r\fR +option, the working file will be compared with the +revision it was based on. With one \fB-r\fR, that +revision will be compared to your current working file. +With two \fB-r\fR options those two revisions will be +compared (and your working file will not affect the +outcome in any way). +.SP +One or both \fB-r\fR options can be replaced by a +\fB-D \fIdate\fB\fR option, described above. +.SP +The following options specify the format of the +output. They have the same meaning as in GNU diff. +Most options have two equivalent names, one of which is a single letter +preceded by \fB-\fR, and the other of which is a long name preceded by +\fB--\fR. +.SP +.IP "" 0 +\fB-\fIlines\fB\fR +.IP "" 2 +Show \fIlines\fR (an integer) lines of context. This option does not +specify an output format by itself; it has no effect unless it is +combined with \fB-c\fR or \fB-u\fR. This option is obsolete. For proper +operation, \fBpatch\fR typically needs at least two lines of context. +.SP +.IP "" 0 +\fB-a\fR +.IP "" 2 +Treat all files as text and compare them line-by-line, even if they +do not seem to be text. +.SP +.IP "" 0 +\fB-b\fR +.IP "" 2 +Ignore trailing white space and consider all other sequences of one or +more white space characters to be equivalent. +.SP +.IP "" 0 +\fB-B\fR +.IP "" 2 +Ignore changes that just insert or delete blank lines. +.SP +.IP "" 0 +\fB--binary\fR +.IP "" 2 +Read and write data in binary mode. +.SP +.IP "" 0 +\fB--brief\fR +.IP "" 2 +Report only whether the files differ, not the details of the +differences. +.SP +.IP "" 0 +\fB-c\fR +.IP "" 2 +Use the context output format. +.SP +.IP "" 0 +\fB-C \fIlines\fB\fR +.IP "" 2 +.IP "" 0 +\fB--context\fR[\fB=\fIlines\fB\fR]\fB\fR +.IP "" 2 +Use the context output format, showing \fIlines\fR (an integer) lines of +context, or three if \fIlines\fR is not given. +For proper operation, \fBpatch\fR typically needs at least two lines of +context. +.SP +.IP "" 0 +\fB--changed-group-format=\fIformat\fB\fR +.IP "" 2 +Use \fIformat\fR to output a line group containing differing lines from +both files in if-then-else format. See `Line group formats\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-d\fR +.IP "" 2 +Change the algorithm to perhaps find a smaller set of changes. This makes +\fBdiff\fR slower (sometimes much slower). +.SP +.IP "" 0 +\fB-e\fR +.IP "" 2 +.IP "" 0 +\fB--ed\fR +.IP "" 2 +Make output that is a valid \fBed\fR script. +.SP +.IP "" 0 +\fB--expand-tabs\fR +.IP "" 2 +Expand tabs to spaces in the output, to preserve the alignment of tabs +in the input files. +.SP +.IP "" 0 +\fB-f\fR +.IP "" 2 +Make output that looks vaguely like an \fBed\fR script but has changes +in the order they appear in the file. +.SP +.IP "" 0 +\fB-F \fIregexp\fB\fR +.IP "" 2 +In context and unified format, for each hunk of differences, show some +of the last preceding line that matches \fIregexp\fR. +.SP +.IP "" 0 +\fB--forward-ed\fR +.IP "" 2 +Make output that looks vaguely like an \fBed\fR script but has changes +in the order they appear in the file. +.SP +.IP "" 0 +\fB-H\fR +.IP "" 2 +Use heuristics to speed handling of large files that have numerous +scattered small changes. +.SP +.IP "" 0 +\fB--horizon-lines=\fIlines\fB\fR +.IP "" 2 +Do not discard the last \fIlines\fR lines of the common prefix +and the first \fIlines\fR lines of the common suffix. +.SP +.IP "" 0 +\fB-i\fR +.IP "" 2 +Ignore changes in case; consider upper- and lower-case letters +equivalent. +.SP +.IP "" 0 +\fB-I \fIregexp\fB\fR +.IP "" 2 +Ignore changes that just insert or delete lines that match \fIregexp\fR. +.SP +.IP "" 0 +\fB--ifdef=\fIname\fB\fR +.IP "" 2 +Make merged if-then-else output using \fIname\fR. +.SP +.IP "" 0 +\fB--ignore-all-space\fR +.IP "" 2 +Ignore white space when comparing lines. +.SP +.IP "" 0 +\fB--ignore-blank-lines\fR +.IP "" 2 +Ignore changes that just insert or delete blank lines. +.SP +.IP "" 0 +\fB--ignore-case\fR +.IP "" 2 +Ignore changes in case; consider upper- and lower-case to be the same. +.SP +.IP "" 0 +\fB--ignore-matching-lines=\fIregexp\fB\fR +.IP "" 2 +Ignore changes that just insert or delete lines that match \fIregexp\fR. +.SP +.IP "" 0 +\fB--ignore-space-change\fR +.IP "" 2 +Ignore trailing white space and consider all other sequences of one or +more white space characters to be equivalent. +.SP +.IP "" 0 +\fB--initial-tab\fR +.IP "" 2 +Output a tab rather than a space before the text of a line in normal or +context format. This causes the alignment of tabs in the line to look +normal. +.SP +.IP "" 0 +\fB-L \fIlabel\fB\fR +.IP "" 2 +Use \fIlabel\fR instead of the file name in the context format +and unified format headers. +.SP +.IP "" 0 +\fB--label=\fIlabel\fB\fR +.IP "" 2 +Use \fIlabel\fR instead of the file name in the context format +and unified format headers. +.SP +.IP "" 0 +\fB--left-column\fR +.IP "" 2 +Print only the left column of two common lines in side by side format. +.SP +.IP "" 0 +\fB--line-format=\fIformat\fB\fR +.IP "" 2 +Use \fIformat\fR to output all input lines in if-then-else format. +See `Line formats\(aq in the CVS manual. +.SP +.IP "" 0 +\fB--minimal\fR +.IP "" 2 +Change the algorithm to perhaps find a smaller set of changes. This +makes \fBdiff\fR slower (sometimes much slower). +.SP +.IP "" 0 +\fB-n\fR +.IP "" 2 +Output RCS-format diffs; like \fB-f\fR except that each command +specifies the number of lines affected. +.SP +.IP "" 0 +\fB-N\fR +.IP "" 2 +.IP "" 0 +\fB--new-file\fR +.IP "" 2 +In directory comparison, if a file is found in only one directory, +treat it as present but empty in the other directory. +.SP +.IP "" 0 +\fB--new-group-format=\fIformat\fB\fR +.IP "" 2 +Use \fIformat\fR to output a group of lines taken from just the second +file in if-then-else format. See `Line group formats\(aq in the CVS manual. +.SP +.IP "" 0 +\fB--new-line-format=\fIformat\fB\fR +.IP "" 2 +Use \fIformat\fR to output a line taken from just the second file in +if-then-else format. See `Line formats\(aq in the CVS manual. +.SP +.IP "" 0 +\fB--old-group-format=\fIformat\fB\fR +.IP "" 2 +Use \fIformat\fR to output a group of lines taken from just the first +file in if-then-else format. See `Line group formats\(aq in the CVS manual. +.SP +.IP "" 0 +\fB--old-line-format=\fIformat\fB\fR +.IP "" 2 +Use \fIformat\fR to output a line taken from just the first file in +if-then-else format. See `Line formats\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-p\fR +.IP "" 2 +Show which C function each change is in. +.SP +.IP "" 0 +\fB--rcs\fR +.IP "" 2 +Output RCS-format diffs; like \fB-f\fR except that each command +specifies the number of lines affected. +.SP +.IP "" 0 +\fB--report-identical-files\fR +.IP "" 2 +.IP "" 0 +\fB-s\fR +.IP "" 2 +Report when two files are the same. +.SP +.IP "" 0 +\fB--show-c-function\fR +.IP "" 2 +Show which C function each change is in. +.SP +.IP "" 0 +\fB--show-function-line=\fIregexp\fB\fR +.IP "" 2 +In context and unified format, for each hunk of differences, show some +of the last preceding line that matches \fIregexp\fR. +.SP +.IP "" 0 +\fB--side-by-side\fR +.IP "" 2 +Use the side by side output format. +.SP +.IP "" 0 +\fB--speed-large-files\fR +.IP "" 2 +Use heuristics to speed handling of large files that have numerous +scattered small changes. +.SP +.IP "" 0 +\fB--suppress-common-lines\fR +.IP "" 2 +Do not print common lines in side by side format. +.SP +.IP "" 0 +\fB-t\fR +.IP "" 2 +Expand tabs to spaces in the output, to preserve the alignment of tabs +in the input files. +.SP +.IP "" 0 +\fB-T\fR +.IP "" 2 +Output a tab rather than a space before the text of a line in normal or +context format. This causes the alignment of tabs in the line to look +normal. +.SP +.IP "" 0 +\fB--text\fR +.IP "" 2 +Treat all files as text and compare them line-by-line, even if they +do not appear to be text. +.SP +.IP "" 0 +\fB-u\fR +.IP "" 2 +Use the unified output format. +.SP +.IP "" 0 +\fB--unchanged-group-format=\fIformat\fB\fR +.IP "" 2 +Use \fIformat\fR to output a group of common lines taken from both files +in if-then-else format. see node `Line group formats\(aq in the CVS manual. +.SP +.IP "" 0 +\fB--unchanged-line-format=\fIformat\fB\fR +.IP "" 2 +Use \fIformat\fR to output a line common to both files in if-then-else +format. see node `Line formats\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-U \fIlines\fB\fR +.IP "" 2 +.IP "" 0 +\fB--unified\fR[\fB=\fIlines\fB\fR]\fB\fR +.IP "" 2 +Use the unified output format, showing \fIlines\fR (an integer) lines of +context, or three if \fIlines\fR is not given. +For proper operation, \fBpatch\fR typically needs at least two lines of +context. +.SP +.IP "" 0 +\fB-w\fR +.IP "" 2 +Ignore white space when comparing lines. +.SP +.IP "" 0 +\fB-W \fIcolumns\fB\fR +.IP "" 2 +.IP "" 0 +\fB--width=\fIcolumns\fB\fR +.IP "" 2 +Use an output width of \fIcolumns\fR in side by side format. +.SP +.IP "" 0 +\fB-y\fR +.IP "" 2 +Use the side by side output format. +.SP +.SH "Line group formats" +.SP +Line group formats let you specify formats suitable for many +applications that allow if-then-else input, including programming +languages and text formatting languages. A line group format specifies +the output format for a contiguous group of similar lines. +.SP +For example, the following command compares the TeX file \fBmyfile\fR +with the original version from the repository, +and outputs a merged file in which old regions are +surrounded by \fB\\begin{em}\fR-\fB\\end{em}\fR lines, and new +regions are surrounded by \fB\\begin{bf}\fR-\fB\\end{bf}\fR lines. +.SP +.PD 0 +.SP +.IP "" 2 +cvs diff \\ +.IP "" 2 + --old-group-format=\(aq\\begin{em} +.IP "" 2 +%<\\end{em} +.IP "" 2 +\(aq \\ +.IP "" 2 + --new-group-format=\(aq\\begin{bf} +.IP "" 2 +%>\\end{bf} +.IP "" 2 +\(aq \\ +.IP "" 2 + myfile + +.PD +.IP "" 0 +.SP +The following command is equivalent to the above example, but it is a +little more verbose, because it spells out the default line group formats. +.SP +.PD 0 +.SP +.IP "" 2 +cvs diff \\ +.IP "" 2 + --old-group-format=\(aq\\begin{em} +.IP "" 2 +%<\\end{em} +.IP "" 2 +\(aq \\ +.IP "" 2 + --new-group-format=\(aq\\begin{bf} +.IP "" 2 +%>\\end{bf} +.IP "" 2 +\(aq \\ +.IP "" 2 + --unchanged-group-format=\(aq%=\(aq \\ +.IP "" 2 + --changed-group-format=\(aq\\begin{em} +.IP "" 2 +%<\\end{em} +.IP "" 2 +\\begin{bf} +.IP "" 2 +%>\\end{bf} +.IP "" 2 +\(aq \\ +.IP "" 2 + myfile + +.PD +.IP "" 0 +.SP +Here is a more advanced example, which outputs a diff listing with +headers containing line numbers in a \`\`plain English\(aq\(aq style. +.SP +.PD 0 +.SP +.IP "" 2 +cvs diff \\ +.IP "" 2 + --unchanged-group-format=\(aq\(aq \\ +.IP "" 2 + --old-group-format=\(aq-------- %dn line%(n=1?:s) deleted at %df: +.IP "" 2 +%<\(aq \\ +.IP "" 2 + --new-group-format=\(aq-------- %dN line%(N=1?:s) added after %de: +.IP "" 2 +%>\(aq \\ +.IP "" 2 + --changed-group-format=\(aq-------- %dn line%(n=1?:s) changed at %df: +.IP "" 2 +%<-------- to: +.IP "" 2 +%>\(aq \\ +.IP "" 2 + myfile + +.PD +.IP "" 0 +.SP +To specify a line group format, use one of the options +listed below. You can specify up to four line group formats, one for +each kind of line group. You should quote \fIformat\fR, because it +typically contains shell metacharacters. +.SP +.IP "" 0 +\fB--old-group-format=\fIformat\fB\fR +.IP "" 2 +These line groups are hunks containing only lines from the first file. +The default old group format is the same as the changed group format if +it is specified; otherwise it is a format that outputs the line group as-is. +.SP +.IP "" 0 +\fB--new-group-format=\fIformat\fB\fR +.IP "" 2 +These line groups are hunks containing only lines from the second +file. The default new group format is same as the changed group +format if it is specified; otherwise it is a format that outputs the +line group as-is. +.SP +.IP "" 0 +\fB--changed-group-format=\fIformat\fB\fR +.IP "" 2 +These line groups are hunks containing lines from both files. The +default changed group format is the concatenation of the old and new +group formats. +.SP +.IP "" 0 +\fB--unchanged-group-format=\fIformat\fB\fR +.IP "" 2 +These line groups contain lines common to both files. The default +unchanged group format is a format that outputs the line group as-is. +.SP +In a line group format, ordinary characters represent themselves; +conversion specifications start with \fB%\fR and have one of the +following forms. +.SP +.IP "" 0 +\fB%<\fR +.IP "" 2 +stands for the lines from the first file, including the trailing newline. +Each line is formatted according to the old line format (see node `Line formats\(aq in the CVS manual). +.SP +.IP "" 0 +\fB%>\fR +.IP "" 2 +stands for the lines from the second file, including the trailing newline. +Each line is formatted according to the new line format. +.SP +.IP "" 0 +\fB%=\fR +.IP "" 2 +stands for the lines common to both files, including the trailing newline. +Each line is formatted according to the unchanged line format. +.SP +.IP "" 0 +\fB%%\fR +.IP "" 2 +stands for \fB%\fR. +.SP +.IP "" 0 +\fB%c\(aq\fIC\fB\(aq\fR +.IP "" 2 +where \fIC\fR is a single character, stands for \fIC\fR. +\fIC\fR may not be a backslash or an apostrophe. +For example, \fB%c\(aq:\(aq\fR stands for a colon, even inside +the then-part of an if-then-else format, which a colon would +normally terminate. +.SP +.IP "" 0 +\fB%c\(aq\\\fIO\fB\(aq\fR +.IP "" 2 +where \fIO\fR is a string of 1, 2, or 3 octal digits, +stands for the character with octal code \fIO\fR. +For example, \fB%c\(aq\\0\(aq\fR stands for a null character. +.SP +.IP "" 0 +\fB\fIF\fB\fIn\fB\fR +.IP "" 2 +where \fIF\fR is a \fBprintf\fR conversion specification and \fIn\fR is one +of the following letters, stands for \fIn\fR\(aqs value formatted with \fIF\fR. +.SP +.IP "" 2 +\fBe\fR +.IP "" 4 +The line number of the line just before the group in the old file. +.SP +.IP "" 2 +\fBf\fR +.IP "" 4 +The line number of the first line in the group in the old file; +equals \fIe\fR + 1. +.SP +.IP "" 2 +\fBl\fR +.IP "" 4 +The line number of the last line in the group in the old file. +.SP +.IP "" 2 +\fBm\fR +.IP "" 4 +The line number of the line just after the group in the old file; +equals \fIl\fR + 1. +.SP +.IP "" 2 +\fBn\fR +.IP "" 4 +The number of lines in the group in the old file; equals \fIl\fR - \fIf\fR + 1. +.SP +.IP "" 2 +\fBE, F, L, M, N\fR +.IP "" 4 +Likewise, for lines in the new file. +.SP +.SP +The \fBprintf\fR conversion specification can be \fB%d\fR, +\fB%o\fR, \fB%x\fR, or \fB%X\fR, specifying decimal, octal, +lower case hexadecimal, or upper case hexadecimal output +respectively. After the \fB%\fR the following options can appear in +sequence: a \fB-\fR specifying left-justification; an integer +specifying the minimum field width; and a period followed by an +optional integer specifying the minimum number of digits. +For example, \fB%5dN\fR prints the number of new lines in the group +in a field of width 5 characters, using the \fBprintf\fR format \fB"%5d"\fR. +.SP +.IP "" 0 +\fB(\fIA\fB=\fIB\fB?\fIT\fB:\fIE\fB)\fR +.IP "" 2 +If \fIA\fR equals \fIB\fR then \fIT\fR else \fIE\fR. +\fIA\fR and \fIB\fR are each either a decimal constant +or a single letter interpreted as above. +This format spec is equivalent to \fIT\fR if +\fIA\fR\(aqs value equals \fIB\fR\(aqs; otherwise it is equivalent to \fIE\fR. +.SP +For example, \fB%(N=0?no:%dN) line%(N=1?:s)\fR is equivalent to +\fBno lines\fR if \fIN\fR (the number of lines in the group in the +new file) is 0, to \fB1 line\fR if \fIN\fR is 1, and to \fB%dN lines\fR +otherwise. +.SP +.SH "Line formats" +.SP +Line formats control how each line taken from an input file is +output as part of a line group in if-then-else format. +.SP +For example, the following command outputs text with a one-column +change indicator to the left of the text. The first column of output +is \fB-\fR for deleted lines, \fB|\fR for added lines, and a space +for unchanged lines. The formats contain newline characters where +newlines are desired on output. +.SP +.PD 0 +.SP +.IP "" 2 +cvs diff \\ +.IP "" 2 + --old-line-format=\(aq-%l +.IP "" 2 +\(aq \\ +.IP "" 2 + --new-line-format=\(aq|%l +.IP "" 2 +\(aq \\ +.IP "" 2 + --unchanged-line-format=\(aq %l +.IP "" 2 +\(aq \\ +.IP "" 2 + myfile + +.PD +.IP "" 0 +.SP +To specify a line format, use one of the following options. You should +quote \fIformat\fR, since it often contains shell metacharacters. +.SP +.IP "" 0 +\fB--old-line-format=\fIformat\fB\fR +.IP "" 2 +formats lines just from the first file. +.SP +.IP "" 0 +\fB--new-line-format=\fIformat\fB\fR +.IP "" 2 +formats lines just from the second file. +.SP +.IP "" 0 +\fB--unchanged-line-format=\fIformat\fB\fR +.IP "" 2 +formats lines common to both files. +.SP +.IP "" 0 +\fB--line-format=\fIformat\fB\fR +.IP "" 2 +formats all lines; in effect, it sets all three above options simultaneously. +.SP +In a line format, ordinary characters represent themselves; +conversion specifications start with \fB%\fR and have one of the +following forms. +.SP +.IP "" 0 +\fB%l\fR +.IP "" 2 +stands for the contents of the line, not counting its trailing +newline (if any). This format ignores whether the line is incomplete. +.SP +.IP "" 0 +\fB%L\fR +.IP "" 2 +stands for the contents of the line, including its trailing newline +(if any). If a line is incomplete, this format preserves its +incompleteness. +.SP +.IP "" 0 +\fB%%\fR +.IP "" 2 +stands for \fB%\fR. +.SP +.IP "" 0 +\fB%c\(aq\fIC\fB\(aq\fR +.IP "" 2 +where \fIC\fR is a single character, stands for \fIC\fR. +\fIC\fR may not be a backslash or an apostrophe. +For example, \fB%c\(aq:\(aq\fR stands for a colon. +.SP +.IP "" 0 +\fB%c\(aq\\\fIO\fB\(aq\fR +.IP "" 2 +where \fIO\fR is a string of 1, 2, or 3 octal digits, +stands for the character with octal code \fIO\fR. +For example, \fB%c\(aq\\0\(aq\fR stands for a null character. +.SP +.IP "" 0 +\fB\fIF\fBn\fR +.IP "" 2 +where \fIF\fR is a \fBprintf\fR conversion specification, +stands for the line number formatted with \fIF\fR. +For example, \fB%.5dn\fR prints the line number using the +\fBprintf\fR format \fB"%.5d"\fR. see node `Line group formats\(aq in the CVS manual, for +more about printf conversion specifications. +.SP +.SP +The default line format is \fB%l\fR followed by a newline character. +.SP +If the input contains tab characters and it is important that they line +up on output, you should ensure that \fB%l\fR or \fB%L\fR in a line +format is just after a tab stop (e.g. by preceding \fB%l\fR or +\fB%L\fR with a tab character), or you should use the \fB-t\fR or +\fB--expand-tabs\fR option. +.SP +Taken together, the line and line group formats let you specify many +different formats. For example, the following command uses a format +similar to \fBdiff\fR\(aqs normal format. You can tailor this command +to get fine control over \fBdiff\fR\(aqs output. +.SP +.PD 0 +.SP +.IP "" 2 +cvs diff \\ +.IP "" 2 + --old-line-format=\(aq< %l +.IP "" 2 +\(aq \\ +.IP "" 2 + --new-line-format=\(aq> %l +.IP "" 2 +\(aq \\ +.IP "" 2 + --old-group-format=\(aq%df%(f=l?:,%dl)d%dE +.IP "" 2 +%<\(aq \\ +.IP "" 2 + --new-group-format=\(aq%dea%dF%(F=L?:,%dL) +.IP "" 2 +%>\(aq \\ +.IP "" 2 + --changed-group-format=\(aq%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) +.IP "" 2 +%<\(em +.IP "" 2 +%>\(aq \\ +.IP "" 2 + --unchanged-group-format=\(aq\(aq \\ +.IP "" 2 + myfile + +.PD +.IP "" 0 +.SP +.SH "diff examples" +.SP +The following line produces a Unidiff (\fB-u\fR flag) +between revision 1.14 and 1.19 of +\fBbackend.c\fR. Due to the \fB-kk\fR flag no +keywords are substituted, so differences that only depend +on keyword substitution are ignored. +.SP +.PD 0 +.SP +.IP "" 2 +$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c + +.PD +.IP "" 0 +.SP +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: +.SP +.PD 0 +.SP +.IP "" 2 +$ cvs diff -r RELEASE_1_0 -r EXPR1 + +.PD +.IP "" 0 +.SP +A command like this can be used to produce a context +diff between two releases: +.SP +.PD 0 +.SP +.IP "" 2 +$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs + +.PD +.IP "" 0 +.SP +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. +.SP +.PD 0 +.SP +.IP "" 2 +$ cvs diff -u | less + +.PD +.IP "" 0 +.SP +.SH "export" +.SS "Export sources from CVS, similar to checkout" +.IX "export (subcommand)" +.SP +.IP "\(bu" 2 +Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] module\&... +.IP "\(bu" 2 +Requires: repository. +.IP "\(bu" 2 +Changes: current directory. +.SP +This command is a variant of \fBcheckout\fR; use it +when you want a copy of the source for module without +the \fBcvs\fR administrative directories. For example, you +might use \fBexport\fR to prepare source for shipment +off-site. This command requires that you specify a +date or tag (with \fB-D\fR or \fB-r\fR), so that you +can count on reproducing the source you ship to others +(and thus it always prunes empty directories). +.SP +One often would like to use \fB-kv\fR with \fBcvs +export\fR. This causes any 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\(aqt handle an export containing binary +files correctly. Also be aware that after having used +\fB-kv\fR, one can no longer use the \fBident\fR +command (which is part of the \fBrcs\fR suite\(emsee +ident(1)) which looks for keyword strings. If +you want to be able to use \fBident\fR you must not +use \fB-kv\fR. +.SP +.SH "export options" +.SP +These standard options are supported by \fBexport\fR +(see node `Common options\(aq in the CVS manual, for a complete description of +them): +.SP +.IP "" 0 +\fB-D \fIdate\fB\fR +.IP "" 2 +Use the most recent revision no later than \fIdate\fR. +.SP +.IP "" 0 +\fB-f\fR +.IP "" 2 +If no matching revision is found, retrieve the most +recent revision (instead of ignoring the file). +.SP +.IP "" 0 +\fB-l\fR +.IP "" 2 +Local; run only in current working directory. +.SP +.IP "" 0 +\fB-n\fR +.IP "" 2 +Do not run any checkout program. +.SP +.IP "" 0 +\fB-R\fR +.IP "" 2 +Export directories recursively. This is on by default. +.SP +.IP "" 0 +\fB-r \fItag\fB\fR +.IP "" 2 +Use revision \fItag\fR. +.SP +In addition, these options (that are common to +\fBcheckout\fR and \fBexport\fR) are also supported: +.SP +.IP "" 0 +\fB-d \fIdir\fB\fR +.IP "" 2 +Create a directory called \fIdir\fR for the working +files, instead of using the module name. +See `checkout options\(aq in the CVS manual for complete details on how +\fBcvs\fR handles this flag. +.SP +.IP "" 0 +\fB-k \fIsubst\fB\fR +.IP "" 2 +Set keyword expansion mode (see node `Substitution modes\(aq in the CVS manual). +.SP +.IP "" 0 +\fB-N\fR +.IP "" 2 +Only useful together with \fB-d \fIdir\fB\fR. +See `checkout options\(aq in the CVS manual for complete details on how +\fBcvs\fR handles this flag. +.SP +.SH "history" +.SS "Show status of files and users" +.IX "history (subcommand)" +.SP +.IP "\(bu" 2 +Synopsis: history [-report] [-flags] [-options args] [files\&...] +.IP "\(bu" 2 +Requires: the file \fB$CVSROOT/CVSROOT/history\fR +.IP "\(bu" 2 +Changes: nothing. +.SP +\fBcvs\fR can keep a history file that tracks each use of the +\fBcheckout\fR, \fBcommit\fR, \fBrtag\fR, +\fBupdate\fR, and \fBrelease\fR commands. You can +use \fBhistory\fR to display this information in +various formats. +.SP +Logging must be enabled by creating the file +\fB$CVSROOT/CVSROOT/history\fR. +.SP +\fB\fBhistory\fB uses \fB-f\fB, \fB-l\fB, +\fB-n\fB, and \fB-p\fB in ways that conflict with the +normal use inside \fBcvs\fB (see node `Common options\(aq in the CVS manual).\fR +.SP +.SH "history options" +.SP +Several options (shown above as \fB-report\fR) control what +kind of report is generated: +.SP +.IP "" 0 +\fB-c\fR +.IP "" 2 +Report on each time commit was used (i.e., each time +the repository was modified). +.SP +.IP "" 0 +\fB-e\fR +.IP "" 2 +Everything (all record types). Equivalent to +specifying \fB-x\fR with all record types. Of course, +\fB-e\fR will also include record types which are +added in a future version of \fBcvs\fR; if you are +writing a script which can only handle certain record +types, you\(aqll want to specify \fB-x\fR. +.SP +.IP "" 0 +\fB-m \fImodule\fB\fR +.IP "" 2 +Report on a particular module. (You can meaningfully +use \fB-m\fR more than once on the command line.) +.SP +.IP "" 0 +\fB-o\fR +.IP "" 2 +Report on checked-out modules. This is the default report type. +.SP +.IP "" 0 +\fB-T\fR +.IP "" 2 +Report on all tags. +.SP +.IP "" 0 +\fB-x \fItype\fB\fR +.IP "" 2 +Extract a particular set of record types \fItype\fR from the \fBcvs\fR +history. The types are indicated by single letters, +which you may specify in combination. +.SP +Certain commands have a single record type: +.SP +.IP "" 2 +\fBF\fR +.IP "" 4 +release +.IP "" 2 +\fBO\fR +.IP "" 4 +checkout +.IP "" 2 +\fBE\fR +.IP "" 4 +export +.IP "" 2 +\fBT\fR +.IP "" 4 +rtag +.SP +One of five record types may result from an update: +.SP +.IP "" 2 +\fBC\fR +.IP "" 4 +A merge was necessary but collisions were +detected (requiring manual merging). +.IP "" 2 +\fBG\fR +.IP "" 4 +A merge was necessary and it succeeded. +.IP "" 2 +\fBU\fR +.IP "" 4 +A working file was copied from the repository. +.IP "" 2 +\fBP\fR +.IP "" 4 +A working file was patched to match the repository. +.IP "" 2 +\fBW\fR +.IP "" 4 +The working copy of a file was deleted during +update (because it was gone from the repository). +.SP +One of three record types results from commit: +.SP +.IP "" 2 +\fBA\fR +.IP "" 4 +A file was added for the first time. +.IP "" 2 +\fBM\fR +.IP "" 4 +A file was modified. +.IP "" 2 +\fBR\fR +.IP "" 4 +A file was removed. +.SP +The options shown as \fB-flags\fR constrain or expand +the report without requiring option arguments: +.SP +.IP "" 0 +\fB-a\fR +.IP "" 2 +Show data for all users (the default is to show data +only for the user executing \fBhistory\fR). +.SP +.IP "" 0 +\fB-l\fR +.IP "" 2 +Show last modification only. +.SP +.IP "" 0 +\fB-w\fR +.IP "" 2 +Show only the records for modifications done from the +same working directory where \fBhistory\fR is +executing. +.SP +The options shown as \fB-options \fIargs\fB\fR constrain the report +based on an argument: +.SP +.IP "" 0 +\fB-b \fIstr\fB\fR +.IP "" 2 +Show data back to a record containing the string +\fIstr\fR in either the module name, the file name, or +the repository path. +.SP +.IP "" 0 +\fB-D \fIdate\fB\fR +.IP "" 2 +Show data since \fIdate\fR. This is slightly different +from the normal use of \fB-D \fIdate\fB\fR, which +selects the newest revision older than \fIdate\fR. +.SP +.IP "" 0 +\fB-f \fIfile\fB\fR +.IP "" 2 +Show data for a particular file +(you can specify several \fB-f\fR options on the same command line). +This is equivalent to specifying the file on the command line. +.SP +.IP "" 0 +\fB-n \fImodule\fB\fR +.IP "" 2 +Show data for a particular module +(you can specify several \fB-n\fR options on the same command line). +.SP +.IP "" 0 +\fB-p \fIrepository\fB\fR +.IP "" 2 +Show data for a particular source repository (you +can specify several \fB-p\fR options on the same command +line). +.SP +.IP "" 0 +\fB-r \fIrev\fB\fR +.IP "" 2 +Show records referring to revisions since the revision +or tag named \fIrev\fR appears in individual \fBrcs\fR +files. Each \fBrcs\fR file is searched for the revision or +tag. +.SP +.IP "" 0 +\fB-t \fItag\fB\fR +.IP "" 2 +Show records since tag \fItag\fR was last added to the +history file. This differs from the \fB-r\fR flag +above in that it reads only the history file, not the +\fBrcs\fR files, and is much faster. +.SP +.IP "" 0 +\fB-u \fIname\fB\fR +.IP "" 2 +Show records for user \fIname\fR. +.SP +.IP "" 0 +\fB-z \fItimezone\fB\fR +.IP "" 2 +Show times in the selected records using the specified +time zone instead of UTC. +.SP +.SH "import" +.SS "Import sources into CVS, using vendor branches" +.IX "import (subcommand)" +.SP +.IP "\(bu" 2 +Synopsis: import [-options] repository vendortag releasetag\&... +.IP "\(bu" 2 +Requires: Repository, source distribution directory. +.IP "\(bu" 2 +Changes: repository. +.SP +Use \fBimport\fR 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. See `Tracking sources\(aq in the CVS manual for +a discussion on this subject. +.SP +The \fIrepository\fR argument gives a directory name +(or a path to a directory) under the \fBcvs\fR root directory +for repositories; if the directory did not exist, +import creates it. +.SP +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 \fBcheckout +-j\fR to reconcile the differences, as import instructs +you to do. +.SP +If \fBcvs\fR decides a file should be ignored +(see node `cvsignore\(aq in the CVS manual), it does not import it and prints +\fBI \fR followed by the filename (see node `import output\(aq in the CVS manual for a +complete description of the output). +.SP +If the file \fB$CVSROOT/CVSROOT/cvswrappers\fR 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. See `Wrappers\(aq in the CVS manual. +.SP +The outside source is saved in a first-level +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. +.SP +At least three arguments are required. +\fIrepository\fR is needed to identify the collection +of source. \fIvendortag\fR is a tag for the entire +branch (e.g., for 1.1.1). You must also specify at +least one \fIreleasetag\fR to uniquely identify the files at +the leaves created each time you execute \fBimport\fR. The +\fIreleasetag\fR should be new, not previously existing in the +repository file, and uniquely identify the imported release, +.SP +Note that \fBimport\fR does \fInot\fR change the +directory in which you invoke it. In particular, it +does not set up that directory as a \fBcvs\fR working +directory; if you want to work with the sources import +them first and then check them out into a different +directory (see node `Getting the source\(aq in the CVS manual). +.SP +.SH "import options" +.SP +This standard option is supported by \fBimport\fR +(see node `Common options\(aq in the CVS manual for a complete description): +.SP +.IP "" 0 +\fB-m \fImessage\fB\fR +.IP "" 2 +Use \fImessage\fR as log information, instead of +invoking an editor. +.SP +There are the following additional special options. +.SP +.IP "" 0 +\fB-b \fIbranch\fB\fR +.IP "" 2 +See `Multiple vendor branches\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-k \fIsubst\fB\fR +.IP "" 2 +Indicate the 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 `Substitution modes\(aq in the CVS manual for a +list of valid \fB-k\fR settings. +.SP +.IP "" 0 +\fB-I \fIname\fB\fR +.IP "" 2 +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 !\(aq. +.SP +\fIname\fR can be a file name pattern of the same type +that you can specify in the \fB.cvsignore\fR file. +See `cvsignore\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-W \fIspec\fB\fR +.IP "" 2 +Specify file names that should be filtered during +import. You can use this option repeatedly. +.SP +\fIspec\fR can be a file name pattern of the same type +that you can specify in the \fB.cvswrappers\fR +file. see node `Wrappers\(aq in the CVS manual. +.SP +.SH "import output" +.SP +\fBimport\fR keeps you informed of its progress by printing a line +for each file, preceded by one character indicating the status of the file: +.SP +.IP "" 0 +\fBU \fIfile\fB\fR +.IP "" 2 +The file already exists in the repository and has not been locally +modified; a new revision has been created (if necessary). +.SP +.IP "" 0 +\fBN \fIfile\fB\fR +.IP "" 2 +The file is a new file which has been added to the repository. +.SP +.IP "" 0 +\fBC \fIfile\fB\fR +.IP "" 2 +The file already exists in the repository but has been locally modified; +you will have to merge the changes. +.SP +.IP "" 0 +\fBI \fIfile\fB\fR +.IP "" 2 +The file is being ignored (see node `cvsignore\(aq in the CVS manual). +.SP +.IX "Symbolic link, importing" +.IX "Link, symbolic, importing" +.IP "" 0 +\fBL \fIfile\fB\fR +.IP "" 2 +The file is a symbolic link; \fBcvs import\fR ignores symbolic links. +People periodically suggest that this behavior should +be changed, but if there is a consensus on what it +should be changed to, it doesn\(aqt seem to be apparent. +(Various options in the \fBmodules\fR file can be used +to recreate symbolic links on checkout, update, etc.; +see node `modules\(aq in the CVS manual.) +.SP +.SH "import examples" +.SP +See `Tracking sources\(aq in the CVS manual, and `From files\(aq in the CVS manual. +.SP +.SH "log" +.SS "Print out log information for files" +.IX "log (subcommand)" +.SP +.IP "\(bu" 2 +Synopsis: log [options] [files\&...] +.IP "\(bu" 2 +Requires: repository, working directory. +.IP "\(bu" 2 +Changes: nothing. +.SP +Display log information for files. \fBlog\fR used to +call the \fBrcs\fR utility \fBrlog\fR. Although this +is no longer true in the current sources, this history +determines the format of the output and the options, +which are not quite in the style of the other \fBcvs\fR +commands. +.SP +.IX "Timezone, in output" +.IX "Zone, time, in output" +The output includes the location of the \fBrcs\fR file, +the \fIhead\fR 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 +\fBcvs\fR print times in the local timezone). +.SP +\fB\fBlog\fB uses \fB-R\fB in a way that conflicts +with the normal use inside \fBcvs\fB (see node `Common options\(aq in the CVS manual).\fR +.SP +.SH "log options" +.SP +By default, \fBlog\fR prints all information that is +available. All other options restrict the output. Note that the revision +selection options (\fB-b\fR, \fB-d\fR, \fB-r\fR, \fB-s\fR, and \fB-w\fR) +have no +effect, other than possibly causing a search for files in Attic directories, +when used in conjunction with the options that restrict the output to only +\fBlog\fR header fields (\fB-h\fR, \fB-R\fR, and \fB-t\fR) +unless the \fB-S\fR option is also specified. +.SP +.IP "" 0 +\fB-b\fR +.IP "" 2 +Print information about the revisions on the default +branch, normally the highest branch on the trunk. +.SP +.IP "" 0 +\fB-d \fIdates\fB\fR +.IP "" 2 +Print information about revisions with a checkin +date/time in the range given by the +semicolon-separated list of dates. The date formats +accepted are those accepted by the \fB-D\fR option to +many other \fBcvs\fR commands (see node `Common options\(aq in the CVS manual). +Dates can be combined into ranges as follows: +.SP +.IP "" 2 +\fB\fId1\fB<\fId2\fB\fR +.IP "" 4 +.IP "" 2 +\fB\fId2\fB>\fId1\fB\fR +.IP "" 4 +Select the revisions that were deposited between +\fId1\fR and \fId2\fR. +.SP +.IP "" 2 +\fB<\fId\fB\fR +.IP "" 4 +.IP "" 2 +\fB\fId\fB>\fR +.IP "" 4 +Select all revisions dated \fId\fR or earlier. +.SP +.IP "" 2 +\fB\fId\fB<\fR +.IP "" 4 +.IP "" 2 +\fB>\fId\fB\fR +.IP "" 4 +Select all revisions dated \fId\fR or later. +.SP +.IP "" 2 +\fB\fId\fB\fR +.IP "" 4 +Select the single, latest revision dated \fId\fR or +earlier. +.SP +The \fB>\fR or \fB<\fR characters may be followed by +\fB=\fR to indicate an inclusive range rather than an +exclusive one. +.SP +Note that the separator is a semicolon (;). +.SP +.IP "" 0 +\fB-h\fR +.IP "" 2 +Print only the name of the \fBrcs\fR file, name +of the file in the working directory, head, +default branch, access list, locks, symbolic names, and +suffix. +.SP +.IP "" 0 +\fB-l\fR +.IP "" 2 +Local; run only in current working directory. (Default +is to run recursively). +.SP +.IP "" 0 +\fB-N\fR +.IP "" 2 +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"\(aqing over 3 pages of tag +information, the log information is presented without +tags at all. +.SP +.IP "" 0 +\fB-n\fR +.IP "" 2 +Print the list of tags for this file. This option can +be very useful when your \fB.cvsrc\fR file has a +\fBlog -N\fR entry as a way to get a full list of all +of the tags. +.SP +.IP "" 0 +\fB-R\fR +.IP "" 2 +Print only the name of the \fBrcs\fR file. +.SP +.IP "" 0 +\fB-r\fIrevisions\fB\fR +.IP "" 2 +Print information about revisions given in the +comma-separated list \fIrevisions\fR of revisions and +ranges. The following table explains the available +range formats: +.SP +.IP "" 2 +\fB\fIrev1\fB:\fIrev2\fB\fR +.IP "" 4 +Revisions \fIrev1\fR to \fIrev2\fR (which must be on +the same branch). +.SP +.IP "" 2 +\fB\fIrev1\fB::\fIrev2\fB\fR +.IP "" 4 +The same, but excluding \fIrev1\fR. +.SP +.IP "" 2 +\fB:\fIrev\fB\fR +.IP "" 4 +.IP "" 2 +\fB::\fIrev\fB\fR +.IP "" 4 +Revisions from the beginning of the branch up to +and including \fIrev\fR. +.SP +.IP "" 2 +\fB\fIrev\fB:\fR +.IP "" 4 +Revisions starting with \fIrev\fR to the end of the +branch containing \fIrev\fR. +.SP +.IP "" 2 +\fB\fIrev\fB::\fR +.IP "" 4 +Revisions starting just after \fIrev\fR to the end of the +branch containing \fIrev\fR. +.SP +.IP "" 2 +\fB\fIbranch\fB\fR +.IP "" 4 +An argument that is a branch means all revisions on +that branch. +.SP +.IP "" 2 +\fB\fIbranch1\fB:\fIbranch2\fB\fR +.IP "" 4 +.IP "" 2 +\fB\fIbranch1\fB::\fIbranch2\fB\fR +.IP "" 4 +A range of branches means all revisions +on the branches in that range. +.SP +.IP "" 2 +\fB\fIbranch\fB.\fR +.IP "" 4 +The latest revision in \fIbranch\fR. +.SP +A bare \fB-r\fR with no revisions means the latest +revision on the default branch, normally the trunk. +There can be no space between the \fB-r\fR option and +its argument. +.SP +.IP "" 0 +\fB-S\fR +.IP "" 2 +Suppress the header if no revisions are selected. +.SP +.IP "" 0 +\fB-s \fIstates\fB\fR +.IP "" 2 +Print information about revisions whose state +attributes match one of the states given in the +comma-separated list \fIstates\fR. Individual states may +be any text string, though \fBcvs\fR commonly only uses two +states, \fBExp\fR and \fBdead\fR. See `admin options\(aq in the CVS manual +for more information. +.SP +.IP "" 0 +\fB-t\fR +.IP "" 2 +Print the same as \fB-h\fR, plus the descriptive text. +.SP +.IP "" 0 +\fB-w\fIlogins\fB\fR +.IP "" 2 +Print information about revisions checked in by users +with login names appearing in the comma-separated list +\fIlogins\fR. If \fIlogins\fR is omitted, the user\(aqs +login is assumed. There can be no space between the +\fB-w\fR option and its argument. +.SP +\fBlog\fR prints the intersection of the revisions +selected with the options \fB-d\fR, \fB-s\fR, and +\fB-w\fR, intersected with the union of the revisions +selected by \fB-b\fR and \fB-r\fR. +.SP +.SH "log examples" +.SP +Contributed examples are gratefully accepted. +.SP +.SH "rdiff" +.SS "\(aqpatch\(aq format diffs between releases" +.IX "rdiff (subcommand)" +.SP +.IP "\(bu" 2 +rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules\&... +.IP "\(bu" 2 +Requires: repository. +.IP "\(bu" 2 +Changes: nothing. +.IP "\(bu" 2 +Synonym: patch +.SP +Builds a Larry Wall format patch(1) file between two +releases, that can be fed directly into the \fBpatch\fR +program to bring an old release up-to-date with the new +release. (This is one of the few \fBcvs\fR commands that +operates directly from the repository, and doesn\(aqt +require a prior checkout.) The diff output is sent to +the standard output device. +.SP +You can specify (using the standard \fB-r\fR and +\fB-D\fR 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 \fBrcs\fR file. +.SP +Note that if the software release affected is contained +in more than one directory, then it may be necessary to +specify the \fB-p\fR option to the \fBpatch\fR command when +patching the old sources, so that \fBpatch\fR is able to find +the files that are located in other directories. +.SP +.SH "rdiff options" +.SP +These standard options are supported by \fBrdiff\fR +(see node `Common options\(aq in the CVS manual for a complete description of +them): +.SP +.IP "" 0 +\fB-D \fIdate\fB\fR +.IP "" 2 +Use the most recent revision no later than \fIdate\fR. +.SP +.IP "" 0 +\fB-f\fR +.IP "" 2 +If no matching revision is found, retrieve the most +recent revision (instead of ignoring the file). +.SP +.IP "" 0 +\fB-k \fIkflag\fB\fR +.IP "" 2 +Process keywords according to \fIkflag\fR. See +`Keyword substitution\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-l\fR +.IP "" 2 +Local; don\(aqt descend subdirectories. +.SP +.IP "" 0 +\fB-R\fR +.IP "" 2 +Examine directories recursively. This option is on by default. +.SP +.IP "" 0 +\fB-r \fItag\fB\fR +.IP "" 2 +Use revision \fItag\fR. +.SP +In addition to the above, these options are available: +.SP +.IP "" 0 +\fB-c\fR +.IP "" 2 +Use the context diff format. This is the default format. +.SP +.IP "" 0 +\fB-s\fR +.IP "" 2 +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. +.SP +.IP "" 0 +\fB-t\fR +.IP "" 2 +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. +.SP +.IP "" 0 +\fB-u\fR +.IP "" 2 +Use the unidiff format for the context diffs. +Remember that old versions +of the \fBpatch\fR program can\(aqt handle the unidiff +format, so if you plan to post this patch to the net +you should probably not use \fB-u\fR. +.SP +.IP "" 0 +\fB-V \fIvn\fB\fR +.IP "" 2 +Expand keywords according to the rules current in +\fBrcs\fR version \fIvn\fR (the expansion format changed with +\fBrcs\fR version 5). Note that this option is no +longer accepted. \fBcvs\fR will always expand keywords the +way that \fBrcs\fR version 5 does. +.SP +.SH "rdiff examples" +.SP +Suppose you receive mail from \fRfoo@example.net\fR asking for an +update from release 1.2 to 1.4 of the tc compiler. You +have no such patches on hand, but with \fBcvs\fR that can +easily be fixed with a command such as this: +.SP +.PD 0 +.SP +.IP "" 2 +$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \\ +.IP "" 2 +> Mail -s \(aqThe patches you asked for\(aq foo@example.net + +.PD +.IP "" 0 +.SP +Suppose you have made release 1.3, and forked a branch +called \fBR_1_3fix\fR for bug fixes. \fBR_1_3_1\fR +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: +.SP +.PD 0 +.SP +.IP "" 2 +$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name +.IP "" 2 +cvs rdiff: Diffing module-name +.IP "" 2 +File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6 +.IP "" 2 +File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4 +.IP "" 2 +File bar.h,v changed from revision 1.29.2.1 to 1.2 + +.PD +.IP "" 0 +.SP +.SH "release" +.SS "Indicate that a Module is no longer in use" +.IX "release (subcommand)" +.SP +.IP "\(bu" 2 +release [-d] directories\&... +.IP "\(bu" 2 +Requires: Working directory. +.IP "\(bu" 2 +Changes: Working directory, history log. +.SP +This command is meant to safely cancel the effect of +\fBcvs checkout\fR. Since \fBcvs\fR doesn\(aqt lock files, it +isn\(aqt 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 \fBcvs\fR history +file (see node `history file\(aq in the CVS manual) that you\(aqve abandoned your +checkout. +.SP +Use \fBcvs release\fR to avoid these problems. This +command checks that no uncommitted changes are +present; that you are executing it from immediately +above a \fBcvs\fR working directory; and that the repository +recorded for your files is the same as the repository +defined in the module database. +.SP +If all these conditions are true, \fBcvs release\fR +leaves a record of its execution (attesting to your +intentionally abandoning your checkout) in the \fBcvs\fR +history log. +.SP +.SH "release options" +.SP +The \fBrelease\fR command supports one command option: +.SP +.IP "" 0 +\fB-d\fR +.IP "" 2 +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. +.SP +\fBWARNING: The \fBrelease\fB command deletes +all directories and files recursively. This +has the very serious side-effect that any directory +created inside checked-out sources, and not added to +the repository (using the \fBadd\fB command; +see node `Adding files\(aq in the CVS manual) will be silently deleted\(emeven +if it is non-empty!\fR +.SP +.SH "release output" +.SP +Before \fBrelease\fR releases your sources it will +print a one-line message for any file that is not +up-to-date. +.SP +.IP "" 0 +\fBU \fIfile\fB\fR +.IP "" 2 +.IP "" 0 +\fBP \fIfile\fB\fR +.IP "" 2 +There exists a newer revision of this file in the +repository, and you have not modified your local copy +of the file (\fBU\fR and \fBP\fR mean the same thing). +.SP +.IP "" 0 +\fBA \fIfile\fB\fR +.IP "" 2 +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. +.SP +.IP "" 0 +\fBR \fIfile\fB\fR +.IP "" 2 +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. See `commit\(aq in the CVS manual. +.SP +.IP "" 0 +\fBM \fIfile\fB\fR +.IP "" 2 +The file is modified in your working directory. There +might also be a newer revision inside the repository. +.SP +.IP "" 0 +\fB? \fIfile\fB\fR +.IP "" 2 +\fIfile\fR is in your working directory, but does not +correspond to anything in the source repository, and is +not in the list of files for \fBcvs\fR to ignore (see the +description of the \fB-I\fR option, and +see node `cvsignore\(aq in the CVS manual). If you remove your working +sources, this file will be lost. +.SP +.SH "release examples" +.SP +Release the \fBtc\fR directory, and delete your local working copy +of the files. +.SP +.PD 0 +.SP +.IP "" 2 +$ cd \&.. # \fRYou must stand immediately above the\fR +.IP "" 2 + # \fRsources when you issue \fBcvs release\fR.\fR +.IP "" 2 +$ cvs release -d tc +.IP "" 2 +You have [0] altered files in this repository. +.IP "" 2 +Are you sure you want to release (and delete) directory \`tc\(aq: y +.IP "" 2 +$ + +.PD +.IP "" 0 +.SP +.SH "remove" +.SS "Remove files from active use" +.IX "remove (subcommand)" +.SP +.IP "\(bu" 2 +Synopsis: remove [-flR] [files...] +.IP "\(bu" 2 +Requires: repository, working directory. +.IP "\(bu" 2 +Changes: working directory. +.SP +The \fBremove\fR command is used to remove unwanted +files from active use. The user normally deletes the +files from the working directory prior to invocation +of the \fBremove\fR command. Only the working +directory is updated. Changes to the repository are +not made until the \fBcommit\fR command is run. +.SP +The \fBremove\fR command does not delete files from +from the repository. \fBcvs\fR keeps all historical +data in the repository so that it is possible to +reconstruct previous states of the projects under +revision control. +.SP +To undo \fBcvs\fR \fBremove\fR or to resurrect files +that were previously removed, see node `add\(aq in the CVS manual. +.SP +.SH "remove options" +.SP +These standard options are supported by \fBremove\fR +(see node `Common options\(aq in the CVS manual for a complete description of +them): +.SP +.IP "" 0 +\fB-l\fR +.IP "" 2 +Local; run only in current working directory. See `Recursive behavior\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-R\fR +.IP "" 2 +Process directories recursively. See `Recursive behavior\(aq in the CVS manual. +.SP +.SP +In addition, these options are also supported: +.SP +.IP "" 0 +\fB-f\fR +.IP "" 2 +Note that this is not the standard behavior of +the \fB-f\fR option as defined in `Common options\(aq in the CVS manual. +.SP +Delete files before removing them. +.SP +Entire directory hierarchies are easily removed +using \fB-f\fR, but take note that it is not as +easy to resurrect directory hierarchies as it is +to remove them. +.SP +.SP +.SH "remove examples" +.SP +.SS "Removing a file" +.SP +.PD 0 +.SP +.IP "" 2 +$ cvs remove remove.me +.IP "" 2 +cvs remove: file \`remove.me\(aq still in working directory +.IP "" 2 +cvs remove: 1 file exists; remove it first +.IP "" 2 +$ rm -f remove.me +.IP "" 2 +$ cvs remove remove.me +.IP "" 2 +cvs remove: scheduling \`remove.me\(aq for removal +.IP "" 2 +cvs remove: use \(aqcvs commit\(aq to remove this file permanently +.SP +.IP "" 2 +$ ls remove.it +.IP "" 2 +remove.it +.IP "" 2 +$ cvs remove -f remove.it +.IP "" 2 +cvs remove: scheduling \`remove.it\(aq for removal +.IP "" 2 +cvs remove: use \(aqcvs commit\(aq to remove this file permanently + +.PD +.IP "" 0 +.SP +.SS "Removing entire directories" +.SP +.PD 0 +.IP "" 2 +$ tree -d a +.IP "" 2 +a +.IP "" 2 +|-- CVS +.IP "" 2 +\`-- b +.IP "" 2 + \`-- CVS +.SP +.IP "" 2 +3 directories +.IP "" 2 +$ cvs remove -f a +.IP "" 2 +cvs remove: Removing a +.IP "" 2 +cvs remove: Removing a/b +.IP "" 2 +cvs remove: scheduling \`a/b/c\(aq for removal +.IP "" 2 +cvs remove: use \(aqcvs commit\(aq to remove this file permanently + +.PD +.IP "" 0 +.SP +.SH "update" +.SS "Bring work tree in sync with repository" +.IX "update (subcommand)" +.SP +.IP "\(bu" 2 +update [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag|-D date] [-W spec] files\&... +.IP "\(bu" 2 +Requires: repository, working directory. +.IP "\(bu" 2 +Changes: working directory. +.SP +After you\(aqve 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 \fBupdate\fR command from +within your working directory to reconcile your work +with any revisions applied to the source repository +since your last checkout or update. +.SP +.SH "update options" +.SP +These standard options are available with \fBupdate\fR +(see node `Common options\(aq in the CVS manual for a complete description of +them): +.SP +.IP "" 0 +\fB-D date\fR +.IP "" 2 +Use the most recent revision no later than \fIdate\fR. +This option is sticky, and implies \fB-P\fR. +See `Sticky tags\(aq in the CVS manual for more information on sticky tags/dates. +.SP +.IP "" 0 +\fB-f\fR +.IP "" 2 +Only useful with the \fB-D \fIdate\fB\fR or \fB-r +\fItag\fB\fR flags. If no matching revision is found, +retrieve the most recent revision (instead of ignoring +the file). +.SP +.IP "" 0 +\fB-k \fIkflag\fB\fR +.IP "" 2 +Process keywords according to \fIkflag\fR. See +`Keyword substitution\(aq in the CVS manual. +This option is sticky; future updates of +this file in this working directory will use the same +\fIkflag\fR. The \fBstatus\fR command can be viewed +to see the sticky options. See `Invoking CVS\(aq in the CVS manual for +more information on the \fBstatus\fR command. +.SP +.IP "" 0 +\fB-l\fR +.IP "" 2 +Local; run only in current working directory. See `Recursive behavior\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-P\fR +.IP "" 2 +Prune empty directories. See `Moving directories\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-p\fR +.IP "" 2 +Pipe files to the standard output. +.SP +.IP "" 0 +\fB-R\fR +.IP "" 2 +Update directories recursively (default). See `Recursive +behavior\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-r rev\fR +.IP "" 2 +Retrieve revision/tag \fIrev\fR. This option is sticky, +and implies \fB-P\fR. +See `Sticky tags\(aq in the CVS manual, for more information on sticky tags/dates. +.SP +These special options are also available with +\fBupdate\fR. +.SP +.IP "" 0 +\fB-A\fR +.IP "" 2 +Reset any sticky tags, dates, or \fB-k\fR options. +Does not reset sticky \fB-k\fR options on modified files. +See `Sticky tags\(aq in the CVS manual for more information on sticky tags/dates. +.SP +.IP "" 0 +\fB-C\fR +.IP "" 2 +Overwrite locally modified files with clean copies from +the repository (the modified file is saved in +\fB.#\fIfile\fB.\fIrevision\fB\fR, however). +.SP +.IP "" 0 +\fB-d\fR +.IP "" 2 +Create any directories that exist in the repository if +they\(aqre missing from the working directory. Normally, +\fBupdate\fR acts only on directories and files that +were already enrolled in your working directory. +.SP +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 \fB-d\fR will create +those directories, which may not be what you want. +.SP +.IP "" 0 +\fB-I \fIname\fB\fR +.IP "" 2 +Ignore files whose names match \fIname\fR (in your +working directory) during the update. You can specify +\fB-I\fR more than once on the command line to specify +several files to ignore. Use \fB-I !\fR to avoid +ignoring any files at all. See `cvsignore\(aq in the CVS manual for other +ways to make \fBcvs\fR ignore some files. +.SP +.IP "" 0 +\fB-W\fIspec\fB\fR +.IP "" 2 +Specify file names that should be filtered during +update. You can use this option repeatedly. +.SP +\fIspec\fR can be a file name pattern of the same type +that you can specify in the \fB.cvswrappers\fR +file. See `Wrappers\(aq in the CVS manual. +.SP +.IP "" 0 +\fB-j\fIrevision\fB\fR +.IP "" 2 +With two \fB-j\fR options, merge changes from the +revision specified with the first \fB-j\fR option to +the revision specified with the second \fBj\fR option, +into the working directory. +.SP +With one \fB-j\fR option, merge changes from the +ancestor revision to the revision specified with the +\fB-j\fR 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 \fB-j\fR option. +.SP +Note that using a single \fB-j \fItagname\fB\fR option rather than +\fB-j \fIbranchname\fB\fR to merge changes from a branch will +often not remove files which were removed on the branch. +See `Merging adds and removals\(aq in the CVS manual for more information. +.SP +In addition, each \fB-j\fR 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: +\fB-j\fISymbolic_Tag\fB:\fIDate_Specifier\fB\fR. +.SP +See `Branching and merging\(aq in the CVS manual. +.SP +.SP +.SH "update output" +.SP +\fBupdate\fR and \fBcheckout\fR keep you informed of +their progress by printing a line for each file, preceded +by one character indicating the status of the file: +.SP +.IP "" 0 +\fBU \fIfile\fB\fR +.IP "" 2 +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 working directory, and for files +that you haven\(aqt changed but are not the most recent +versions available in the repository. +.SP +.IP "" 0 +\fBP \fIfile\fB\fR +.IP "" 2 +Like \fBU\fR, but the \fBcvs\fR server sends a patch instead of an entire +file. This accomplishes the same thing as \fBU\fR using less bandwidth. +.SP +.IP "" 0 +\fBA \fIfile\fB\fR +.IP "" 2 +The file has been added to your private copy of the +sources, and will be added to the source repository +when you run \fBcommit\fR on the file. This is a +reminder to you that the file needs to be committed. +.SP +.IP "" 0 +\fBR \fIfile\fB\fR +.IP "" 2 +The file has been removed from your private copy of the +sources, and will be removed from the source repository +when you run \fBcommit\fR on the file. This is a +reminder to you that the file needs to be committed. +.SP +.IP "" 0 +\fBM \fIfile\fB\fR +.IP "" 2 +The file is modified in your working directory. +.SP +\fBM\fR can indicate one of two states for a file +you\(aqre 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. +.SP +\fBcvs\fR will print some messages if it merges your work, +and a backup copy of your working file (as it looked +before you ran \fBupdate\fR) will be made. The exact +name of that file is printed while \fBupdate\fR runs. +.SP +.IP "" 0 +\fBC \fIfile\fB\fR +.IP "" 2 +.IX "\&.# files" +.IX "__ files (VMS)" +A conflict was detected while trying to merge your +changes to \fIfile\fR with changes from the source +repository. \fIfile\fR (the copy in your working +directory) is now the result of attempting to merge +the two revisions; an unmodified copy of your file +is also in your working directory, with the name +\fB.#\fIfile\fB.\fIrevision\fB\fR where \fIrevision\fR +is the revision that your modified file started +from. Resolve the conflict as described in +`Conflicts example\(aq in the CVS manual. +(Note that some systems automatically purge +files that begin with \fB.#\fR 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.) Under \fBvms\fR, the file name starts with +\fB__\fR rather than \fB.#\fR. +.SP +.IP "" 0 +\fB? \fIfile\fB\fR +.IP "" 2 +\fIfile\fR is in your working directory, but does not +correspond to anything in the source repository, and is +not in the list of files for \fBcvs\fR to ignore (see the +description of the \fB-I\fR option, and +see node `cvsignore\(aq in the CVS manual). +.SH "AUTHORS" +.TP +Dick Grune +Original author of the +.B cvs +shell script version posted to +.B comp.sources.unix +in the volume6 release of December, 1986. +Credited with much of the +.B cvs +conflict resolution algorithms. +.TP +Brian Berliner +Coder and designer of the +.B cvs +program itself in April, 1989, based on the original work done by Dick. +.TP +Jeff Polk +Helped Brian with the design of the +.B cvs +module and vendor branch support and author of the +.BR checkin ( 1 ) +shell script (the ancestor of \fBcvs import\fP). +.TP +Larry Jones, Derek R. Price, and Mark D. Baushke +Have helped maintain +.B cvs +for many years. +.TP +And many others too numerous to mention here. +.SH "SEE ALSO" +The most comprehensive manual for CVS is +Version Management with CVS by Per Cederqvist et al. Depending on +your system, you may be able to get it with the +.B info CVS +command or it may be available as cvs.pdf (Portable Document Format), +cvs.ps (PostScript), cvs.texinfo (Texinfo source), or cvs.html. +.SP +For CVS updates, more information on documentation, software related +to CVS, development of CVS, and more, see: +.in +1i +.SP +.PD 0 +.IP "" 4 +.B http://cvs.nongnu.org +.in -1i +.SP +.BR ci ( 1 ), +.BR co ( 1 ), +.BR cvs ( 5 ), +.BR cvsbug ( 8 ), +.BR diff ( 1 ), +.BR grep ( 1 ), +.BR patch ( 1 ), +.BR rcs ( 1 ), +.BR rcsdiff ( 1 ), +.BR rcsmerge ( 1 ), +.BR rlog ( 1 ). diff --git a/contrib/cvs/doc/cvs.man.footer b/contrib/cvs/doc/cvs.man.footer new file mode 100644 index 0000000..fe3f6b4 --- /dev/null +++ b/contrib/cvs/doc/cvs.man.footer @@ -0,0 +1,58 @@ +.SH "AUTHORS" +.TP +Dick Grune +Original author of the +.B cvs +shell script version posted to +.B comp.sources.unix +in the volume6 release of December, 1986. +Credited with much of the +.B cvs +conflict resolution algorithms. +.TP +Brian Berliner +Coder and designer of the +.B cvs +program itself in April, 1989, based on the original work done by Dick. +.TP +Jeff Polk +Helped Brian with the design of the +.B cvs +module and vendor branch support and author of the +.BR checkin ( 1 ) +shell script (the ancestor of \fBcvs import\fP). +.TP +Larry Jones, Derek R. Price, and Mark D. Baushke +Have helped maintain +.B cvs +for many years. +.TP +And many others too numerous to mention here. +.SH "SEE ALSO" +The most comprehensive manual for CVS is +Version Management with CVS by Per Cederqvist et al. Depending on +your system, you may be able to get it with the +.B info CVS +command or it may be available as cvs.pdf (Portable Document Format), +cvs.ps (PostScript), cvs.texinfo (Texinfo source), or cvs.html. +.SP +For CVS updates, more information on documentation, software related +to CVS, development of CVS, and more, see: +.in +1i +.SP +.PD 0 +.IP "" 4 +.B http://cvs.nongnu.org +.in -1i +.SP +.BR ci ( 1 ), +.BR co ( 1 ), +.BR cvs ( 5 ), +.BR cvsbug ( 8 ), +.BR diff ( 1 ), +.BR grep ( 1 ), +.BR patch ( 1 ), +.BR rcs ( 1 ), +.BR rcsdiff ( 1 ), +.BR rcsmerge ( 1 ), +.BR rlog ( 1 ). diff --git a/contrib/cvs/doc/cvs.man.header b/contrib/cvs/doc/cvs.man.header new file mode 100644 index 0000000..cbc4f7d --- /dev/null +++ b/contrib/cvs/doc/cvs.man.header @@ -0,0 +1,61 @@ +.\" This is the man page for CVS. It is auto-generated from the +.\" cvs.man.header, cvs.texinfo, & cvs.man.footer files. Please make changes +.\" there. A full copyright & license notice may also be found in cvs.texinfo. +.\" +.\" Man page autogeneration, including this header file, is +.\" Copyright 2004-2005 The Free Software Foundation, Inc., +.\" Derek R. Price, & Ximbiot <http://ximbiot.com>. +.\" +.\" This documentation 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 documentation 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 documentation; if not, write to the Free Software +.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +.de Id +.ds Rv \\$3 +.ds Dt \\$4 +.. +.TH CVS 1 "\*(Dt" +.\" Full space in nroff; half space in troff +.de SP +.if n .sp +.if t .sp .5 +.. +.\" quoted command +.de ` +.RB ` "\|\\$1\|" '\\$2 +.. +.SH "NAME" +cvs \- Concurrent Versions System +.SH "SYNOPSIS" +.TP +\fBcvs\fP [ \fIcvs_options\fP ] +.I cvs_command +[ +.I command_options +] [ +.I command_args +] +.SH "NOTE" +.IX "revision control system" "\fLcvs\fR" +.IX cvs "" "\fLcvs\fP \- concurrent versions system" +.IX "concurrent versions system \- \fLcvs\fP" +.IX "release control system" "cvs command" "" "\fLcvs\fP \- concurrent versions system" +.IX "source control system" "cvs command" "" "\fLcvs\fP \- concurrent versions system" +.IX revisions "cvs command" "" "\fLcvs\fP \- source control" +This manpage is a summary of some of the features of +\fBcvs\fP. It is auto-generated from an appendix of the CVS manual. +For more in-depth documentation, please consult the +Cederqvist manual (via the +.B info CVS +command or otherwise, +as described in the SEE ALSO section of this manpage). Cross-references +in this man page refer to nodes in the same. diff --git a/contrib/cvs/doc/cvs.texinfo b/contrib/cvs/doc/cvs.texinfo new file mode 100644 index 0000000..6b1840a --- /dev/null +++ b/contrib/cvs/doc/cvs.texinfo @@ -0,0 +1,14892 @@ +\input texinfo @c -*-texinfo-*- +@comment Documentation for CVS. +@setfilename cvs.info +@macro copyleftnotice +@noindent +Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, + 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 + Free Software Foundation, Inc. + +@multitable @columnfractions .12 .88 +@item Portions +@item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, + 2006, 2007 Derek R. Price, +@item @tab Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007 + Ximbiot @url{http://ximbiot.com}, +@item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB, +@item @tab and Copyright @copyright{} others. +@end multitable + +@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 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 +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 this permission notice may be stated in a translation +approved by the Free Software Foundation. +@end macro + +@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 2, 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. + +@c See ../README for A4 vs. US letter size. +@c When we provided A4 postscript, and people tried to +@c print it on US letter, the usual complaint was that the +@c page numbers would get cut off. +@c If one prints US letter on A4, reportedly there is +@c some extra space at the top and/or bottom, and the side +@c margins are a bit narrow, but no text is lost. +@c +@c See +@c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html +@c for more on paper sizes. Insuring that margins are +@c big enough to print on either A4 or US letter does +@c indeed seem to be the usual approach (RFC2346). + +@c This document seems to get overfull hboxes with some +@c frequency (probably because the tendency is to +@c sanity-check it with "make info" and run TeX less +@c often). The big ugly boxes just seem to add insult +@c to injury, and I'm not aware of them helping to fix +@c the overfull hboxes at all. +@finalout + +@include version.texi +@settitle CVS---Concurrent Versions System v@value{VERSION} +@setchapternewpage odd + +@c -- TODO list: +@c -- Fix all lines that match "^@c -- " +@c -- Also places marked with FIXME should be manual +@c problems (as opposed to FIXCVS for CVS problems). + +@c @splitrcskeyword{} is used to avoid keyword expansion. It is replaced by +@c @asis when generating info and dvi, and by <i></i> in the generated html, +@c such that keywords are not expanded in the generated html. +@ifnothtml +@macro splitrcskeyword {arg} +@asis{}\arg\ +@end macro +@end ifnothtml + +@ifhtml +@macro splitrcskeyword {arg} +@i{}\arg\ +@end macro +@end ifhtml + +@dircategory GNU Packages +@direntry +* CVS: (cvs). Concurrent Versions System +@end direntry +@dircategory Individual utilities +@direntry +* cvs: (cvs)CVS commands. Concurrent Versions System +@end direntry + +@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{VERSION} +@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 +@copyleftnotice +@end titlepage + +@summarycontents + +@contents + +@comment ================================================================ +@comment The real text starts here +@comment ================================================================ + +@ifnottex +@c --------------------------------------------------------------------- +@node Top +@top + +This info manual describes how to use and administer +@sc{cvs} version @value{VERSION}. +@end ifnottex + +@ifinfo +@copyleftnotice +@end ifinfo + +@c This menu is pretty long. Not sure how easily that +@c can be fixed (no brilliant ideas right away)... +@menu +* Overview:: An introduction to CVS +* Repository:: Where all your sources are stored +* Starting a new project:: Starting a project with CVS +* Revisions:: Numeric and symbolic names for revisions +* Branching and merging:: Diverging/rejoining branches of development +* Recursive behavior:: CVS descends directories +* Adding and removing:: Adding/removing/renaming files/directories +* History browsing:: Viewing the history of files in various ways + +CVS and the Real World. +----------------------- +* Binary files:: CVS can handle binary files +* Multiple developers:: How CVS helps a group of developers +* Revision management:: Policy questions for revision management +* Keyword substitution:: CVS can include the revision inside the file +* Tracking sources:: Tracking third-party sources +* Builds:: Issues related to CVS and builds +* Special Files:: Devices, links and other non-regular files + +References. +----------- +* CVS commands:: CVS commands share some things +* Invoking CVS:: Quick reference to CVS commands +* Administrative files:: Reference manual for the Administrative files +* Environment variables:: All environment variables which affect CVS +* Compatibility:: Upgrading CVS versions +* Troubleshooting:: Some tips when nothing works +* Credits:: Some of the contributors to this manual +* BUGS:: Dealing with bugs in CVS or this manual +* Index:: Index +@end menu + +@c --------------------------------------------------------------------- +@node Overview +@chapter Overview +@cindex Overview + +This chapter is for people who have never used +@sc{cvs}, and perhaps have never used version control +software before. + +If you are already familiar with @sc{cvs} and are just +trying to learn a particular feature or remember a +certain command, you can probably skip everything here. + +@menu +* What is CVS?:: What you can do with @sc{cvs} +* What is CVS not?:: Problems @sc{cvs} doesn't try to solve +* A sample session:: A tour of basic @sc{cvs} usage +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node What is CVS? +@section 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 +two people never modify the same file 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 the newsgroup +@code{comp.sources.unix} in the volume 6 +release of July, 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} in a variety of ways, including +free download from the Internet. For more information +on downloading @sc{cvs} and other @sc{cvs} topics, see: + +@example +@url{http://cvs.nongnu.org/} +@end example + +@cindex Mailing list +@cindex List, mailing list +@cindex Newsgroups +There is a mailing list, known as @email{info-cvs@@nongnu.org}, +devoted to @sc{cvs}. To subscribe or +unsubscribe +write to +@email{info-cvs-request@@nongnu.org}. +If you prefer a Usenet group, there is a one-way mirror (posts to the email +list are usually sent to the news group, but not vice versa) of +@email{info-cvs@@nongnu.org} at @url{news:gnu.cvs.help}. The right +Usenet group for posts is @url{news:comp.software.config-mgmt} which is for +@sc{cvs} discussions (along with other configuration +management systems). In the future, it might be +possible to create a +@code{comp.software.config-mgmt.cvs}, but probably only +if there is sufficient @sc{cvs} traffic on +@url{news:comp.software.config-mgmt}. +@c Other random data is that the tale was very +@c skeptical of comp.software.config-mgmt.cvs when the +@c subject came up around 1995 or so (for one +@c thing, because creating it would be a "reorg" which +@c would need to take a more comprehensive look at the +@c whole comp.software.config-mgmt.* hierarchy). + +You can also subscribe to the @email{bug-cvs@@nongnu.org} mailing list, +described in more detail in @ref{BUGS}. To subscribe +send mail to @email{bug-cvs-request@@nongnu.org}. There is a two-way +Usenet mirror (posts to the Usenet group are usually sent to the email list and +vice versa) of @email{bug-cvs@@nongnu.org} named @url{news:gnu.cvs.bug}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node What is CVS not? +@section What is CVS not? +@cindex What is CVS not? + +@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. + +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. + +Of course, you should place the tools created to +support such a build system (scripts, @file{Makefile}s, +etc.) under @sc{cvs}. + +Figuring out what files need to be rebuilt when +something changes is, again, something to be handled +outside the scope of @sc{cvs}. One traditional +approach is to use @code{make} for building, and use +some automated tool for generating the dependencies which +@code{make} uses. + +See @ref{Builds}, for more information on doing builds +in conjunction with @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} does not have change control + +Change control refers to a number of things. First of +all it can mean @dfn{bug-tracking}, that is being able +to keep a database of reported bugs and the status of +each one (Is it fixed? In what release? Has the bug +submitter agreed that it is fixed?). For interfacing +@sc{cvs} to an external bug-tracking system, see the +@file{rcsinfo} and @file{verifymsg} files +(@pxref{Administrative files}). + +Another aspect of change control is keeping track of +the fact that changes to several files were in fact +changed together as one logical change. If you check +in several files in a single @code{cvs commit} +operation, @sc{cvs} then forgets that those files were +checked in together, and the fact that they have the +same log message is the only thing tying them +together. Keeping a @sc{gnu} style @file{ChangeLog} +can help somewhat. +@c FIXME: should have an xref to a section which talks +@c more about keeping ChangeLog's with CVS, but that +@c section hasn't been written yet. + +Another aspect of change control, in some systems, is +the ability to keep track of the status of each +change. Some changes have been written by a developer, +others have been reviewed by a second developer, and so +on. Generally, the way to do this with @sc{cvs} is to +generate a diff (using @code{cvs diff} or @code{diff}) +and email it to someone who can then apply it using the +@code{patch} utility. This is very flexible, but +depends on mechanisms outside @sc{cvs} to make sure +nothing falls through the cracks. + +@item @sc{cvs} is not an automated testing program + +It should be possible to enforce mandatory use of a +test suite using the @code{commitinfo} file. I haven't +heard a lot about projects trying to do that or whether +there are subtle gotchas, however. + +@item @sc{cvs} does not have a built-in process model + +Some systems provide ways to ensure that changes or +releases go through various steps, with various +approvals as needed. Generally, one can accomplish +this with @sc{cvs} but it might be a little more work. +In some cases you'll want to use the @file{commitinfo}, +@file{loginfo}, @file{rcsinfo}, or @file{verifymsg} +files, to require that certain steps be performed +before cvs will allow a checkin. Also consider whether +features such as branches and tags can be used to +perform tasks such as doing work in a development tree +and then merging certain changes over to a stable tree +only once they have been proven. +@end table + +@c --------------------------------------------------------------------- +@node A sample session +@section 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) + +@c I think an example is a pretty good way to start. But +@c somewhere in here, maybe after the sample session, +@c we need something which is kind of +@c a "roadmap" which is more directed at sketching out +@c the functionality of CVS and pointing people to +@c various other parts of the manual. As it stands now +@c people who read in order get dumped right into all +@c manner of hair regarding remote repositories, +@c creating a repository, etc. +@c +@c The following was in the old Basic concepts node. I don't +@c know how good a job it does at introducing modules, +@c or whether they need to be introduced so soon, but +@c something of this sort might go into some +@c introductory material somewhere. +@ignore +@cindex Modules (intro) +The repository contains directories and files, in an +arbitrary tree. The @dfn{modules} feature can be used +to group together a set of directories or files into a +single entity (@pxref{modules}). A typical usage is to +define one module per project. +@end ignore + +As a way of introducing @sc{cvs}, we'll go through a +typical work-session using @sc{cvs}. The first thing +to understand is that @sc{cvs} stores all files in a +centralized @dfn{repository} (@pxref{Repository}); this +section assumes that a repository is set up. +@c I'm not sure that the sentence concerning the +@c repository quite tells the user what they need to +@c know at this point. Might need to expand on "centralized" +@c slightly (maybe not here, maybe further down in the example?) + +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 +@subsection 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 +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 +@subsection Committing your changes +@cindex Committing changes to files +@cindex Log message entry + +When you have checked that the compiler is still compilable you decide +to make a new version of @file{backend.c}. This will +store your new @file{backend.c} in the repository and +make it available to anyone else who is using that same +repository. + +@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. + +@cindex CVSEDITOR, environment variable +@cindex EDITOR, environment variable +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 there is a default +which will vary with your operating system, for example +@code{vi} for unix or @code{notepad} for Windows +NT/95. + +@cindex VISUAL, environment variable +In addition, @sc{cvs} checks the @code{$VISUAL} environment +variable. Opinions vary on whether this behavior is desirable and +whether future releases of @sc{cvs} should check @code{$VISUAL} or +ignore it. You will be OK either way if you make sure that +@code{$VISUAL} is either unset or set to the same thing as +@code{$EDITOR}. + +@c This probably should go into some new node +@c containing detailed info on the editor, rather than +@c the intro. In fact, perhaps some of the stuff with +@c CVSEDITOR and -m and so on should too. +When @sc{cvs} starts the editor, it includes a list of +files which are modified. For the @sc{cvs} client, +this list is based on comparing the modification time +of the file against the modification time that the file +had when it was last gotten or updated. Therefore, if +a file's modification time has changed but its contents +have not, it will show up as modified. The simplest +way to handle this is simply not to worry about it---if +you proceed with the commit @sc{cvs} will detect that +the contents are not modified and treat it as an +unmodified file. The next @code{update} will clue +@sc{cvs} in to the fact that the file is unmodified, +and it will reset its stored timestamp so that the file +will not show up in future editor sessions. +@c FIXCVS: Might be nice if "commit" and other commands +@c would reset that timestamp too, but currently commit +@c doesn't. +@c FIXME: Need to talk more about the process of +@c prompting for the log message. Like show an example +@c of what it pops up in the editor, for example. Also +@c a discussion of how to get the "a)bort, c)ontinue, +@c e)dit" prompt and what to do with it. Might also +@c work in the suggestion that if you want a diff, you +@c should make it before running commit (someone +@c suggested that the diff pop up in the editor. I'm +@c not sure that is better than telling people to run +@c "cvs diff" first if that is what they want, but if +@c we want to tell people that, the manual possibly +@c should say it). + +If you want to avoid +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 +@subsection 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) directory `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 +@subsection 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. +@c FIXME: we haven't yet defined the term "check in". + +@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) directory `tc': y +@end example + +@c --------------------------------------------------------------------- +@node Repository +@chapter The Repository +@cindex Repository (intro) +@cindex Repository, example +@cindex Layout of repository +@cindex Typical repository +@cindex /usr/local/cvsroot, as example repository +@cindex cvsroot + +The @sc{cvs} @dfn{repository} stores a complete copy of +all the files and directories which are under version +control. + +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 into a +@dfn{working directory}, 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 repository then contains the changes +which you have made, as well as recording exactly what +you changed, when you changed it, and other such +information. Note that the repository is not a +subdirectory of the working directory, or vice versa; +they should be in separate locations. +@c Need some example, e.g. repository +@c /usr/local/cvsroot; working directory +@c /home/joe/sources. But this node is too long +@c as it is; need a little reorganization... + +@cindex :local:, setting up +@sc{cvs} can access a repository by a variety of +means. It might be on the local computer, or it might +be on a computer across the room or across the world. +To distinguish various ways to access a repository, the +repository name can start with an @dfn{access method}. +For example, the access method @code{:local:} means to +access a repository directory, so the repository +@code{:local:/usr/local/cvsroot} means that the +repository is in @file{/usr/local/cvsroot} on the +computer running @sc{cvs}. For information on other +access methods, see @ref{Remote repositories}. + +@c Can se say this more concisely? Like by passing +@c more of the buck to the Remote repositories node? +If the access method is omitted, then if the repository +starts with @samp{/}, then @code{:local:} is +assumed. If it does not start with @samp{/} then either +@code{:ext:} or @code{:server:} is assumed. For +example, if you have a local repository in +@file{/usr/local/cvsroot}, you can use +@code{/usr/local/cvsroot} instead of +@code{:local:/usr/local/cvsroot}. But if (under +Windows NT, for example) your local repository is +@file{c:\src\cvsroot}, then you must specify the access +method, as in @code{:local:c:/src/cvsroot}. + +@c This might appear to go in Repository storage, but +@c actually it is describing something which is quite +@c user-visible, when you do a "cvs co CVSROOT". This +@c isn't necessary the perfect place for that, though. +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 +* Specifying a repository:: Telling CVS where your repository is +* Repository storage:: The structure of the repository +* Working directory storage:: The structure of working directories +* Intro administrative files:: Defining modules +* Multiple repositories:: Multiple repositories +* Creating a repository:: Creating a repository +* Backing up:: Backing up a repository +* Moving a repository:: Moving a repository +* Remote repositories:: Accessing repositories on remote machines +* Read-only access:: Granting read-only access to the repository +* Server temporary directory:: The server creates temporary directories +@end menu + +@node Specifying a repository +@section Telling CVS where your repository is + +There are several 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 + +@cindex .profile, setting CVSROOT in +@cindex .cshrc, setting CVSROOT in +@cindex .tcshrc, setting CVSROOT in +@cindex .bashrc, setting CVSROOT in +@cindex CVSROOT, environment variable + 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}, @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 + +@cindex Root file, in CVS directory +@cindex CVS/Root file + 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. If +@code{-d} option differs from @file{CVS/Root}, the +former is used. Of course, for proper operation they +should be two ways of referring to the same repository. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Repository storage +@section How data is stored in the repository +@cindex Repository, how data is stored + +For most purposes it isn't important @emph{how} +@sc{cvs} stores information in the repository. In +fact, the format has changed in the past, and is likely +to change in the future. Since in almost all cases one +accesses the repository via @sc{cvs} commands, such +changes need not be disruptive. + +However, in some cases it may be necessary to +understand how @sc{cvs} stores data in the repository, +for example you might need to track down @sc{cvs} locks +(@pxref{Concurrency}) or you might need to deal with +the file permissions appropriate for the repository. + +@menu +* Repository files:: What files are stored in the repository +* File permissions:: File permissions +* Windows permissions:: Issues specific to Windows +* Attic:: Some files are stored in the Attic +* CVS in repository:: Additional information in CVS directory +* Locks:: CVS locks control concurrent accesses +* CVSROOT storage:: A few things about CVSROOT are different +@end menu + +@node Repository files +@subsection Where files are stored within the repository + +@c @cindex Filenames, legal +@c @cindex Legal filenames +@c Somewhere we need to say something about legitimate +@c characters in filenames in working directory and +@c repository. Not "/" (not even on non-unix). And +@c here is a specific set of issues: +@c Files starting with a - are handled inconsistently. They can not +@c be added to a repository with an add command, because it they are +@c interpreted as a switch. They can appear in a repository if they are +@c part of a tree that is imported. They can not be removed from the tree +@c once they are there. +@c Note that "--" *is* supported (as a +@c consequence of using GNU getopt). Should document +@c this somewhere ("Common options"?). The other usual technique, +@c "./-foo", isn't as effective, at least for "cvs add" +@c which doesn't support pathnames containing "/". + +The overall structure of the repository is a directory +tree corresponding to the directories in the working +directory. For example, supposing the repository is in + +@example +/usr/local/cvsroot +@end example + +@noindent +here is a possible directory tree (showing only the +directories): + +@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 + +With the directories are @dfn{history files} for each file +under version control. The name of the history file is +the name of the corresponding file with @samp{,v} +appended to the end. Here is what the repository for +the @file{yoyodyne/tc} directory might look like: +@c FIXME: Should also mention CVS (CVSREP) +@c FIXME? Should we introduce Attic with an xref to +@c Attic? Not sure whether that is a good idea or not. +@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 +@c The first sentence, about what history files +@c contain, is kind of redundant with our intro to what the +@c repository does in node Repository.... +The history files 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. The history files are +known as @dfn{RCS files}, because the first program to +store files in that format was a version control system +known as @sc{rcs}. For a full +description of the file format, see the @code{man} page +@cite{rcsfile(5)}, distributed with @sc{rcs}, or the +file @file{doc/RCSFILES} in the @sc{cvs} source +distribution. This +file format has become very common---many systems other +than @sc{cvs} or @sc{rcs} can at least import history +files in this format. +@c FIXME: Think about including documentation for this +@c rather than citing it? In the long run, getting +@c this to be a standard (not sure if we can cope with +@c a standards process as formal as IEEE/ANSI/ISO/etc, +@c though...) is the way to go, so maybe citing is +@c better. + +The @sc{rcs} files used in @sc{cvs} differ in a few +ways from the standard format. The biggest difference +is magic branches; for more information see @ref{Magic +branch numbers}. Also in @sc{cvs} the valid tag names +are a subset of what @sc{rcs} accepts; for @sc{cvs}'s +rules see @ref{Tags}. + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node File permissions +@subsection File permissions +@c -- Move this to @node Creating a repository or similar +@cindex Security, file permissions in repository +@cindex File permissions, general +@cindex Permissions, general +@c FIXME: we need to somehow reflect "permissions in +@c repository" versus "permissions in working +@c directory" in the index entries. +@cindex Group, UNIX file permissions, in repository +@cindex Read-only files, in repository +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. +(On some systems, you also need to set the set-group-ID-on-execution bit +on the repository directories (see chmod(1)) so that newly-created files +and directories get the group-ID of the parent directory rather than +that of the current process.) + +@c See also comment in commitinfo node regarding cases +@c which are really awkward with unix groups. + +This means that you can only control access to files on +a per-directory basis. + +Note that users must also have write access to check +out files, because @sc{cvs} needs to create lock files +(@pxref{Concurrency}). You can use LockDir in CVSROOT/config +to put the lock files somewhere other than in the repository +if you want to allow read-only access to some directories +(@pxref{config}). + +@c CVS seems to use CVSUMASK in picking permissions for +@c val-tags, but maybe we should say more about this. +@c Like val-tags gets created by someone who doesn't +@c have CVSUMASK set right? +@cindex CVSROOT/val-tags file, and read-only access to projects +@cindex val-tags file, and read-only access to projects +Also note that users must have write access to the +@file{CVSROOT/val-tags} file. @sc{cvs} uses it to keep +track of what tags are valid tag names (it is sometimes +updated when tags are used, as well as when they are +created). + +Each @sc{rcs} file will be owned by the user who last +checked it in. This has little significance; what +really matters is who owns the directories. + +@cindex CVSUMASK, environment variable +@cindex Umask, for repository files +@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. If you set the @code{CVSUMASK} +environment variable, that will control the file +permissions which @sc{cvs} uses in creating directories +and/or files in the repository. @code{CVSUMASK} does +not affect the file permissions in the working +directory; such files have the permissions which are +typical for newly created files, except that sometimes +@sc{cvs} creates them read-only (see the sections on +watches, @ref{Setting a watch}; -r, @ref{Global +options}; or @code{CVSREAD}, @ref{Environment variables}). +@c FIXME: Need more discussion of which +@c group should own the file in the repository. +@c Include a somewhat detailed example of the usual +@c case where CVSUMASK is 007, the developers are all +@c in a group, and that group owns stuff in the +@c repository. Need to talk about group ownership of +@c newly-created directories/files (on some unices, +@c such as SunOS4, setting the setgid bit on the +@c directories will make files inherit the directory's +@c group. On other unices, your mileage may vary. I +@c can't remember what POSIX says about this, if +@c anything). + +Note that using the client/server @sc{cvs} +(@pxref{Remote repositories}), there is no good way to +set @code{CVSUMASK}; the setting on the client machine +has no effect. If you are connecting with @code{rsh}, you +can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as +described in the documentation for your operating +system. This behavior might change in future versions +of @sc{cvs}; do not rely on the setting of +@code{CVSUMASK} on the client having no effect. +@c FIXME: need to explain what a umask is or cite +@c someplace which does. +@c +@c There is also a larger (largely separate) issue +@c about the meaning of CVSUMASK in a non-unix context. +@c For example, whether there is +@c an equivalent which fits better into other +@c protection schemes like POSIX.6, VMS, &c. +@c +@c FIXME: Need one place which discusses this +@c read-only files thing. Why would one use -r or +@c CVSREAD? Why would one use watches? How do they +@c interact? +@c +@c FIXME: We need to state +@c whether using CVSUMASK removes the need for manually +@c fixing permissions (in fact, if we are going to mention +@c manually fixing permission, we better document a lot +@c better just what we mean by "fix"). + +Using pserver, you will generally need stricter +permissions on the @sc{cvsroot} directory and +directories above it in the tree; see @ref{Password +authentication security}. + +@cindex Setuid +@cindex Setgid +@cindex Security, setuid +@cindex Installed images (VMS) +Some operating systems have features which allow a +particular program to run with the ability to perform +operations which the caller of the program could not. +For example, the set user ID (setuid) or set group ID +(setgid) features of unix or the installed image +feature of VMS. @sc{cvs} was not written to use such +features and therefore attempting to install @sc{cvs} in +this fashion will provide protection against only +accidental lapses; anyone who is trying to circumvent +the measure will be able to do so, and depending on how +you have set it up may gain access to more than just +@sc{cvs}. You may wish to instead consider pserver. It +shares some of the same attributes, in terms of +possibly providing a false sense of security or opening +security holes wider than the ones you are trying to +fix, so read the documentation on pserver security +carefully if you are considering this option +(@ref{Password authentication security}). + +@node Windows permissions +@subsection File Permission issues specific to Windows +@cindex Windows, and permissions +@cindex File permissions, Windows-specific +@cindex Permissions, Windows-specific + +Some file permission issues are specific to Windows +operating systems (Windows 95, Windows NT, and +presumably future operating systems in this family. +Some of the following might apply to OS/2 but I'm not +sure). + +If you are using local @sc{cvs} and the repository is on a +networked file system which is served by the Samba SMB +server, some people have reported problems with +permissions. Enabling WRITE=YES in the samba +configuration is said to fix/workaround it. +Disclaimer: I haven't investigated enough to know the +implications of enabling that option, nor do I know +whether there is something which @sc{cvs} could be doing +differently in order to avoid the problem. If you find +something out, please let us know as described in +@ref{BUGS}. + +@node Attic +@subsection The attic +@cindex Attic + +You will notice that sometimes @sc{cvs} stores an +@sc{rcs} file in the @code{Attic}. For example, if the +@sc{cvsroot} is @file{/usr/local/cvsroot} and we are +talking about the file @file{backend.c} in the +directory @file{yoyodyne/tc}, then the file normally +would be in + +@example +/usr/local/cvsroot/yoyodyne/tc/backend.c,v +@end example + +@noindent +but if it goes in the attic, it would be in + +@example +/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v +@end example + +@noindent +@cindex Dead state +instead. It should not matter from a user point of +view whether a file is in the attic; @sc{cvs} keeps +track of this and looks in the attic when it needs to. +But in case you want to know, the rule is that the RCS +file is stored in the attic if and only if the head +revision on the trunk has state @code{dead}. A +@code{dead} state means that file has been removed, or +never added, for that revision. For example, if you +add a file on a branch, it will have a trunk revision +in @code{dead} state, and a branch revision in a +non-@code{dead} state. +@c Probably should have some more concrete examples +@c here, or somewhere (not sure exactly how we should +@c arrange the discussion of the dead state, versus +@c discussion of the attic). + +@node CVS in repository +@subsection The CVS directory in the repository +@cindex CVS directory, in repository + +The @file{CVS} directory in each repository directory +contains information such as file attributes (in a file +called @file{CVS/fileattr}. In the +future additional files may be added to this directory, +so implementations should silently ignore additional +files. + +This behavior is implemented only by @sc{cvs} 1.7 and +later; for details see @ref{Watches Compatibility}. + +The format of the @file{fileattr} file is a series of entries +of the following form (where @samp{@{} and @samp{@}} +means the text between the braces can be repeated zero +or more times): + +@var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval} + @{; @var{attrname} = @var{attrval}@} <linefeed> + +@var{ent-type} is @samp{F} for a file, in which case the entry specifies the +attributes for that file. + +@var{ent-type} is @samp{D}, +and @var{filename} empty, to specify default attributes +to be used for newly added files. + +Other @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older +will delete them any time it writes file attributes. +@sc{cvs} 1.10 and later will preserve them. + +Note that the order of the lines is not significant; +a program writing the fileattr file may +rearrange them at its convenience. + +There is currently no way of quoting tabs or line feeds in the +filename, @samp{=} in @var{attrname}, +@samp{;} in @var{attrval}, etc. Note: some implementations also +don't handle a NUL character in any of the fields, but +implementations are encouraged to allow it. + +By convention, @var{attrname} starting with @samp{_} is for an attribute given +special meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes +(or will be, once implementations start supporting user-defined attributes). + +Built-in attributes: + +@table @code +@item _watched +Present means the file is watched and should be checked out +read-only. + +@item _watchers +Users with watches for this file. Value is +@var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @} +where @var{watcher} is a username, and @var{type} +is zero or more of edit,unedit,commit separated by +@samp{+} (that is, nothing if none; there is no "none" or "all" keyword). + +@item _editors +Users editing this file. Value is +@var{editor} > @var{val} @{ , @var{editor} > @var{val} @} +where @var{editor} is a username, and @var{val} is +@var{time}+@var{hostname}+@var{pathname}, where +@var{time} is when the @code{cvs edit} command (or +equivalent) happened, +and @var{hostname} and @var{pathname} are for the working directory. +@end table + +Example: + +@c FIXME: sanity.sh should contain a similar test case +@c so we can compare this example from something from +@c Real Life(TM). See cvsclient.texi (under Notify) for more +@c discussion of the date format of _editors. +@example +Ffile1 _watched=;_watchers=joe>edit,mary>commit +Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs +D _watched= +@end example + +@noindent +means that the file @file{file1} should be checked out +read-only. Furthermore, joe is watching for edits and +mary is watching for commits. The file @file{file2} +should be checked out read-only; sue started editing it +on 8 Jan 1975 in the directory @file{/home/sue/cvs} on +the machine @code{workstn1}. Future files which are +added should be checked out read-only. To represent +this example here, we have shown a space after +@samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact +there must be a single tab character there and no spaces. + +@node Locks +@subsection CVS locks in the repository + +@cindex #cvs.rfl, technical details +@cindex #cvs.wfl, technical details +@cindex #cvs.lock, technical details +@cindex Locks, cvs, technical details +For an introduction to @sc{cvs} locks focusing on +user-visible behavior, see @ref{Concurrency}. The +following section is aimed at people who are writing +tools which want to access a @sc{cvs} repository without +interfering with other tools accessing the same +repository. If you find yourself confused by concepts +described here, like @dfn{read lock}, @dfn{write lock}, +and @dfn{deadlock}, you might consult the literature on +operating systems or databases. + +@cindex #cvs.tfl +Any file in the repository with a name starting +with @file{#cvs.rfl.} is a read lock. Any file in +the repository with a name starting with +@file{#cvs.wfl} is a write lock. Old versions of @sc{cvs} +(before @sc{cvs} 1.5) also created files with names starting +with @file{#cvs.tfl}, but they are not discussed here. +The directory @file{#cvs.lock} serves as a master +lock. That is, one must obtain this lock first before +creating any of the other locks. + +To obtain a read lock, first create the @file{#cvs.lock} +directory. This operation must be atomic (which should +be true for creating a directory under most operating +systems). If it fails because the directory already +existed, wait for a while and try again. After +obtaining the @file{#cvs.lock} lock, create a file +whose name is @file{#cvs.rfl.} followed by information +of your choice (for example, hostname and process +identification number). Then remove the +@file{#cvs.lock} directory to release the master lock. +Then proceed with reading the repository. When you are +done, remove the @file{#cvs.rfl} file to release the +read lock. + +To obtain a write lock, first create the +@file{#cvs.lock} directory, as with read locks. Then +check that there are no files whose names start with +@file{#cvs.rfl.}. If there are, remove +@file{#cvs.lock}, wait for a while, and try again. If +there are no readers, then create a file whose name is +@file{#cvs.wfl} followed by information of your choice +(for example, hostname and process identification +number). Hang on to the @file{#cvs.lock} lock. Proceed +with writing the repository. When you are done, first +remove the @file{#cvs.wfl} file and then the +@file{#cvs.lock} directory. Note that unlike the +@file{#cvs.rfl} file, the @file{#cvs.wfl} file is just +informational; it has no effect on the locking operation +beyond what is provided by holding on to the +@file{#cvs.lock} lock itself. + +Note that each lock (write lock or read lock) only locks +a single directory in the repository, including +@file{Attic} and @file{CVS} but not including +subdirectories which represent other directories under +version control. To lock an entire tree, you need to +lock each directory (note that if you fail to obtain +any lock you need, you must release the whole tree +before waiting and trying again, to avoid deadlocks). + +Note also that @sc{cvs} expects write locks to control +access to individual @file{foo,v} files. @sc{rcs} has +a scheme where the @file{,foo,} file serves as a lock, +but @sc{cvs} does not implement it and so taking out a +@sc{cvs} write lock is recommended. See the comments at +rcs_internal_lockfile in the @sc{cvs} source code for +further discussion/rationale. + +@node CVSROOT storage +@subsection How files are stored in the CVSROOT directory +@cindex CVSROOT, storage of files + +The @file{$CVSROOT/CVSROOT} directory contains the +various administrative files. In some ways this +directory is just like any other directory in the +repository; it contains @sc{rcs} files whose names end +in @samp{,v}, and many of the @sc{cvs} commands operate +on it the same way. However, there are a few +differences. + +For each administrative file, in addition to the +@sc{rcs} file, there is also a checked out copy of the +file. For example, there is an @sc{rcs} file +@file{loginfo,v} and a file @file{loginfo} which +contains the latest revision contained in +@file{loginfo,v}. When you check in an administrative +file, @sc{cvs} should print + +@example +cvs commit: Rebuilding administrative file database +@end example + +@noindent +and update the checked out copy in +@file{$CVSROOT/CVSROOT}. If it does not, there is +something wrong (@pxref{BUGS}). To add your own files +to the files to be updated in this fashion, you can add +them to the @file{checkoutlist} administrative file +(@pxref{checkoutlist}). + +@cindex modules.db +@cindex modules.pag +@cindex modules.dir +By default, the @file{modules} file behaves as +described above. If the modules file is very large, +storing it as a flat text file may make looking up +modules slow (I'm not sure whether this is as much of a +concern now as when @sc{cvs} first evolved this +feature; I haven't seen benchmarks). Therefore, by +making appropriate edits to the @sc{cvs} source code +one can store the modules file in a database which +implements the @code{ndbm} interface, such as Berkeley +db or GDBM. If this option is in use, then the modules +database will be stored in the files @file{modules.db}, +@file{modules.pag}, and/or @file{modules.dir}. +@c I think fileattr also will use the database stuff. +@c Anything else? + +For information on the meaning of the various +administrative files, see @ref{Administrative files}. + +@node Working directory storage +@section How data is stored in the working directory + +@c FIXME: Somewhere we should discuss timestamps (test +@c case "stamps" in sanity.sh). But not here. Maybe +@c in some kind of "working directory" chapter which +@c would encompass the "Builds" one? But I'm not sure +@c whether that is a good organization (is it based on +@c what the user wants to do?). + +@cindex CVS directory, in working directory +While we are discussing @sc{cvs} internals which may +become visible from time to time, we might as well talk +about what @sc{cvs} puts in the @file{CVS} directories +in the working directories. As with the repository, +@sc{cvs} handles this information and one can usually +access it via @sc{cvs} commands. But in some cases it +may be useful to look at it, and other programs, such +as the @code{jCVS} graphical user interface or the +@code{VC} package for emacs, may need to look at it. +Such programs should follow the recommendations in this +section if they hope to be able to work with other +programs which use those files, including future +versions of the programs just mentioned and the +command-line @sc{cvs} client. + +The @file{CVS} directory contains several files. +Programs which are reading this directory should +silently ignore files which are in the directory but +which are not documented here, to allow for future +expansion. + +The files are stored according to the text file +convention for the system in question. This means that +working directories are not portable between systems +with differing conventions for storing text files. +This is intentional, on the theory that the files being +managed by @sc{cvs} probably will not be portable between +such systems either. + +@table @file +@item Root +This file contains the current @sc{cvs} root, as +described in @ref{Specifying a repository}. + +@cindex Repository file, in CVS directory +@cindex CVS/Repository file +@item Repository +This file contains the directory within the repository +which the current directory corresponds with. It can +be either an absolute pathname or a relative pathname; +@sc{cvs} has had the ability to read either format +since at least version 1.3 or so. The relative +pathname is relative to the root, and is the more +sensible approach, but the absolute pathname is quite +common and implementations should accept either. For +example, after the command + +@example +cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc +@end example + +@noindent +@file{Root} will contain + +@example +:local:/usr/local/cvsroot +@end example + +@noindent +and @file{Repository} will contain either + +@example +/usr/local/cvsroot/yoyodyne/tc +@end example + +@noindent +or + +@example +yoyodyne/tc +@end example + +If the particular working directory does not correspond +to a directory in the repository, then @file{Repository} +should contain @file{CVSROOT/Emptydir}. +@cindex Emptydir, in CVSROOT directory +@cindex CVSROOT/Emptydir directory + +@cindex Entries file, in CVS directory +@cindex CVS/Entries file +@item Entries +This file lists the files and directories in the +working directory. +The first character of each line indicates what sort of +line it is. If the character is unrecognized, programs +reading the file should silently skip that line, to +allow for future expansion. + +If the first character is @samp{/}, then the format is: + +@example +/@var{name}/@var{revision}/@var{timestamp}[+@var{conflict}]/@var{options}/@var{tagdate} +@end example + +@noindent +where @samp{[} and @samp{]} are not part of the entry, +but instead indicate that the @samp{+} and conflict +marker are optional. @var{name} is the name of the +file within the directory. @var{revision} is the +revision that the file in the working derives from, or +@samp{0} for an added file, or @samp{-} followed by a +revision for a removed file. @var{timestamp} is the +timestamp of the file at the time that @sc{cvs} created +it; if the timestamp differs with the actual +modification time of the file it means the file has +been modified. It is stored in +the format used by the ISO C asctime() function (for +example, @samp{Sun Apr 7 01:29:26 1996}). One may +write a string which is not in that format, for +example, @samp{Result of merge}, to indicate that the +file should always be considered to be modified. This +is not a special case; to see whether a file is +modified a program should take the timestamp of the file +and simply do a string compare with @var{timestamp}. +If there was a conflict, @var{conflict} can be set to +the modification time of the file after the file has been +written with conflict markers (@pxref{Conflicts example}). +Thus if @var{conflict} is subsequently the same as the actual +modification time of the file it means that the user +has obviously not resolved the conflict. @var{options} +contains sticky options (for example @samp{-kb} for a +binary file). @var{tagdate} contains @samp{T} followed +by a tag name, or @samp{D} for a date, followed by a +sticky tag or date. Note that if @var{timestamp} +contains a pair of timestamps separated by a space, +rather than a single timestamp, you are dealing with a +version of @sc{cvs} earlier than @sc{cvs} 1.5 (not +documented here). + +The timezone on the timestamp in CVS/Entries (local or +universal) should be the same as the operating system +stores for the timestamp of the file itself. For +example, on Unix the file's timestamp is in universal +time (UT), so the timestamp in CVS/Entries should be +too. On @sc{vms}, the file's timestamp is in local +time, so @sc{cvs} on @sc{vms} should use local time. +This rule is so that files do not appear to be modified +merely because the timezone changed (for example, to or +from summer time). +@c See comments and calls to gmtime() and friends in +@c src/vers_ts.c (function time_stamp). + +If the first character of a line in @file{Entries} is +@samp{D}, then it indicates a subdirectory. @samp{D} +on a line all by itself indicates that the program +which wrote the @file{Entries} file does record +subdirectories (therefore, if there is such a line and +no other lines beginning with @samp{D}, one knows there +are no subdirectories). Otherwise, the line looks +like: + +@example +D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4} +@end example + +@noindent +where @var{name} is the name of the subdirectory, and +all the @var{filler} fields should be silently ignored, +for future expansion. Programs which modify +@code{Entries} files should preserve these fields. + +The lines in the @file{Entries} file can be in any order. + +@cindex Entries.Log file, in CVS directory +@cindex CVS/Entries.Log file +@item Entries.Log +This file does not record any information beyond that +in @file{Entries}, but it does provide a way to update +the information without having to rewrite the entire +@file{Entries} file, including the ability to preserve +the information even if the program writing +@file{Entries} and @file{Entries.Log} abruptly aborts. +Programs which are reading the @file{Entries} file +should also check for @file{Entries.Log}. If the latter +exists, they should read @file{Entries} and then apply +the changes mentioned in @file{Entries.Log}. After +applying the changes, the recommended practice is to +rewrite @file{Entries} and then delete @file{Entries.Log}. +The format of a line in @file{Entries.Log} is a single +character command followed by a space followed by a +line in the format specified for a line in +@file{Entries}. The single character command is +@samp{A} to indicate that the entry is being added, +@samp{R} to indicate that the entry is being removed, +or any other character to indicate that the entire line +in @file{Entries.Log} should be silently ignored (for +future expansion). If the second character of the line +in @file{Entries.Log} is not a space, then it was +written by an older version of @sc{cvs} (not documented +here). + +Programs which are writing rather than reading can +safely ignore @file{Entries.Log} if they so choose. + +@cindex Entries.Backup file, in CVS directory +@cindex CVS/Entries.Backup file +@item Entries.Backup +This is a temporary file. Recommended usage is to +write a new entries file to @file{Entries.Backup}, and +then to rename it (atomically, where possible) to @file{Entries}. + +@cindex Entries.Static file, in CVS directory +@cindex CVS/Entries.Static file +@item Entries.Static +The only relevant thing about this file is whether it +exists or not. If it exists, then it means that only +part of a directory was gotten and @sc{cvs} will +not create additional files in that directory. To +clear it, use the @code{update} command with the +@samp{-d} option, which will get the additional files +and remove @file{Entries.Static}. +@c FIXME: This needs to be better documented, in places +@c other than Working Directory Storage. +@c FIXCVS: The fact that this setting exists needs to +@c be more visible to the user. For example "cvs +@c status foo", in the case where the file would be +@c gotten except for Entries.Static, might say +@c something to distinguish this from other cases. +@c One thing that periodically gets suggested is to +@c have "cvs update" print something when it skips +@c files due to Entries.Static, but IMHO that kind of +@c noise pretty much makes the Entries.Static feature +@c useless. + +@cindex Tag file, in CVS directory +@cindex CVS/Tag file +@cindex Sticky tags/dates, per-directory +@cindex Per-directory sticky tags/dates +@item Tag +This file contains per-directory sticky tags or dates. +The first character is @samp{T} for a branch tag, +@samp{N} for a non-branch tag, or @samp{D} for a date, +or another character to mean the file should be +silently ignored, for future expansion. This character +is followed by the tag or date. Note that +per-directory sticky tags or dates are used for things +like applying to files which are newly added; they +might not be the same as the sticky tags or dates on +individual files. For general information on sticky +tags and dates, see @ref{Sticky tags}. +@c FIXME: This needs to be much better documented, +@c preferably not in the context of "working directory +@c storage". +@c FIXME: The Sticky tags node needs to discuss, or xref to +@c someplace which discusses, per-directory sticky +@c tags and the distinction with per-file sticky tags. + +@cindex Notify file, in CVS directory +@cindex CVS/Notify file +@item Notify +This file stores notifications (for example, for +@code{edit} or @code{unedit}) which have not yet been +sent to the server. Its format is not yet documented +here. + +@cindex Notify.tmp file, in CVS directory +@cindex CVS/Notify.tmp file +@item Notify.tmp +This file is to @file{Notify} as @file{Entries.Backup} +is to @file{Entries}. That is, to write @file{Notify}, +first write the new contents to @file{Notify.tmp} and +then (atomically where possible), rename it to +@file{Notify}. + +@cindex Base directory, in CVS directory +@cindex CVS/Base directory +@item Base +If watches are in use, then an @code{edit} command +stores the original copy of the file in the @file{Base} +directory. This allows the @code{unedit} command to +operate even if it is unable to communicate with the +server. + +@cindex Baserev file, in CVS directory +@cindex CVS/Baserev file +@item Baserev +The file lists the revision for each of the files in +the @file{Base} directory. The format is: + +@example +B@var{name}/@var{rev}/@var{expansion} +@end example + +@noindent +where @var{expansion} should be ignored, to allow for +future expansion. + +@cindex Baserev.tmp file, in CVS directory +@cindex CVS/Baserev.tmp file +@item Baserev.tmp +This file is to @file{Baserev} as @file{Entries.Backup} +is to @file{Entries}. That is, to write @file{Baserev}, +first write the new contents to @file{Baserev.tmp} and +then (atomically where possible), rename it to +@file{Baserev}. + +@cindex Template file, in CVS directory +@cindex CVS/Template file +@item Template +This file contains the template specified by the +@file{rcsinfo} file (@pxref{rcsinfo}). It is only used +by the client; the non-client/server @sc{cvs} consults +@file{rcsinfo} directly. +@end table + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Intro administrative files +@section The administrative files +@cindex Administrative files (intro) +@cindex Modules file +@cindex CVSROOT, module name +@cindex Defining modules (intro) + +@c FIXME: this node should be reorganized into "general +@c information about admin files" and put the "editing +@c admin files" stuff up front rather than jumping into +@c the details of modules right away. Then the +@c Administrative files node can go away, the information +@c on each admin file distributed to a place appropriate +@c to its function, and this node can contain a table +@c listing each file and a @ref to its detailed description. + +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 four 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. + +@c FIXME: subsection without node is bogus +@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. If and when this happens, you can correct +the problem by temporarily copying a corrected administrative file +directly into the @code{$CVSROOT/CVSROOT} repository directory, +then committing the same correction via a checkout of the @file{CVSROOT} +module. It is important that the correction also be made via the +checked out copy, or the next checkout and commit to the +<code>CVSROOT</code> module will overwrite the correction that was +copied directly into the repository, possibly breaking things in such +a way as to prevent commits again. +@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 directory) by simply +allowing @sc{cvs} to use the repository that was used +to check out the working directory +(@pxref{Specifying a repository}). + +The big advantage of having multiple repositories is +that they can reside on different servers. With @sc{cvs} +version 1.10, a single command cannot recurse into +directories from different repositories. With development +versions of @sc{cvs}, you can check out code from multiple +servers into your working directory. @sc{cvs} will +recurse and handle all the details of making +connections to as many server machines as necessary to +perform the requested command. Here is an example of +how to set up a working directory: + +@example +cvs -d server1:/cvs co dir1 +cd dir1 +cvs -d server2:/root co sdir +cvs update +@end example + +The @code{cvs co} commands set up the working +directory, and then the @code{cvs update} command will +contact server2, to update the dir1/sdir subdirectory, +and server1, to update everything else. + +@c FIXME: Does the FAQ have more about this? I have a +@c dim recollection, but I'm too lazy to check right now. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Creating a repository +@section Creating a repository + +@cindex Repository, setting up +@cindex Creating a repository +@cindex Setting up a repository + +This section describes how to set up a @sc{cvs} repository for any +sort of access method. After completing the setup described in this +section, you should be able to access your @sc{cvs} repository immediately +via the local access method and several remote access methods. For +more information on setting up remote access to the repository you create +in this section, please read the section on @xref{Remote repositories}. + +To set up a @sc{cvs} repository, first choose the +machine and disk on which you want to store the +revision history of the source files. CPU and memory +requirements are modest, so most machines should be +adequate. For details see @ref{Server requirements}. +@c Possible that we should be providing a quick rule of +@c thumb, like the 32M memory for the server. That +@c might increase the number of people who are happy +@c with the answer, without following the xref. + +To estimate disk space +requirements, if you are importing RCS files from +another system, the size of those files is the +approximate initial size of your repository, or if you +are starting without any version history, a rule of +thumb is to allow for the server approximately three +times the size of the code to be under @sc{cvs} for the +repository (you will eventually outgrow this, but not +for a while). On the machines on which the developers +will be working, you'll want disk space for +approximately one working directory for each developer +(either the entire tree or a portion of it, depending +on what each developer uses). + +The repository should be accessible +(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. It is not +possible to use @sc{cvs} to read from a repository +which one only has read access to; @sc{cvs} needs to be +able to create lock files (@pxref{Concurrency}). + +@cindex init (subcommand) +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 Backing up +@section Backing up a repository +@cindex Repository, backing up +@cindex Backing up, repository + +There is nothing particularly magical about the files +in the repository; for the most part it is possible to +back them up just like any other files. However, there +are a few issues to consider. + +@cindex Locks, cvs, and backups +@cindex #cvs.rfl, and backups +The first is that to be paranoid, one should either not +use @sc{cvs} during the backup, or have the backup +program lock @sc{cvs} while doing the backup. To not +use @sc{cvs}, you might forbid logins to machines which +can access the repository, turn off your @sc{cvs} +server, or similar mechanisms. The details would +depend on your operating system and how you have +@sc{cvs} set up. To lock @sc{cvs}, you would create +@file{#cvs.rfl} locks in each repository directory. +See @ref{Concurrency}, for more on @sc{cvs} locks. +Having said all this, if you just back up without any +of these precautions, the results are unlikely to be +particularly dire. Restoring from backup, the +repository might be in an inconsistent state, but this +would not be particularly hard to fix manually. + +When you restore a repository from backup, assuming +that changes in the repository were made after the time +of the backup, working directories which were not +affected by the failure may refer to revisions which no +longer exist in the repository. Trying to run @sc{cvs} +in such directories will typically produce an error +message. One way to get those changes back into the +repository is as follows: + +@itemize @bullet +@item +Get a new working directory. + +@item +Copy the files from the working directory from before +the failure over to the new working directory (do not +copy the contents of the @file{CVS} directories, of +course). + +@item +Working in the new working directory, use commands such +as @code{cvs update} and @code{cvs diff} to figure out +what has changed, and then when you are ready, commit +the changes into the repository. +@end itemize + +@node Moving a repository +@section Moving a repository +@cindex Repository, moving +@cindex Moving a repository +@cindex Copying a repository + +Just as backing up the files in the repository is +pretty much like backing up any other files, if you +need to move a repository from one place to another it +is also pretty much like just moving any other +collection of files. + +The main thing to consider is that working directories +point to the repository. The simplest way to deal with +a moved repository is to just get a fresh working +directory after the move. Of course, you'll want to +make sure that the old working directory had been +checked in before the move, or you figured out some +other way to make sure that you don't lose any +changes. If you really do want to reuse the existing +working directory, it should be possible with manual +surgery on the @file{CVS/Repository} files. You can +see @ref{Working directory storage}, for information on +the @file{CVS/Repository} and @file{CVS/Root} files, but +unless you are sure you want to bother, it probably +isn't worth it. +@c FIXME: Surgery on CVS/Repository should be avoided +@c by making RELATIVE_REPOS the default. +@c FIXME-maybe: might want some documented way to +@c change the CVS/Root files in some particular tree. +@c But then again, I don't know, maybe just having +@c people do this in perl/shell/&c isn't so bad... + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Remote repositories +@section Remote repositories +@cindex Repositories, remote +@cindex Remote repositories +@cindex Client/Server Operation +@cindex Server, CVS +@cindex Remote repositories, port specification +@cindex Repositories, remote, port specification +@cindex Client/Server Operation, port specification +@cindex pserver (client/server connection method), port specification +@cindex kserver (client/server connection method), port specification +@cindex gserver (client/server connection method), port specification +@cindex port, specifying for remote repositories + + Your working copy of the sources can be on a +different machine than the repository. Using @sc{cvs} +in this manner is known as @dfn{client/server} +operation. You run @sc{cvs} on a machine which can +mount your working directory, known as the +@dfn{client}, and tell it to communicate to a machine +which can mount the repository, known as the +@dfn{server}. Generally, using a remote +repository is just like using a local one, except that +the format of the repository name is: + +@example +[:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository +@end example + +Specifying a password in the repository name is not recommended during +checkout, since this will cause @sc{cvs} to store a cleartext copy of the +password in each created directory. @code{cvs login} first instead +(@pxref{Password authentication client}). + +The details of exactly what needs to be set up depend +on how you are connecting to the server. + +If @var{method} is not specified, and the repository +name contains @samp{:}, then the default is @code{ext} +or @code{server}, depending on your platform; both are +described in @ref{Connecting via rsh}. +@c Should we try to explain which platforms are which? +@c Platforms like unix and VMS, which only allow +@c privileged programs to bind to sockets <1024 lose on +@c :server: +@c Platforms like Mac and VMS, whose rsh program is +@c unusable or nonexistent, lose on :ext: +@c Platforms like OS/2 and NT probably could plausibly +@c default either way (modulo -b troubles). + +@c FIXME: We need to have a better way of explaining +@c what method to use. This presentation totally +@c obscures the fact that :ext: and CVS_RSH is the way to +@c use SSH, for example. Plus it incorrectly implies +@c that you need an @code{rsh} binary on the client to use +@c :server:. +@c Also note that rsh not pserver is the right choice if you want +@c users to be able to create their own repositories +@c (because of the --allow-root related issues). +@menu +* Server requirements:: Memory and other resources for servers +* Connecting via rsh:: Using the @code{rsh} program to connect +* Password authenticated:: Direct connections using passwords +* GSSAPI authenticated:: Direct connections using GSSAPI +* Kerberos authenticated:: Direct connections with Kerberos +* Connecting via fork:: Using a forked @code{cvs server} to connect +@end menu + +@node Server requirements +@subsection Server requirements + +The quick answer to what sort of machine is suitable as +a server is that requirements are modest---a server +with 32M of memory or even less can handle a fairly +large source tree with a fair amount of activity. +@c Say something about CPU speed too? I'm even less sure +@c what to say on that subject... + +The real answer, of course, is more complicated. +Estimating the known areas of large memory consumption +should be sufficient to estimate memory requirements. +There are two such areas documented here; other memory +consumption should be small by comparison (if you find +that is not the case, let us know, as described in +@ref{BUGS}, so we can update this documentation). + +The first area of big memory consumption is large +checkouts, when using the @sc{cvs} server. The server +consists of two processes for each client that it is +serving. Memory consumption on the child process +should remain fairly small. Memory consumption on the +parent process, particularly if the network connection +to the client is slow, can be expected to grow to +slightly more than the size of the sources in a single +directory, or two megabytes, whichever is larger. +@c "two megabytes" of course is SERVER_HI_WATER. But +@c we don't mention that here because we are +@c documenting the default configuration of CVS. If it +@c is a "standard" thing to change that value, it +@c should be some kind of run-time configuration. +@c +@c See cvsclient.texi for more on the design decision +@c to not have locks in place while waiting for the +@c client, which is what results in memory consumption +@c as high as this. + +Multiplying the size of each @sc{cvs} server by the +number of servers which you expect to have active at +one time should give an idea of memory requirements for +the server. For the most part, the memory consumed by +the parent process probably can be swap space rather +than physical memory. +@c Has anyone verified that notion about swap space? +@c I say it based pretty much on guessing that the +@c ->text of the struct buffer_data only gets accessed +@c in a first in, first out fashion, but I haven't +@c looked very closely. + +@c What about disk usage in /tmp on the server? I think that +@c it can be substantial, but I haven't looked at this +@c again and tried to figure it out ("cvs import" is +@c probably the worst case...). + +The second area of large memory consumption is +@code{diff}, when checking in large files. This is +required even for binary files. The rule of thumb is +to allow about ten times the size of the largest file +you will want to check in, although five times may be +adequate. For example, if you want to check in a file +which is 10 megabytes, you should have 100 megabytes of +memory on the machine doing the checkin (the server +machine for client/server, or the machine running +@sc{cvs} for non-client/server). This can be swap +space rather than physical memory. Because the memory +is only required briefly, there is no particular need +to allow memory for more than one such checkin at a +time. +@c The 5-10 times rule of thumb is from Paul Eggert for +@c GNU diff. I don't think it is in the GNU diff +@c manual or anyplace like that. +@c +@c Probably we could be saying more about +@c non-client/server CVS. +@c I would guess for non-client/server CVS in an NFS +@c environment the biggest issues are the network and +@c the NFS server. + +Resource consumption for the client is even more +modest---any machine with enough capacity to run the +operating system in question should have little +trouble. +@c Is that true? I think the client still wants to +@c (bogusly) store entire files in memory at times. + +For information on disk space requirements, see +@ref{Creating a repository}. + +@node Connecting via rsh +@subsection Connecting with rsh or ssh + +@cindex ssh +@sc{cvs} may use the @samp{ssh} protocol to perform +these operations, so the remote user host needs to have +a either an agent like @code{ssh-agent} to hold +credentials or a @file{.shosts} file which grants +access to the local user. Note that the program that +@sc{cvs} uses for this purpose may be specified using +the @file{--with-ssh} flag to configure. + +@cindex rsh +@sc{cvs} uses the @samp{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. Note that the program that @sc{cvs} uses for this +purpose may be specified using the @file{--with-rsh} +flag to configure. + +For example, suppose you are the user @samp{mozart} on +the local machine @samp{toe.example.com}, and the +server machine is @samp{faun.example.org}. On +faun, put the following line into the file +@file{.rhosts} in @samp{bach}'s home directory: + +@example +toe.example.com mozart +@end example + +@noindent +Then test that @samp{rsh} is working with + +@example +rsh -l bach faun.example.org 'echo $PATH' +@end example + +@noindent +To test that @samp{ssh} is working use + +@example +ssh -l bach faun.example.org 'echo $PATH' +@end example + +@cindex CVS_SERVER, environment variable +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}. +@c FIXME: there should be a way to specify the +@c program in CVSROOT, not CVS_SERVER, so that one can use +@c different ones for different roots. e.g. ":server;cvs=cvs-1.6:" +@c instead of ":server:". + +There is no need to edit @file{inetd.conf} or start a +@sc{cvs} server daemon. + +@cindex :server:, setting up +@cindex :ext:, setting up +@cindex :extssh:, setting up +@cindex Kerberos, using kerberized rsh +@cindex SSH (rsh replacement) +@cindex rsh replacements (Kerberized, SSH, &c) +There are three access methods that you use in @code{CVSROOT} +for rsh or ssh. @code{:server:} specifies an internal rsh +client, which is supported only by some @sc{cvs} ports. +@code{:extssh:} specifies an external ssh program. By +default this is @code{ssh} (unless otherwise specified +by the @file{--with-ssh} flag to configure) but you may set the +@code{CVS_SSH} environment variable to invoke another +program or wrapper script. +@code{:ext:} specifies an external rsh program. By +default this is @code{rsh} (unless otherwise specified +by the @file{--with-rsh} flag to configure) but you may set the +@code{CVS_RSH} environment variable to invoke another +program which can access the remote server (for +example, @code{remsh} on HP-UX 9 because @code{rsh} is +something different). It must be a program which can +transmit data to and from the server without modifying +it; for example the Windows NT @code{rsh} is not +suitable since it by default translates between CRLF +and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b} +to @code{rsh} to get around this, but since this could +potentially cause problems for programs other than the +standard @code{rsh}, it may change in the future. If +you set @code{CVS_RSH} to @code{SSH} or some other rsh +replacement, the instructions in the rest of this +section concerning @file{.rhosts} and so on are likely +to be inapplicable; consult the documentation for your rsh +replacement. +@c FIXME: there should be a way to specify the +@c program in CVSROOT, not CVS_RSH, so that one can use +@c different ones for different roots. e.g. +@c ":ext;CVS_RSH=remsh:" instead of ":ext:". +@c See also the comment in src/client.c for rationale +@c concerning "rsh" being the default and never +@c "remsh". + +Continuing our example, supposing you want to access +the module @file{foo} in the repository +@file{/usr/local/cvsroot/}, on machine +@file{faun.example.org}, you are ready to go: + +@example +cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo +@end example + +@noindent +(The @file{bach@@} can be omitted if the username is +the same on both the local and remote hosts.) + +@c Should we mention "rsh host echo hi" and "rsh host +@c cat" (the latter followed by typing text and ^D) +@c as troubleshooting techniques? Probably yes +@c (people tend to have trouble setting this up), +@c but this kind of thing can be hard to spell out. + +@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 + +First of all, you probably want to tighten the +permissions on the @file{$CVSROOT} and +@file{$CVSROOT/CVSROOT} directories. See @ref{Password +authentication security}, for more details. + +@cindex pserver (subcommand) +@cindex Remote repositories, port specification +@cindex Repositories, remote, port specification +@cindex Client/Server Operation, port specification +@cindex pserver (client/server connection method), port specification +@cindex kserver (client/server connection method), port specification +@cindex gserver (client/server connection method), port specification +@cindex port, specifying for remote repositories +@cindex Password server, setting up +@cindex Authenticating server, setting up +@cindex inetd, configuring for pserver +@cindex xinetd, configuring for pserver +@c FIXME: this isn't quite right regarding port +@c numbers; CVS looks up "cvspserver" in +@c /etc/services (on unix, but what about non-unix?). +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. This can also be specified in the CVSROOT variable +(@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT +environment variable (@pxref{Environment variables}). + + 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 -f --allow-root=/usr/cvsroot pserver +@end example + +@noindent +(You could also use the +@samp{-T} option to specify a temporary directory.) + +The @samp{--allow-root} option specifies the allowable +@sc{cvsroot} directory. Clients which attempt to use a +different @sc{cvsroot} directory will not be allowed to +connect. If there is more than one @sc{cvsroot} +directory which you want to allow, repeat the option. +(Unfortunately, many versions of @code{inetd} have very small +limits on the number of arguments and/or the total length +of the command. The usual solution to this problem is +to have @code{inetd} run a shell script which then invokes +@sc{cvs} with the necessary arguments.) + + 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 + +@noindent +and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}. + +If your system uses @code{xinetd} instead of @code{inetd}, +the procedure is slightly different. +Create a file called @file{/etc/xinetd.d/cvspserver} containing the following: + +@example +service cvspserver +@{ + port = 2401 + socket_type = stream + protocol = tcp + wait = no + user = root + passenv = PATH + server = /usr/local/bin/cvs + server_args = -f --allow-root=/usr/cvsroot pserver +@} +@end example + +@noindent +(If @code{cvspserver} is defined in @file{/etc/services}, you can omit +the @code{port} line.) + + Once the above is taken care of, restart your +@code{inetd}, or do whatever is necessary to force it +to reread its initialization files. + +If you are having trouble setting this up, see +@ref{Connection}. + +@cindex CVS passwd file +@cindex passwd (admin file) +Because the client stores and transmits passwords in +cleartext (almost---see @ref{Password authentication +security}, for details), a separate @sc{cvs} password +file is generally 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}). It uses a colon-separated +format, similar to @file{/etc/passwd} on Unix systems, +except that it has fewer fields: @sc{cvs} username, +optional password, and an optional system username for +@sc{cvs} to run as if authentication succeeds. Here is +an example @file{passwd} file with five entries: + +@example +anonymous: +bach:ULtgRLXo7NRxs +spwang:1sOp854gDF3DY +melissa:tGX1fS8sun6rY:pubcvs +qproj:XR4EZcEs0szik:pubcvs +@end example + +@noindent +(The passwords are encrypted according to the standard +Unix @code{crypt()} function, so it is possible to +paste in passwords directly from regular Unix +@file{/etc/passwd} files.) + +The first line in the example will grant access to any +@sc{cvs} client attempting to authenticate as user +@code{anonymous}, no matter what password they use, +including an empty password. (This is typical for +sites granting anonymous read-only access; for +information on how to do the "read-only" part, see +@ref{Read-only access}.) + +The second and third lines will grant access to +@code{bach} and @code{spwang} if they supply their +respective plaintext passwords. + +@cindex User aliases +The fourth line will grant access to @code{melissa}, if +she supplies the correct password, but her @sc{cvs} +operations will actually run on the server side under +the system user @code{pubcvs}. Thus, there need not be +any system user named @code{melissa}, but there +@emph{must} be one named @code{pubcvs}. + +The fifth line shows that system user identities can be +shared: any client who successfully authenticates as +@code{qproj} will actually run as @code{pubcvs}, just +as @code{melissa} does. That way you could create a +single, shared system user for each project in your +repository, and give each developer their own line in +the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs} +username on each line would be different, but the +system username would be the same. The reason to have +different @sc{cvs} usernames is that @sc{cvs} will log their +actions under those names: when @code{melissa} commits +a change to a project, the checkin is recorded in the +project's history under the name @code{melissa}, not +@code{pubcvs}. And the reason to have them share a +system username is so that you can arrange permissions +in the relevant area of the repository such that only +that account has write-permission there. + +If the system-user field is present, all +password-authenticated @sc{cvs} commands run as that +user; if no system user is specified, @sc{cvs} simply +takes the @sc{cvs} username as the system username and +runs commands as that user. In either case, if there +is no such user on the system, then the @sc{cvs} +operation will fail (regardless of whether the client +supplied a valid password). + +The password and system-user fields can both be omitted +(and if the system-user field is omitted, then also +omit the colon that would have separated it from the +encrypted password). For example, this would be a +valid @file{$CVSROOT/CVSROOT/passwd} file: + +@example +anonymous::pubcvs +fish:rKa5jzULzmhOo:kfogel +sussman:1sOp854gDF3DY +@end example + +@noindent +When the password field is omitted or empty, then the +client's authentication attempt will succeed with any +password, including the empty string. However, the +colon after the @sc{cvs} username is always necessary, +even if the password is empty. + +@sc{cvs} can also fall back to use system authentication. +When authenticating a password, the server first checks +for the user in the @file{$CVSROOT/CVSROOT/passwd} +file. If it finds the user, it will use that entry for +authentication as described above. But if it does not +find the user, or if the @sc{cvs} @file{passwd} file +does not exist, then the server can try to authenticate +the username and password using the operating system's +user-lookup routines (this "fallback" behavior can be +disabled by setting @code{SystemAuth=no} in the +@sc{cvs} @file{config} file, @pxref{config}). Be +aware, however, that falling back to system +authentication might be a security risk: @sc{cvs} +operations would then be authenticated with that user's +regular login password, and the password flies across +the network in plaintext. See @ref{Password +authentication security} for more on this. + +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. + +Unlike many of the files in @file{$CVSROOT/CVSROOT}, it +is normal to edit the @file{passwd} file in-place, +rather than via @sc{cvs}. This is because of the +possible security risks of having the @file{passwd} +file checked out to people's working copies. If you do +want to include the @file{passwd} file in checkouts of +@file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}. + +@c We might also suggest using the @code{htpasswd} command +@c from freely available web servers as well, but that +@c would open up a can of worms in that the users next +@c questions are likely to be "where do I get it?" and +@c "how do I use it?" +@c Also note that htpasswd, at least the version I had, +@c likes to clobber the third field. + +@node Password authentication client +@subsubsection Using the client with password authentication +@cindex Login (subcommand) +@cindex Password client, using +@cindex Authenticated client, using +@cindex :pserver:, setting up +To run a @sc{cvs} command on a remote repository via +the password-authenticating server, one specifies the +@code{pserver} protocol, optional username, repository host, an +optional port number, and path to the repository. For example: + +@example +cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj +@end example + +@noindent +or + +@example +CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot +cvs checkout someproj +@end example + +However, unless you're connecting to a public-access +repository (i.e., one where that username doesn't +require a password), you'll need to supply a password or @dfn{log in} first. +Logging in verifies your password with the repository and stores it in a file. +It's done with the @code{login} command, which will +prompt you interactively for the password if you didn't supply one as part of +@var{$CVSROOT}: + +@example +cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login +CVS password: +@end example + +@noindent +or + +@example +cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login +@end example + +After you enter the password, @sc{cvs} verifies it with +the server. If the verification succeeds, then that +combination of username, host, repository, and password +is permanently recorded, so future transactions with +that repository won't require you to run @code{cvs +login}. (If verification fails, @sc{cvs} will exit +complaining that the password was incorrect, and +nothing will be recorded.) + +The records are stored, by default, in the file +@file{$HOME/.cvspass}. That file's format is +human-readable, and to a degree human-editable, but +note that the passwords are not stored in +cleartext---they are trivially encoded to protect them +from "innocent" compromise (i.e., inadvertent viewing +by a system administrator or other non-malicious +person). + +@cindex CVS_PASSFILE, environment variable +You can change the default location of this file by +setting the @code{CVS_PASSFILE} environment variable. +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. + +Once you have logged in, all @sc{cvs} commands using +that remote repository and username will authenticate +with the stored password. So, for example + +@example +cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo +@end example + +@noindent +should just work (unless the password changes on the +server side, in which case you'll have to re-run +@code{cvs login}). + +Note that if the @samp{:pserver:} were not present in +the repository specification, @sc{cvs} would assume it +should use @code{rsh} to connect with the server +instead (@pxref{Connecting via rsh}). + +Of course, 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} can deduce the repository +from the working copy's @file{CVS} subdirectory. + +@c FIXME: seems to me this needs somewhat more +@c explanation. +@cindex Logout (subcommand) +The password for a given remote repository can be +removed from the @code{CVS_PASSFILE} by using the +@code{cvs logout} command. + +@node Password authentication security +@subsubsection Security considerations with password authentication + +@cindex Security, of pserver +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. + +@c FIXME: The bit about "access to the repository +@c implies general access to the system is *not* specific +@c to pserver; it applies to kerberos and SSH and +@c everything else too. Should reorganize the +@c documentation to make this clear. +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 +non-read-only +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. +@c OpenBSD uses chroot() and copies the repository to +@c provide anonymous read-only access (for details see +@c http://www.openbsd.org/anoncvs.shar). While this +@c closes the most obvious holes, I'm not sure it +@c closes enough holes to recommend it (plus it is +@c *very* easy to accidentally screw up a setup of this +@c type). + +Note that because the @file{$CVSROOT/CVSROOT} directory +contains @file{passwd} and other files which are used +to check security, you must control the permissions on +this directory as tightly as the permissions on +@file{/etc}. The same applies to the @file{$CVSROOT} +directory itself and any directory +above it in the tree. Anyone who has write access to +such a directory will have the ability to become any +user on the system. Note that these permissions are +typically tighter than you would use if you are not +using pserver. +@c TODO: Would be really nice to document/implement a +@c scheme where the CVS server can run as some non-root +@c user, e.g. "cvs". CVSROOT/passwd would contain a +@c bunch of entries of the form foo:xxx:cvs (or the "cvs" +@c would be implicit). This would greatly reduce +@c security risks such as those hinted at in the +@c previous paragraph. I think minor changes to CVS +@c might be required but mostly this would just need +@c someone who wants to play with it, document it, &c. + +In summary, anyone who gets the password gets +repository access (which may imply 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 GSSAPI authenticated +@subsection Direct connection with GSSAPI + +@cindex GSSAPI +@cindex Security, GSSAPI +@cindex :gserver:, setting up +@cindex Kerberos, using :gserver: +GSSAPI is a generic interface to network security +systems such as Kerberos 5. +If you have a working GSSAPI library, you can have +@sc{cvs} connect via a direct @sc{tcp} connection, +authenticating with GSSAPI. + +To do this, @sc{cvs} needs to be compiled with GSSAPI +support; when configuring @sc{cvs} it tries to detect +whether GSSAPI libraries using Kerberos version 5 are +present. You can also use the @file{--with-gssapi} +flag to configure. + +The connection is authenticated using GSSAPI, but the +message stream is @emph{not} authenticated by default. +You must use the @code{-a} global option to request +stream authentication. + +The data transmitted is @emph{not} encrypted by +default. Encryption support must be compiled into both +the client and the server; use the +@file{--enable-encrypt} configure option to turn it on. +You must then use the @code{-x} global option to +request encryption. + +GSSAPI connections are handled on the server side by +the same server which handles the password +authentication server; see @ref{Password authentication +server}. If you are using a GSSAPI mechanism such as +Kerberos which provides for strong authentication, you +will probably want to disable the ability to +authenticate via cleartext passwords. To do so, create +an empty @file{CVSROOT/passwd} password file, and set +@code{SystemAuth=no} in the config file +(@pxref{config}). + +The GSSAPI server uses a principal name of +cvs/@var{hostname}, where @var{hostname} is the +canonical name of the server host. You will have to +set this up as required by your GSSAPI mechanism. + +To connect using GSSAPI, use the @samp{:gserver:} method. For +example, + +@example +cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo +@end example + +@node Kerberos authenticated +@subsection Direct connection with Kerberos + +@cindex Kerberos, using :kserver: +@cindex Security, Kerberos +@cindex :kserver:, setting up +The easiest way to use Kerberos is to use the Kerberos +@code{rsh}, as described in @ref{Connecting via rsh}. +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. + +This section concerns the Kerberos network security +system, version 4. Kerberos version 5 is supported via +the GSSAPI generic network security interface, as +described in the previous section. + +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. + +The data transmitted is @emph{not} encrypted by +default. Encryption support must be compiled into both +the client and server; use the +@file{--enable-encryption} configure option to turn it +on. You must then use the @code{-x} global option to +request encryption. + +@cindex CVS_CLIENT_PORT +You need to edit @file{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{CVSROOT} (@pxref{Remote repositories}) +or the @code{CVS_CLIENT_PORT} environment variable +(@pxref{Environment variables}) on the client. + +@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 :kserver:faun.example.org:/usr/local/cvsroot checkout foo +@end example + +Previous versions of @sc{cvs} would fall back to a +connection via rsh; this version will not do so. + +@node Connecting via fork +@subsection Connecting with fork + +@cindex fork, access method +@cindex :fork:, setting up +This access method allows you to connect to a +repository on your local disk via the remote protocol. +In other words it does pretty much the same thing as +@code{:local:}, but various quirks, bugs and the like are +those of the remote @sc{cvs} rather than the local +@sc{cvs}. + +For day-to-day operations you might prefer either +@code{:local:} or @code{:fork:}, depending on your +preferences. Of course @code{:fork:} comes in +particularly handy in testing or +debugging @code{cvs} and the remote protocol. +Specifically, we avoid all of the network-related +setup/configuration, timeouts, and authentication +inherent in the other remote access methods but still +create a connection which uses the remote protocol. + +To connect using the @code{fork} method, use +@samp{:fork:} and the pathname to your local +repository. For example: + +@example +cvs -d :fork:/usr/local/cvsroot checkout foo +@end example + +@cindex CVS_SERVER, and :fork: +As with @code{:ext:}, the server is called @samp{cvs} +by default, or the value of the @code{CVS_SERVER} +environment variable. + +@c --------------------------------------------------------------------- +@node Read-only access +@section Read-only repository access +@cindex Read-only repository access +@cindex readers (admin file) +@cindex writers (admin file) + + It is possible to grant read-only repository +access to people using the password-authenticated +server (@pxref{Password authenticated}). (The +other access methods do not have explicit support for +read-only users because those methods all assume login +access to the repository machine anyway, and therefore +the user can do whatever local file permissions allow +her to do.) + + A user who has read-only access can do only +those @sc{cvs} operations which do not modify the +repository, except for certain ``administrative'' files +(such as lock files and the history file). It may be +desirable to use this feature in conjunction with +user-aliasing (@pxref{Password authentication server}). + +Unlike with previous versions of @sc{cvs}, read-only +users should be able merely to read the repository, and +not to execute programs on the server or otherwise gain +unexpected levels of access. Or to be more accurate, +the @emph{known} holes have been plugged. Because this +feature is new and has not received a comprehensive +security audit, you should use whatever level of +caution seems warranted given your attitude concerning +security. + + There are two ways to specify read-only access +for a user: by inclusion, and by exclusion. + + "Inclusion" means listing that user +specifically in the @file{$CVSROOT/CVSROOT/readers} +file, which is simply a newline-separated list of +users. Here is a sample @file{readers} file: + +@example +melissa +splotnik +jrandom +@end example + +@noindent + (Don't forget the newline after the last user.) + + "Exclusion" means explicitly listing everyone +who has @emph{write} access---if the file + +@example +$CVSROOT/CVSROOT/writers +@end example + +@noindent +exists, then only +those users listed in it have write access, and +everyone else has read-only access (of course, even the +read-only users still need to be listed in the +@sc{cvs} @file{passwd} file). The +@file{writers} file has the same format as the +@file{readers} file. + + Note: if your @sc{cvs} @file{passwd} +file maps cvs users onto system users (@pxref{Password +authentication server}), make sure you deny or grant +read-only access using the @emph{cvs} usernames, not +the system usernames. That is, the @file{readers} and +@file{writers} files contain cvs usernames, which may +or may not be the same as system usernames. + + Here is a complete description of the server's +behavior in deciding whether to grant read-only or +read-write access: + + If @file{readers} exists, and this user is +listed in it, then she gets read-only access. Or if +@file{writers} exists, and this user is NOT listed in +it, then she also gets read-only access (this is true +even if @file{readers} exists but she is not listed +there). Otherwise, she gets full read-write access. + + Of course there is a conflict if the user is +listed in both files. This is resolved in the more +conservative way, it being better to protect the +repository too much than too little: such a user gets +read-only access. + +@node Server temporary directory +@section Temporary directories for the server +@cindex Temporary directories, and server +@cindex Server, temporary directories + +While running, the @sc{cvs} server creates temporary +directories. They are named + +@example +cvs-serv@var{pid} +@end example + +@noindent +where @var{pid} is the process identification number of +the server. +They are located in the directory specified by +the @samp{-T} global option (@pxref{Global options}), +the @code{TMPDIR} environment variable (@pxref{Environment variables}), +or, failing that, @file{/tmp}. + +In most cases the server will remove the temporary +directory when it is done, whether it finishes normally +or abnormally. However, there are a few cases in which +the server does not or cannot remove the temporary +directory, for example: + +@itemize @bullet +@item +If the server aborts due to an internal server error, +it may preserve the directory to aid in debugging + +@item +If the server is killed in a way that it has no way of +cleaning up (most notably, @samp{kill -KILL} on unix). + +@item +If the system shuts down without an orderly shutdown, +which tells the server to clean up. +@end itemize + +In cases such as this, you will need to manually remove +the @file{cvs-serv@var{pid}} directories. As long as +there is no server running with process identification +number @var{pid}, it is safe to do so. + +@c --------------------------------------------------------------------- +@node Starting a new project +@chapter Starting a project with CVS +@cindex Starting a project with CVS +@cindex Creating a project + +@comment --moduledb-- +Because renaming files and moving them between +directories is somewhat inconvenient, the first thing +you do when you start a new project should be to think +through your file organization. It is not impossible +to rename or move files, but it does increase the +potential for confusion and @sc{cvs} does have some +quirks particularly in the area of renaming +directories. @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 directory tree from scratch. +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node From files +@subsection Creating a directory tree 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{wdir}}, and you want them to appear in the +repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this: + +@example +$ cd @var{wdir} +$ cvs import -m "Imported sources" yoyodyne/@var{rdir} 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. +@c FIXME: Need to say more about "verify that it +@c worked". What should the user look for in the output +@c from "diff -r"? + +@example +$ cd .. +$ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below} +$ diff -r @var{wdir} yoyodyne/@var{rdir} +$ rm -r @var{wdir} +@end example + +@noindent +Erasing the original sources is a good idea, to make sure that you do +not accidentally edit them in @var{wdir}, 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 @code{$CVSROOT} +are reasonable, and that they belong to the proper +groups. @xref{File permissions}. + +If some of the files you want to import are binary, you +may want to use the wrappers features to specify which +files are binary and which are not. @xref{Wrappers}. + +@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 systems + +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 appropriate 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. + +The @sc{rcs} file should not be locked when you move it +into @sc{cvs}; if it is, @sc{cvs} will have trouble +letting you operate on it. +@c What is the easiest way to unlock your files if you +@c have them locked? Especially if you have a lot of them? +@c This is a CVS bug/misfeature; importing RCS files +@c should ignore whether they are locked and leave them in +@c an unlocked state. Yet another reason for a separate +@c "import RCS file" command. + +@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. + +Failing that, probably your best bet is to write a +script that will check out the files one revision at a +time using the command line interface to the other +system, and then check the revisions into @sc{cvs}. +The @file{sccs2rcs} script mentioned below may be a +useful example to follow. + +@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). + +@cindex PVCS, importing files from +@item From PVCS +There is a script in the @file{contrib} directory of +the @sc{cvs} source distribution called @file{pvcs_to_rcs} +which converts @sc{pvcs} archives to @sc{rcs} files. +You must run it on a machine which has both +@sc{pvcs} and @sc{rcs} installed, and like everything +else in contrib it is unsupported (your mileage may +vary). See the comments in the script for details. +@end table +@c CMZ and/or PATCHY were systems that were used in the +@c high energy physics community (especially for +@c CERNLIB). CERN has replaced them with CVS, but the +@c CAR format seems to live on as a way to submit +@c changes. There is a program car2cvs which converts +@c but I'm not sure where one gets a copy. +@c Not sure it is worth mentioning here, since it would +@c appear to affect only one particular community. +@c Best page for more information is: +@c http://wwwcn1.cern.ch/asd/cvs/index.html +@c See also: +@c http://ecponion.cern.ch/ecpsa/cernlib.html + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node From scratch +@subsection Creating a directory tree from scratch + +@c Also/instead should be documenting +@c $ cvs co -l . +@c $ mkdir tc +@c $ cvs add tc +@c $ cd tc +@c $ mkdir man +@c $ cvs add man +@c etc. +@c Using import to create the directories only is +@c probably a somewhat confusing concept. +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 + +This will add yoyodyne/@var{dir} as a directory under +@code{$CVSROOT}. + +Use @code{checkout} to get the new project. Then, use @code{add} +to add files (and new directories) as needed. + +@example +$ cd .. +$ cvs co yoyodyne/@var{dir} +@end example + +Check that the permissions @sc{cvs} sets on the +directories inside @code{$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 CVSROOT/modules +$ cd CVSROOT +@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 CVSROOT +@end example +@end enumerate + +@c --------------------------------------------------------------------- +@node Revisions +@chapter Revisions + +For many uses of @sc{cvs}, one doesn't need to worry +too much about revision numbers; @sc{cvs} assigns +numbers such as @code{1.1}, @code{1.2}, and so on, and +that is all one needs to know. However, some people +prefer to have more knowledge and control concerning +how @sc{cvs} assigns revision numbers. + +If one wants to keep track of a set of revisions +involving more than one file, such as which revisions +went into a particular release, one uses a @dfn{tag}, +which is a symbolic revision which can be assigned to a +numeric revision in each file. + +@menu +* Revision numbers:: The meaning of a revision number +* Versions revisions releases:: Terminology used in this manual +* Assigning revisions:: Assigning revisions +* Tags:: Tags--Symbolic revisions +* Tagging the working directory:: The cvs tag command +* Tagging by date/tag:: The cvs rtag command +* Modifying tags:: Adding, renaming, and deleting tags +* Tagging add/remove:: Tags with adding and removing files +* Sticky tags:: Certain tags are persistent +@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 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 + +It is also possible to end up with numbers containing +more than one period, for example @samp{1.3.2.2}. Such +revisions represent revisions on branches +(@pxref{Branching and merging}); such revision numbers +are explained in detail in @ref{Branches and +revisions}. + +@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. + +@node Assigning revisions +@section Assigning revisions + +@c We avoid the "major revision" terminology. It seems +@c like jargon. Hopefully "first number" is clear enough. +By default, @sc{cvs} will assign numeric revisions by +leaving the first number the same and incrementing the +second number. For example, @code{1.1}, @code{1.2}, +@code{1.3}, etc. + +When adding a new file, the second number will always +be one and the first number will equal the highest +first number of any file in that directory. For +example, the current directory contains files whose +highest numbered revisions are @code{1.7}, @code{3.1}, +and @code{4.12}, then an added file will be given the +numeric revision @code{4.1}. +(When using client/server @sc{cvs}, +only files that are actually sent to the server are considered.) + +@c This is sort of redundant with something we said a +@c while ago. Somewhere we need a better way of +@c introducing how the first number can be anything +@c except "1", perhaps. Also I don't think this +@c presentation is clear on why we are discussing releases +@c and first numbers of numeric revisions in the same +@c breath. +Normally there is no reason to care +about the revision numbers---it is easier to treat them +as internal numbers that @sc{cvs} maintains, and tags +provide a better way to distinguish between things like +release 1 versus release 2 of your product +(@pxref{Tags}). However, if you want to set the +numeric revisions, the @samp{-r} option to @code{cvs +commit} can do that. The @samp{-r} option implies the +@samp{-f} option, in the sense that it causes the +files to be committed even if they are not modified. + +For example, to bring all your files up to +revision 3.0 (including those that haven't changed), +you might invoke: + +@example +$ cvs commit -r 3.0 +@end example + +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}. If you want to maintain several releases in +parallel, you need to use a branch (@pxref{Branching and merging}). + +@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) +@cindex HEAD, as reserved tag name +@cindex BASE, as reserved tag name +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 must +start with an uppercase or lowercase letter and 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 be specially named, for example by +starting with @samp{.}, rather than being named analogously to +@code{BASE} and @code{HEAD}, to avoid conflicts with +actual tag names. +@c Including a character such as % or = has also been +@c suggested as the naming convention for future +@c special tag names. Starting with . is nice because +@c that is not a legal tag name as far as RCS is concerned. +@c FIXME: CVS actually accepts quite a few characters +@c in tag names, not just the ones documented above +@c (see RCS_check_tag). RCS +@c defines legitimate tag names by listing illegal +@c characters rather than legal ones. CVS is said to lose its +@c mind if you try to use "/" (try making such a tag sticky +@c and using "cvs status" client/server--see remote +@c protocol format for entries line for probable cause). +@c TODO: The testsuite +@c should test for whatever are documented above as +@c officially-OK tag names, and CVS should at least reject +@c characters that won't work, like "/". + +You'll want to choose some convention for naming tags, +based on information such as the name of the program +and the version number of the release. For example, +one might take the name of the program, immediately +followed by the version number with @samp{.} changed to +@samp{-}, so that @sc{cvs} 1.9 would be tagged with the name +@code{cvs1-9}. If you choose a consistent convention, +then you won't constantly be guessing whether a tag is +@code{cvs-1-9} or @code{cvs1_9} or what. You might +even want to consider enforcing your convention in the +@file{taginfo} file (@pxref{taginfo}). +@c Might be nice to say more about using taginfo this +@c way, like giving an example, or pointing out any particular +@c issues which arise. + +@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 +directory. That is, you should issue the +command in the directory where @file{backend.c} +resides. + +@example +$ cvs tag rel-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 /u/cvsroot/yoyodyne/tc/backend.c,v + Sticky Tag: (none) + Sticky Date: (none) + Sticky Options: (none) + + Existing Tags: + rel-0-4 (revision: 1.4) + +@end example + +For a complete summary of the syntax of @code{cvs tag}, +including the various options, see @ref{Invoking CVS}. + +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 rel-1-0 . +cvs tag: Tagging . +T Makefile +T backend.c +T driver.c +T frontend.c +T parser.c +@end example + +@noindent +(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 rel-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 specifying @samp{-r} to +any of these commands, you will need beware of sticky +tags; see @ref{Sticky tags}. + +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 + +@node Tagging the working directory +@section Specifying what to tag from the working directory + +@cindex tag (subcommand) +The example in the previous section demonstrates one of +the most common ways to choose which revisions to tag. +Namely, running the @code{cvs tag} command without +arguments causes @sc{cvs} to select the revisions which +are checked out in the current working directory. For +example, if the copy of @file{backend.c} in working +directory was checked out from revision 1.4, then +@sc{cvs} will tag revision 1.4. Note that the tag is +applied immediately to revision 1.4 in the repository; +tagging is not like modifying a file, or other +operations in which one first modifies the working +directory and then runs @code{cvs commit} to transfer +that modification to the repository. + +One potentially surprising aspect of the fact that +@code{cvs tag} operates on the repository is that you +are tagging the checked-in revisions, which may differ +from locally modified files in your working directory. +If you want to avoid doing this by mistake, specify the +@samp{-c} option to @code{cvs tag}. If there are any +locally modified files, @sc{cvs} will abort with an +error before it tags any files: + +@example +$ cvs tag -c rel-0-4 +cvs tag: backend.c is locally modified +cvs [tag aborted]: correct the above errors first! +@end example + +@node Tagging by date/tag +@section Specifying what to tag by date or revision +@cindex rtag (subcommand) + +The @code{cvs rtag} command tags the repository as of a +certain date or time (or can be used to tag the latest +revision). @code{rtag} works directly on the +repository contents (it requires no prior checkout and +does not look for a working directory). + +The following options specify which date or revision to +tag. See @ref{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 -r @var{tag} +Only tag those files that contain existing tag @var{tag}. +@end table + +The @code{cvs tag} command also allows one to specify +files by revision or date, using the same @samp{-r}, +@samp{-D}, and @samp{-f} options. However, this +feature is probably not what you want. The reason is +that @code{cvs tag} chooses which files to tag based on +the files that exist in the working directory, rather +than the files which existed as of the given tag/date. +Therefore, you are generally better off using @code{cvs +rtag}. The exceptions might be cases like: + +@example +cvs tag -r 1.4 backend.c +@end example + +@node Modifying tags +@section Deleting, moving, and renaming tags + +@c Also see: +@c "How do I move or rename a magic branch tag?" +@c in the FAQ (I think the issues it talks about still +@c apply, but this could use some sanity.sh work). + +Normally one does not modify tags. They exist in order +to record the history of the repository and so deleting +them or changing their meaning would, generally, not be +what you want. + +However, there might be cases in which one uses a tag +temporarily or accidentally puts one in the wrong +place. Therefore, one might delete, move, or rename a +tag. + +@noindent +@strong{WARNING: The commands in this section are +dangerous; they permanently discard historical +information and it can be difficult or impossible to +recover from errors. If you are a @sc{cvs} +administrator, you may consider restricting these +commands with the @file{taginfo} file (@pxref{taginfo}).} + +@cindex Deleting tags +@cindex Deleting branch tags +@cindex Removing tags +@cindex Removing branch tags +@cindex Tags, deleting +@cindex Branch tags, deleting +To delete a tag, specify the @samp{-d} option to either +@code{cvs tag} or @code{cvs rtag}. For example: + +@example +cvs rtag -d rel-0-4 tc +@end example + +@noindent +deletes the non-branch tag @code{rel-0-4} from the module @code{tc}. +In the event that branch tags are encountered within the repository +with the given name, a warning message will be issued and the branch +tag will not be deleted. If you are absolutely certain you know what +you are doing, the @code{-B} option may be specified to allow deletion +of branch tags. In that case, any non-branch tags encountered will +trigger warnings and will not be deleted. + +@noindent +@strong{WARNING: Moving branch tags is very dangerous! If you think +you need the @code{-B} option, think again and ask your @sc{cvs} +administrator about it (if that isn't you). There is almost certainly +another way to accomplish what you want to accomplish.} + +@cindex Moving tags +@cindex Moving branch tags +@cindex Tags, moving +@cindex Branch tags, moving +When we say @dfn{move} a tag, we mean to make the same +name point to different revisions. For example, the +@code{stable} tag may currently point to revision 1.4 +of @file{backend.c} and perhaps we want to make it +point to revision 1.6. To move a non-branch tag, specify the +@samp{-F} option to either @code{cvs tag} or @code{cvs +rtag}. For example, the task just mentioned might be +accomplished as: + +@example +cvs tag -r 1.6 -F stable backend.c +@end example + +@noindent +If any branch tags are encountered in the repository +with the given name, a warning is issued and the branch +tag is not disturbed. If you are absolutely certain you +wish to move the branch tag, the @code{-B} option may be specified. +In that case, non-branch tags encountered with the given +name are ignored with a warning message. + +@noindent +@strong{WARNING: Moving branch tags is very dangerous! If you think you +need the @code{-B} option, think again and ask your @sc{cvs} +administrator about it (if that isn't you). There is almost certainly +another way to accomplish what you want to accomplish.} + +@cindex Renaming tags +@cindex Tags, renaming +When we say @dfn{rename} a tag, we mean to make a +different name point to the same revisions as the old +tag. For example, one may have misspelled the tag name +and want to correct it (hopefully before others are +relying on the old spelling). To rename a tag, first +create a new tag using the @samp{-r} option to +@code{cvs rtag}, and then delete the old name. (Caution: +this method will not work with branch tags.) +This leaves the new tag on exactly the +same files as the old tag. For example: + +@example +cvs rtag -r old-name-0-4 rel-0-4 tc +cvs rtag -d old-name-0-4 tc +@end example + +@node Tagging add/remove +@section Tagging and adding and removing files + +The subject of exactly how tagging interacts with +adding and removing files is somewhat obscure; for the +most part @sc{cvs} will keep track of whether files +exist or not without too much fussing. By default, +tags are applied to only files which have a revision +corresponding to what is being tagged. Files which did +not exist yet, or which were already removed, simply +omit the tag, and @sc{cvs} knows to treat the absence +of a tag as meaning that the file didn't exist as of +that tag. + +However, this can lose a small amount of information. +For example, suppose a file was added and then removed. +Then, if the tag is missing for that file, there is no +way to know whether the tag refers to the time before +the file was added, or the time after it was removed. +If you specify the @samp{-r} option to @code{cvs rtag}, +then @sc{cvs} tags the files which have been removed, +and thereby avoids this problem. For example, one +might specify @code{-r HEAD} to tag the head. + +On the subject of adding and removing files, the +@code{cvs rtag} command has a @samp{-a} option which +means to clear the tag from removed files that would +not otherwise be tagged. For example, one might +specify this option in conjunction with @samp{-F} when +moving a tag. If one moved a tag without @samp{-a}, +then the tag in the removed files might still refer to +the old revision, rather than reflecting the fact that +the file had been removed. I don't think this is +necessary if @samp{-r} is specified, as noted above. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Sticky tags +@section Sticky tags +@cindex Sticky tags +@cindex Tags, sticky + +@c A somewhat related issue is per-directory sticky +@c tags (see comment at CVS/Tag in node Working +@c directory storage); we probably want to say +@c something like "you can set a sticky tag for only +@c some files, but you don't want to" or some such. + +Sometimes a working copy's revision has extra data +associated with it, for example it might be on a branch +(@pxref{Branching and merging}), or restricted to +versions prior to a certain date by @samp{checkout -D} +or @samp{update -D}. Because this data persists -- +that is, it applies to subsequent commands in the +working copy -- we refer to it as @dfn{sticky}. + +Most of the time, stickiness is an obscure aspect of +@sc{cvs} that you don't need to think about. However, +even if you don't want to use the feature, you may need +to know @emph{something} about sticky tags (for +example, how to avoid them!). + +You can use the @code{status} command to see if any +sticky tags or dates are set: + +@example +$ cvs status 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 /u/cvsroot/yoyodyne/tc/driver.c,v + Sticky Tag: rel-1-0-patches (branch: 1.7.2) + Sticky Date: (none) + Sticky Options: (none) + +@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 merges local changes into the version of the +file from the head of the trunk, removing any sticky tags, +dates, or options (other than sticky @samp{-k} options on locally +modified files). See @ref{update} for more on the operation +of @code{cvs update}. + +@cindex Sticky date +The most common use of sticky tags is to identify which +branch one is working on, as described in +@ref{Accessing branches}. However, non-branch +sticky tags have uses as well. For example, +suppose that you want to avoid updating your working +directory, to isolate yourself from possibly +destabilizing changes other people are making. You +can, of course, just refrain from running @code{cvs +update}. But if you want to avoid updating only a +portion of a larger tree, then sticky tags can help. +If you check out a certain revision (such as 1.4) it +will become sticky. Subsequent @code{cvs update} +commands will +not retrieve the latest revision until you reset the +tag with @code{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. + +People often want to retrieve an old version of +a file without setting a sticky tag. This can +be done with the @samp{-p} option to @code{checkout} or +@code{update}, which sends the contents of the file to +standard output. For example: +@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 +*************** +$ +@end example + +However, this isn't the easiest way, if you are asking +how to undo a previous checkin (in this example, put +@file{file1} back to the way it was as of revision +1.1). In that case you are better off using the +@samp{-j} option to @code{update}; for further +discussion see @ref{Merging two revisions}. + +@c --------------------------------------------------------------------- +@node Branching and merging +@chapter Branching and merging +@cindex Branching +@cindex Merging +@cindex Copying changes +@cindex Main trunk and branches +@cindex Revision tree, making branches +@cindex Branches, copying changes between +@cindex Changes, copying between branches +@cindex Modifications, copying between branches + +@sc{cvs} allows you to isolate changes onto a separate +line of development, known as a @dfn{branch}. When you +change files on a branch, those changes do not appear +on the main trunk or other branches. + +Later you can move changes from one branch to another +branch (or the main trunk) by @dfn{merging}. Merging +involves first running @code{cvs update -j}, to merge +the changes into the working directory. +You can then commit that revision, and thus effectively +copy the changes onto another branch. + +@menu +* Branches motivation:: What branches are good for +* Creating a branch:: Creating a branch +* Accessing branches:: Checking out and updating branches +* Branches and revisions:: Branches are reflected in revision numbers +* Magic branch numbers:: Magic branch numbers +* 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 +* Merging adds and removals:: What if files are added or removed? +* Merging and keywords:: Avoiding conflicts due to keyword substitution +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Branches motivation +@section What branches are good for +@cindex Branches motivation +@cindex What branches are good for +@cindex Motivation for branches + +@c FIXME: this node mentions one way to use branches, +@c but it is by no means the only way. For example, +@c the technique of committing a new feature on a branch, +@c until it is ready for the main trunk. The whole +@c thing is generally speaking more akin to the +@c "Revision management" node although it isn't clear to +@c me whether policy matters should be centralized or +@c distributed throughout the relevant sections. +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 +bug fix 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 elect 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 tag, creating a branch using +@cindex rtag, creating a branch using + +You can create a branch with @code{tag -b}; for +example, assuming you're in a working copy: + +@example +$ cvs tag -b rel-1-0-patches +@end example + +@c FIXME: we should be more explicit about the value of +@c having a tag on the branchpoint. For example +@c "cvs tag rel-1-0-patches-branchpoint" before +@c the "cvs tag -b". This points out that +@c rel-1-0-patches is a pretty awkward name for +@c this example (more so than for the rtag example +@c below). + +This splits off a branch based on the current revisions +in the working copy, assigning that branch the name +@samp{rel-1-0-patches}. + +It is important to understand that branches get created +in the repository, not in the working copy. Creating a +branch based on current revisions, as the above example +does, will @emph{not} automatically switch the working +copy to be on the new branch. For information on how +to do that, see @ref{Accessing branches}. + +You can also create a branch without reference to any +working copy, by using @code{rtag}: + +@example +$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc +@end example + +@samp{-r rel-1-0} says that this branch should be +rooted at the revision that +corresponds to the tag @samp{rel-1-0}. It need not +be the most recent revision -- it's often useful to +split a branch off an old revision (for example, when +fixing a bug in a past release otherwise known to be +stable). + +As with @samp{tag}, the @samp{-b} flag tells +@code{rtag} to create a branch (rather than just a +symbolic revision name). Note that the numeric +revision number that matches @samp{rel-1-0} will +probably be different from file to file. + +So, the full effect of the command is to create a new +branch -- named @samp{rel-1-0-patches} -- in module +@samp{tc}, rooted in the revision tree at the point tagged +by @samp{rel-1-0}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Accessing branches +@section Accessing branches +@cindex Check out a branch +@cindex Retrieve a branch +@cindex Access a branch +@cindex Identifying a branch +@cindex Branch, check out +@cindex Branch, retrieving +@cindex Branch, accessing +@cindex Branch, identifying + +You can retrieve a branch in one of two ways: by +checking it out fresh from the repository, or by +switching an existing working copy over to the branch. + +To check out a branch from the repository, invoke +@samp{checkout} with the @samp{-r} flag, followed by +the tag name of the branch (@pxref{Creating a branch}): + +@example +$ cvs checkout -r rel-1-0-patches tc +@end example + +Or, if you already have a working copy, you can switch +it to a given branch with @samp{update -r}: + +@example +$ cvs update -r rel-1-0-patches tc +@end example + +@noindent +or equivalently: + +@example +$ cd tc +$ cvs update -r rel-1-0-patches +@end example + +It does not matter if the working copy was originally +on the main trunk or on some other branch -- the above +command will switch it to the named branch. And +similarly to a regular @samp{update} command, +@samp{update -r} merges any changes you have made, +notifying you of conflicts where they occur. + +Once you have a working copy tied to a particular +branch, it remains there until you tell it otherwise. +This means that changes checked in from the working +copy will add new revisions on that branch, while +leaving the main trunk and other branches unaffected. + +@cindex Branches, sticky +To find out what branch a working copy is on, you can +use the @samp{status} command. In its output, look for +the field named @samp{Sticky tag} (@pxref{Sticky tags}) +-- that's @sc{cvs}'s way of telling you the branch, if +any, of the current working files: + +@example +$ 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 /u/cvsroot/yoyodyne/tc/driver.c,v + Sticky Tag: rel-1-0-patches (branch: 1.7.2) + Sticky Date: (none) + Sticky Options: (none) + + Existing Tags: + rel-1-0-patches (branch: 1.7.2) + rel-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 /u/cvsroot/yoyodyne/tc/backend.c,v + Sticky Tag: rel-1-0-patches (branch: 1.4.2) + Sticky Date: (none) + Sticky Options: (none) + + Existing Tags: + rel-1-0-patches (branch: 1.4.2) + rel-1-0 (revision: 1.4) + rel-0-4 (revision: 1.4) + +@end example + +Don't be confused by the fact that the branch numbers +for each file are different (@samp{1.7.2} and +@samp{1.4.2} respectively). The branch tag is the +same, @samp{rel-1-0-patches}, and the files are +indeed on the same branch. The numbers simply reflect +the point in each file's revision history at which the +branch was made. In the above example, one can deduce +that @samp{driver.c} had been through more changes than +@samp{backend.c} before this branch was created. + +See @ref{Branches and revisions} for details about how +branch numbers are constructed. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Branches and revisions +@section Branches and revisions +@cindex Branch number +@cindex Number, branch +@cindex Revision numbers (branches) + +Ordinarily, a file's revision history is a linear +series of increments (@pxref{Revision numbers}): + +@example + +-----+ +-----+ +-----+ +-----+ +-----+ + ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! + +-----+ +-----+ +-----+ +-----+ +-----+ +@end example + +However, @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 +@c This example used to have a 1.2.2.4 revision, which +@c might help clarify that development can continue on +@c 1.2.2. Might be worth reinstating if it can be done +@c without overfull hboxes. +@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.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 Magic branch numbers +@section Magic branch numbers + +@c Want xref to here from "log"? + +This section describes a @sc{cvs} feature called +@dfn{magic branches}. For most purposes, you need not +worry about magic branches; @sc{cvs} handles them for +you. However, they are visible to you in certain +circumstances, so it may be useful to have some idea of +how it works. + +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.4 becomes +1.2.0.4, 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 a few places the hiding +is incomplete: + +@itemize @bullet +@ignore +@c This is in ignore as I'm taking their word for it, +@c that this was fixed +@c a long time ago. But before deleting this +@c entirely, I'd rather verify it (and add a test +@c case to the testsuite). +@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. + +@end ignore +@item +The magic branch number appears in the output from +@code{cvs log}. +@c What output should appear instead? + +@item +You cannot specify a symbolic branch name to @code{cvs +admin}. + +@end itemize + +@c Can CVS do this automatically the first time +@c you check something in to that branch? Should +@c it? +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 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{branchname}} flag to the @code{update} subcommand. With one +@samp{-j @var{branchname}} option it merges the changes made between the +greatest common ancestor (GCA) of the branch and the destination revision (in +the simple case below the GCA is the point where the branch forked) and the +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}. + +If your source files contain keywords (@pxref{Keyword substitution}), +you might be getting more conflicts than strictly necessary. See +@ref{Merging and keywords}, for information on how to avoid this. + +The @code{checkout} command also supports the @samp{-j @var{branchname}} flag. The +same effect as above could be achieved with this: + +@example +$ cvs checkout -j R1fix mod +$ cvs commit -m "Included R1fix" +@end example + +It should be noted that @code{update -j @var{tagname}} will also work but may +not produce the desired result. @xref{Merging adds and removals}, for more. + +@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 + +@noindent +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 + +@noindent +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 undo 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. +You almost always use symbolic +tags rather than revision numbers when operating on +multiple files. + +@cindex Restoring old version of removed file +@cindex Resurrecting old version of dead file +Specifying two @samp{-j} options can also undo file +removals or additions. 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 -j 1.2 -j 1.1 file1 +U file1 +$ 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 + +@node Merging adds and removals +@section Merging can add or remove files + +If the changes which you are merging involve removing +or adding some files, @code{update -j} will reflect +such additions or removals. + +@c FIXME: This example needs a lot more explanation. +@c We also need other examples for some of the other +@c cases (not all--there are too many--as long as we present a +@c coherent general principle). +For example: +@example +cvs update -A +touch a b c +cvs add a b c ; cvs ci -m "added" a b c +cvs tag -b branchtag +cvs update -r branchtag +touch d ; cvs add d +rm a ; cvs rm a +cvs ci -m "added d, removed a" +cvs update -A +cvs update -jbranchtag +@end example + +After these commands are executed and a @samp{cvs commit} is done, +file @file{a} will be removed and file @file{d} added in the main branch. +@c (which was determined by trying it) + +Note that using a single static tag (@samp{-j @var{tagname}}) +rather than a dynamic tag (@samp{-j @var{branchname}}) to merge +changes from a branch will usually not remove files which were removed on the +branch since @sc{cvs} does not automatically add static tags to dead revisions. +The exception to this rule occurs when +a static tag has been attached to a dead revision manually. Use the branch tag +to merge all changes from the branch or use two static tags as merge endpoints +to be sure that all intended changes are propagated in the merge. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Merging and keywords +@section Merging and keywords +@cindex Merging, and keyword substitution +@cindex Keyword substitution, and merging +@cindex -j (merging branches), and keyword substitution +@cindex -kk, to avoid conflicts during a merge + +If you merge files containing keywords (@pxref{Keyword +substitution}), you will normally get numerous +conflicts during the merge, because the keywords are +expanded differently in the revisions which you are +merging. + +Therefore, you will often want to specify the +@samp{-kk} (@pxref{Substitution modes}) switch to the +merge command line. By substituting just the name of +the keyword, not the expanded value of that keyword, +this option ensures that the revisions which you are +merging will be the same as each other, and avoid +spurious conflicts. + +For example, suppose you have a file like this: + +@example + +---------+ + _! 1.1.2.1 ! <- br1 + / +---------+ + / + / ++-----+ +-----+ +! 1.1 !----! 1.2 ! ++-----+ +-----+ +@end example + +@noindent +and your working directory is currently on the trunk +(revision 1.2). Then you might get the following +results from a merge: + +@example +$ cat file1 +key $@splitrcskeyword{Revision}: 1.2 $ +. . . +$ cvs update -j br1 +U file1 +RCS file: /cvsroot/first-dir/file1,v +retrieving revision 1.1 +retrieving revision 1.1.2.1 +Merging differences between 1.1 and 1.1.2.1 into file1 +rcsmerge: warning: conflicts during merge +$ cat file1 +@asis{}<<<<<<< file1 +key $@splitrcskeyword{Revision}: 1.2 $ +@asis{}======= +key $@splitrcskeyword{Revision}: 1.1.2.1 $ +@asis{}>>>>>>> 1.1.2.1 +. . . +@end example + +What happened was that the merge tried to merge the +differences between 1.1 and 1.1.2.1 into your working +directory. So, since the keyword changed from +@code{Revision: 1.1} to @code{Revision: 1.1.2.1}, +@sc{cvs} tried to merge that change into your working +directory, which conflicted with the fact that your +working directory had contained @code{Revision: 1.2}. + +Here is what happens if you had used @samp{-kk}: + +@example +$ cat file1 +key $@splitrcskeyword{Revision}: 1.2 $ +. . . +$ cvs update -kk -j br1 +U file1 +RCS file: /cvsroot/first-dir/file1,v +retrieving revision 1.1 +retrieving revision 1.1.2.1 +Merging differences between 1.1 and 1.1.2.1 into file1 +$ cat file1 +key $@splitrcskeyword{Revision}$ +. . . +@end example + +What is going on here is that revision 1.1 and 1.1.2.1 +both expand as plain @code{Revision}, and therefore +merging the changes between them into the working +directory need not change anything. Therefore, there +is no conflict. + +There is, however, one major caveat with using +@samp{-kk} on merges. Namely, it overrides whatever +keyword expansion mode @sc{cvs} would normally have +used. In particular, this is a problem if the mode had +been @samp{-kb} for a binary file. Therefore, if your +repository contains binary files, you will need to deal +with the conflicts rather than using @samp{-kk}. + +@ignore +The following seems rather confusing, possibly buggy, +and in general, in need of much more thought before it +is a recommended technique. For one thing, does it +apply on Windows as well as on Unix? + +Unchanged binary files will undergo the same keyword substitution +but will not be checked in on a subsequent +@code{cvs commit}. Be aware that binary files containing keyword +strings which are present in or below the working directory +will most likely remain corrupt until repaired, however. A simple +@code{cvs update -A} is sufficient to fix these otherwise unaltered binary files +if the merge is being done to the main branch but +this must be done after the merge has been committed or the merge itself +will be lost. + +For Example: +@example +cvs update -Akk -jbranchtag +cvs commit +cvs update -A +@end example + +@noindent +will update the current directory from the main trunk of the +repository, substituting the base keyword strings for keywords, +and merge changes made on the branch @samp{branchtag} into the new +work files, performing the same keyword substitution on that file set before +comparing the two sets. The final @code{cvs update -A} will restore any +corrupted binary files as well as resetting the sticky @samp{-kk} tags which +were present on the files in and below the working directory. +Unfortunately, this doesn't work as well with an arbitrary branch tag, as the +@samp{-r @var{branchtag}} switch does not reset the sticky @samp{-kk} +switches attached to the working files as @samp{-A} does. The workaround +for this is to release the working directory after the merge has been +committed and check it out again. +@end ignore + +As a result of using @samp{-kk} during the merge, each file examined by the +update will have @samp{-kk} set as sticky options. Running @code{update -A} +will clear the sticky options on unmodified files, but it will not clear +the sticky options on modified files. To get back to the default keyword +substitution for modified files, you must commit the results of the merge +and then run @code{update -A}. + +@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 + +@example +cvs update testing/testpgm.t testing/test2.t +@end example + +@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} directory +@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. +Conversely, the @samp{-R} option can be used to force recursion if +@samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}). + +@example +$ cvs update -l # @r{Don't update files in subdirectories} +@end example + +@c --------------------------------------------------------------------- +@node Adding and removing +@chapter Adding, removing, and renaming files and directories + +In the course of a project, one will often add new +files. Likewise with removing or renaming, or with +directories. The general concept to keep in mind in +all these cases is that instead of making an +irreversible change you want @sc{cvs} to record the +fact that a change has taken place, just as with +modifying an existing file. The exact mechanisms to do +this in @sc{cvs} vary depending on the situation. + +@menu +* Adding files:: Adding files +* Removing files:: Removing files +* Removing directories:: Removing directories +* Moving files:: Moving and renaming files +* Moving directories:: Moving and renaming directories +@end menu + +@node Adding files +@section Adding files to a directory +@cindex Adding files + +To add a new file to a directory, follow these steps. + +@itemize @bullet +@item +You must have a working copy of the directory. +@xref{Getting the source}. + +@item +Create the new file inside your working copy of the directory. + +@item +Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you +want to version control the file. If the file contains +binary data, specify @samp{-kb} (@pxref{Binary files}). + +@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. +@end itemize + +You can also use the @code{add} command to add a new +directory. +@c FIXCVS and/or FIXME: Adding a directory doesn't +@c require the commit step. This probably can be +@c considered a CVS bug, but it is possible we should +@c warn people since this behavior probably won't be +@c changing right away. + +Unlike most other commands, the @code{add} command is +not recursive. You have to explicitly name files and +directories that you wish to add to the repository. +However, each directory will need to be added +separately before you will be able to add new files +to those directories. + +@example +$ mkdir -p foo/bar +$ cp ~/myfile foo/bar/myfile +$ cvs add foo foo/bar +$ cvs add foo/bar/myfile +@end example + +@cindex add (subcommand) +@deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{} + +Schedule @var{files} to be added to the repository. +The files or directories specified with @code{add} must +already exist in the current directory. 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}. + +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 undo the +effect of the @code{remove}, unless a @code{commit} +command intervened. @xref{Removing files}, for an +example. + +The @samp{-k} option specifies the default way that +this file will be checked out; for more information see +@ref{Substitution modes}. + +@c As noted in BUGS, -m is broken client/server (Nov +@c 96). Also see testsuite log2-* tests. +The @samp{-m} option specifies 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 version history 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 deffn + +For example, the following commands add the file +@file{backend.c} to the repository: + +@c This example used to specify +@c -m "Optimizer and code generation passes." +@c to the cvs add command, but that doesn't work +@c client/server (see log2 in sanity.sh). Should fix CVS, +@c but also seems strange to document things which +@c don't work... +@example +$ cvs add backend.c +$ cvs commit -m "Early version. Not yet compilable." backend.c +@end example + +When you add a file it is added only on the branch +which you are working on (@pxref{Branching and merging}). You can +later merge the additions to another branch if you want +(@pxref{Merging adds and removals}). +@c Should we mention that earlier versions of CVS +@c lacked this feature (1.3) or implemented it in a buggy +@c way (well, 1.8 had many bugs in cvs update -j)? +@c Should we mention the bug/limitation regarding a +@c file being a regular file on one branch and a directory +@c on another? +@c FIXME: This needs an example, or several, here or +@c elsewhere, for it to make much sense. +@c Somewhere we need to discuss the aspects of death +@c support which don't involve branching, I guess. +@c Like the ability to re-create a release from a tag. + +@c --------------------------------------------------------------------- +@node Removing files +@section Removing files +@cindex Removing files +@cindex Deleting files + +@c FIXME: this node wants to be split into several +@c smaller nodes. Could make these children of +@c "Adding and removing", probably (death support could +@c be its own section, for example, as could the +@c various bits about undoing mistakes in adding and +@c removing). +Directories change. New files are added, and old files +disappear. Still, you want to be able to retrieve an +exact copy of old releases. + +Here is what you can do to remove a file, +but remain able to retrieve old revisions: + +@itemize @bullet +@c FIXME: should probably be saying something about +@c having a working directory in the first place. +@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 directory. +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 + +@c FIXME: Somehow this should be linked in with a more +@c general discussion of death support. I don't know +@c whether we want to use the term "death support" or +@c not (we can perhaps get by without it), but we do +@c need to discuss the "dead" state in "cvs log" and +@c related subjects. The current discussion is +@c scattered around, and not xref'd to each other. +@c FIXME: I think this paragraph wants to be moved +@c later down, at least after the first example. +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. @sc{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}. + +@c FIXME: This style seems to clash with how we +@c document things in general. +@cindex Remove (subcommand) +@deffn Command {cvs remove} [options] 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. For a full list of +options, see @ref{Invoking CVS}. +@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 + +As a convenience you can remove the file and @code{cvs +remove} it in one step, by specifying the @samp{-f} +option. For example, the above example could also be +done like this: + +@example +$ cd test +$ cvs remove -f *.c +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 execute @code{remove} for a file, and then +change your mind before you commit, you can undo the +@code{remove} with an @code{add} command. +@ignore +@c is this worth saying or not? Somehow it seems +@c confusing to me. +Of course, +since you have removed your copy of file in the working +directory, @sc{cvs} does not necessarily bring back the +contents of the file from right before you executed +@code{remove}; instead it gets the file from the +repository again. +@end ignore + +@c FIXME: what if you change your mind after you commit +@c it? (answer is also "cvs add" but we don't say that...). +@c We need some index entries for thinks like "undoing +@c removal" too. + +@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 + +When you remove a file it is removed only on the branch +which you are working on (@pxref{Branching and merging}). You can +later merge the removals to another branch if you want +(@pxref{Merging adds and removals}). + +@node Removing directories +@section Removing directories +@cindex Removing directories +@cindex Directories, removing + +In concept, removing directories is somewhat similar to +removing files---you want the directory to not exist in +your current working directories, but you also want to +be able to retrieve old releases in which the directory +existed. + +The way that you remove a directory is to remove all +the files in it. You don't remove the directory +itself; there is no way to do that. +Instead you specify the @samp{-P} option to +@code{cvs update} or @code{cvs checkout}, +which will cause @sc{cvs} to remove empty +directories from working directories. +(Note that @code{cvs export} always removes empty directories.) +Probably the +best way to do this is to always specify @samp{-P}; if +you want an empty directory then put a dummy file (for +example @file{.keepme}) in it to prevent @samp{-P} from +removing it. + +@c I'd try to give a rationale for this, but I'm not +@c sure there is a particularly convincing one. What +@c we would _like_ is for CVS to do a better job of version +@c controlling whether directories exist, to eliminate the +@c need for -P and so that a file can be a directory in +@c one revision and a regular file in another. +Note that @samp{-P} is implied by the @samp{-r} or @samp{-D} +options of @code{checkout}. This way, +@sc{cvs} will be able to correctly create the directory +or not depending on whether the particular version you +are checking out contains any files in that directory. + +@c --------------------------------------------------------------------- +@node Moving files +@section 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 +@subsection The Normal way to Rename + +@c More rename issues. Not sure whether these are +@c worth documenting; I'm putting them here because +@c it seems to be as good a place as any to try to +@c set down the issues. +@c * "cvs annotate" will annotate either the new +@c file or the old file; it cannot annotate _each +@c line_ based on whether it was last changed in the +@c new or old file. Unlike "cvs log", where the +@c consequences of having to select either the new +@c or old name seem fairly benign, this may be a +@c real advantage to having CVS know about renames +@c other than as a deletion and an addition. + +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. +@c The following sentence is not true: one must cd into +@c the directory to run "cvs add". +@c (Both @var{old} and @var{new} could +@c 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 again, usually at 1.1, so if that bothers you, +use the @samp{-r rev} option to commit. For more +information see @ref{Assigning revisions}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Inside +@subsection 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{dir} +$ 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 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 +@subsection 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{dir} +$ cp @var{old},v @var{new},v +# @r{Remove the old file} +$ cd ~/@var{dir} +$ 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 non-branch tag names} +$ cvs tag -d @var{tag1} @var{new} +$ cvs tag -d @var{tag2} @var{new} +@dots{} +@end example + +By removing the tags you will be able to check out old +revisions. + +@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. + +@ignore +@c Is this true? I don't see how the revision numbers +@c _could_ start over, when new,v is just old,v with +@c the tags deleted. +@c If there is some need to reinstate this text, +@c it is "usually 1.1", not "1.0" and it needs an +@c xref to Assigning revisions +@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 ignore +@end itemize + +@c --------------------------------------------------------------------- +@node Moving directories +@section Moving and renaming directories +@cindex Moving directories +@cindex Renaming directories +@cindex Directories, moving + +The normal way to rename or move a directory is to +rename or move each file within it as described in +@ref{Outside}. Then check out with the @samp{-P} +option, as described in @ref{Removing directories}. + +If you really want to hack the repository to rename or +delete a directory in the repository, you can do it +like this: + +@enumerate +@item +Inform everyone who has a checked out copy of the directory that the +directory will be renamed. They should commit all their changes in all their +copies of the project containing the directory to be removed, and remove +all their working copies of said project, before you take the steps below. + +@item +Rename the directory inside the repository. + +@example +$ cd $CVSROOT/@var{parent-dir} +$ 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 again and continue +working. + +@end enumerate + +If someone had a working copy 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. + +@c FIXME: should also be talking about how you look at +@c old revisions (e.g. "cvs update -p -r 1.2 foo.c"). +@menu +* log messages:: Log messages +* history database:: The history database +* user-defined logging:: User-defined logging +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node log messages +@section Log messages + +@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}). + +Note: you can control what is logged to this file by using the +@samp{LogHistory} keyword in the @file{CVSROOT/config} file +(@pxref{config}). + +@c +@c The history database has many problems: +@c * It is very unclear what field means what. This +@c could be improved greatly by better documentation, +@c but there are still non-orthogonalities (for +@c example, tag does not record the "repository" +@c field but most records do). +@c * Confusion about files, directories, and modules. +@c Some commands record one, some record others. +@c * File removal is not logged. There is an 'R' +@c record type documented, but CVS never uses it. +@c * Tags are only logged for the "cvs rtag" command, +@c not "cvs tag". The fix for this is not completely +@c clear (see above about modules vs. files). +@c * Are there other cases of operations that are not +@c logged? One would hope for all changes to the +@c repository to be logged somehow (particularly +@c operations like tagging, "cvs admin -k", and other +@c operations which do not record a history that one +@c can get with "cvs log"). Operations on the working +@c directory, like export, get, and release, are a +@c second category also covered by the current "cvs +@c history". +@c * The history file does not record the options given +@c to a command. The most serious manifestation of +@c this is perhaps that it doesn't record whether a command +@c was recursive. It is not clear to me whether one +@c wants to log at a level very close to the command +@c line, as a sort of way of logging each command +@c (more or less), or whether one wants +@c to log more at the level of what was changed (or +@c something in between), but either way the current +@c information has pretty big gaps. +@c * Further details about a tag--like whether it is a +@c branch tag or, if a non-branch tag, which branch it +@c is on. One can find out this information about the +@c tag as it exists _now_, but if the tag has been +@c moved, one doesn't know what it was like at the time +@c the history record was written. +@c * Whether operating on a particular tag, date, or +@c options was implicit (sticky) or explicit. +@c +@c Another item, only somewhat related to the above, is a +@c way to control what is logged in the history file. +@c This is probably the only good way to handle +@c different people having different ideas about +@c information/space tradeoffs. +@c +@c It isn't really clear that it makes sense to try to +@c patch up the history file format as it exists now to +@c include all that stuff. It might be better to +@c design a whole new CVSROOT/nhistory file and "cvs +@c nhistory" command, or some such, or in some other +@c way trying to come up with a clean break from the +@c past, which can address the above concerns. Another +@c open question is how/whether this relates to +@c taginfo/loginfo/etc. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node user-defined logging +@section User-defined logging + +@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}). +To log tags, use the @file{taginfo} file (@pxref{taginfo}). +@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 checkouts, exports, and tags, +respectively, you can also use the +@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}. + +@c --------------------------------------------------------------------- +@node Binary files +@chapter Handling binary files +@cindex Binary files + +The most common use for @sc{cvs} is to store text +files. With text files, @sc{cvs} can merge revisions, +display the differences between revisions in a +human-visible fashion, and other such operations. +However, if you are willing to give up a few of these +abilities, @sc{cvs} can store binary files. For +example, one might store a web site in @sc{cvs} +including both text files and binary images. + +@menu +* Binary why:: More details on issues with binary files +* Binary howto:: How to store them +@end menu + +@node Binary why +@section The issues with binary files + +While the need to manage binary files may seem obvious +if the files that you customarily work with are binary, +putting them into version control does present some +additional issues. + +One basic function of version control is to show the +differences between two revisions. For example, if +someone else checked in a new version of a file, you +may wish to look at what they changed and determine +whether their changes are good. For text files, +@sc{cvs} provides this functionality via the @code{cvs +diff} command. For binary files, it may be possible to +extract the two revisions and then compare them with a +tool external to @sc{cvs} (for example, word processing +software often has such a feature). If there is no +such tool, one must track changes via other mechanisms, +such as urging people to write good log messages, and +hoping that the changes they actually made were the +changes that they intended to make. + +Another ability of a version control system is the +ability to merge two revisions. For @sc{cvs} this +happens in two contexts. The first is when users make +changes in separate working directories +(@pxref{Multiple developers}). The second is when one +merges explicitly with the @samp{update -j} command +(@pxref{Branching and merging}). + +In the case of text +files, @sc{cvs} can merge changes made independently, +and signal a conflict if the changes conflict. With +binary files, the best that @sc{cvs} can do is present +the two different copies of the file, and leave it to +the user to resolve the conflict. The user may choose +one copy or the other, or may run an external merge +tool which knows about that particular file format, if +one exists. +Note that having the user merge relies primarily on the +user to not accidentally omit some changes, and thus is +potentially error prone. + +If this process is thought to be undesirable, the best +choice may be to avoid merging. To avoid the merges +that result from separate working directories, see the +discussion of reserved checkouts (file locking) in +@ref{Multiple developers}. To avoid the merges +resulting from branches, restrict use of branches. + +@node Binary howto +@section How to store binary files + +There are two issues with using @sc{cvs} to store +binary files. The first is that @sc{cvs} by default +converts 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. + +@c FIXME: the third is that one can't do merges with +@c binary files. xref to Multiple Developers and the +@c reserved checkout issues. + +The @samp{-kb} option available with some @sc{cvs} +commands insures that neither line ending conversion +nor keyword expansion will be done. + +Here is an example of how you can create a new file +using the @samp{-kb} flag: + +@example +$ echo '$@splitrcskeyword{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 '$@splitrcskeyword{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 +# @r{For non-unix systems:} +# @r{Copy in a good copy of the file from outside CVS} +$ cvs commit -m "make it binary" kotest +@end example + +@c Trying to describe this for both unix and non-unix +@c in the same description is very confusing. Might +@c want to split the two, or just ditch the unix "shortcut" +@c (unixheads don't do much with binary files, anyway). +@c This used to say "(Try the above example, and do a +@c @code{cat kotest} after every command)". But that +@c only really makes sense for the unix case. +When you check in the file @file{kotest} the file is +not preserved as a binary file, because you did not +check it in as a binary file. 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. If you need to +cope with line endings (that is, you are using +@sc{cvs} on a non-unix system), then you need to +check in a new copy of the file, as shown by the +@code{cvs commit} command above. +On unix, the @code{cvs update -A} command suffices. +@c FIXME: should also describe what the *other users* +@c need to do, if they have checked out copies which +@c have been corrupted by lack of -kb. I think maybe +@c "cvs update -kb" or "cvs +@c update -A" would suffice, although the user who +@c reported this suggested removing the file, manually +@c removing it from CVS/Entries, and then "cvs update" +(Note that you can use @code{cvs log} to determine the default keyword +substitution method for a file and @code{cvs status} to determine +the keyword substitution method for a working copy.) + +However, in using @code{cvs admin -k} to change the +keyword expansion, be aware that the keyword expansion +mode is not version controlled. This means that, for +example, that if you have a text file in old releases, +and a binary file with the same name in new releases, +@sc{cvs} provides no way to check out the file in text +or binary mode depending on what version you are +checking out. There is no good workaround for this +problem. + +You can also set a default for whether @code{cvs add} +and @code{cvs import} treat a file as binary based on +its name; for example you could say that files who +names end in @samp{.exe} are binary. @xref{Wrappers}. +There is currently no way to have @sc{cvs} detect +whether a file is binary based on its contents. The +main difficulty with designing such a feature is that +it is not clear how to distinguish between binary and +non-binary files, and the rules to apply would vary +considerably with the operating system. +@c For example, it would be good on MS-DOS-family OSes +@c for anything containing ^Z to be binary. Having +@c characters with the 8th bit set imply binary is almost +@c surely a bad idea in the context of ISO-8859-* and +@c other such character sets. On VMS or the Mac, we +@c could use the OS's file typing. This is a +@c commonly-desired feature, and something of this sort +@c may make sense. But there are a lot of pitfalls here. +@c +@c Another, probably better, way to tell is to read the +@c file in text mode, write it to a temp file in text +@c mode, and then do a binary mode compare of the two +@c files. If they differ, it is a binary file. This +@c might have problems on VMS (or some other system +@c with several different text modes), but in general +@c should be relatively portable. The only other +@c downside I can think of is that it would be fairly +@c slow, but that is perhaps a small price to pay for +@c not having your files corrupted. Another issue is +@c what happens if you import a text file with bare +@c linefeeds on Windows. Such files will show up on +@c Windows sometimes (I think some native windows +@c programs even write them, on occasion). Perhaps it +@c is reasonable to treat such files as binary; after +@c all it is something of a presumption to assume that +@c the user would want the linefeeds converted to CRLF. + +@c --------------------------------------------------------------------- +@node Multiple developers +@chapter Multiple developers +@cindex Multiple developers +@cindex Team of developers +@cindex File locking +@cindex Locking files +@cindex Working copy +@cindex Reserved checkouts +@cindex Unreserved checkouts +@cindex RCS-style locking + +When more than one person works on a software project +things often get complicated. Often, two people try to +edit the same file simultaneously. One solution, known +as @dfn{file locking} or @dfn{reserved checkouts}, is +to allow only one person to edit each file at a time. +This is the only solution with some version control +systems, including @sc{rcs} and @sc{sccs}. Currently +the usual way to get reserved checkouts with @sc{cvs} +is the @code{cvs admin -l} command (@pxref{admin +options}). This is not as nicely integrated into +@sc{cvs} as the watch features, described below, but it +seems that most people with a need for reserved +checkouts find it adequate. +@c Or "find it better than worrying about implementing +@c nicely integrated reserved checkouts" or ...? +It also may be possible to use the watches +features described below, together with suitable +procedures (not enforced by software), to avoid having +two people edit at the same time. + +@c Our unreserved checkout model might not +@c be quite the same as others. For example, I +@c think that some systems will tend to create a branch +@c in the case where CVS prints "up-to-date check failed". +@c It isn't clear to me whether we should try to +@c explore these subtleties; it could easily just +@c confuse people. +The default model with @sc{cvs} is known as +@dfn{unreserved checkouts}. In this model, developers +can 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. + +@c FIXME? should probably use the word "watch" here, to +@c tie this into the text below and above. +@sc{cvs} also supports mechanisms which facilitate +various kinds of communication, without actually +enforcing rules like reserved checkouts do. + +The rest of this chapter describes how these various +models work, and some of the issues involved in +choosing between them. + +@ignore +Here is a draft reserved checkout design or discussion +of the issues. This seems like as good a place as any +for this. + +Might want a cvs lock/cvs unlock--in which the names +differ from edit/unedit because the network must be up +for these to work. unedit gives an error if there is a +reserved checkout in place (so that people don't +accidentally leave locks around); unlock gives an error +if one is not in place (this is more arguable; perhaps +it should act like unedit in that case). + +On the other hand, might want it so that emacs, +scripts, etc., can get ready to edit a file without +having to know which model is in use. In that case we +would have a "cvs watch lock" (or .cvsrc?) (that is, +three settings, "on", "off", and "lock"). Having cvs +watch lock set would cause a get to record in the CVS +directory which model is in use, and cause "cvs edit" +to change behaviors. We'd want a way to query which +setting is in effect (this would be handy even if it is +only "on" or "off" as presently). If lock is in +effect, then commit would require a lock before +allowing a checkin; chmod wouldn't suffice (might be +debatable--see chmod comment below, in watches--but it +is the way people expect RCS to work and I can't think +of any significant downside. On the other hand, maybe +it isn't worth bothering, because people who are used +to RCS wouldn't think to use chmod anyway). + +Implementation: use file attributes or use RCS +locking. The former avoids more dependence on RCS +behaviors we will need to re-implement as we librarify +RCS, and makes it easier to import/export RCS files (in +that context, want to ignore the locker field). But +note that RCS locks are per-branch, which is the +correct behavior (this is also an issue for the "watch +on" features; they should be per-branch too). + +Here are a few more random notes about implementation +details, assuming "cvs watch lock" and + +CVS/Watched file? Or try to fit this into CVS/Entries somehow? +Cases: (1) file is checked out (unreserved or with watch on) by old +version of @sc{cvs}, now we do something with new one, (2) file is checked +out by new version, now we do something with old one. + +Remote protocol would have a "Watched" analogous to "Mode". Of course +it would apply to all Updated-like requests. How do we keep this +setting up to date? I guess that there wants to be a Watched request, +and the server would send a new one if it isn't up to date? (Ugh--hard +to implement and slows down "cvs -q update"--is there an easier way?) + +"cvs edit"--checks CVS/Watched, and if watch lock, then sends +"edit-lock" request. Which comes back with a Checked-in with +appropriate Watched (off, on, lock, locked, or some such?), or error +message if already locked. + +"cvs commit"--only will commit if off/on/locked. lock is not OK. + +Doc: +note that "cvs edit" must be connected to network if watch lock is in +effect. + +Talk about what to do if someone has locked a file and you want to +edit that file. (breaking locks, or lack thereof). + + +One other idea (which could work along with the +existing "cvs admin -l" reserved checkouts, as well as +the above): + +"cvs editors" could show who has the file locked, if +someone does. + +@end ignore + +@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 +* Choosing a model:: Reserved or unreserved checkouts? +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node File status +@section File status +@cindex File status +@cindex Status of a file + +@c Shouldn't this start with an example or something, +@c introducing the unreserved checkout model? Before we +@c dive into listing states? +Based on what operations you have performed on a +checked out file, and what operations others have +performed to that file in the repository, one can +classify a file in a number of states. The states, as +reported by the @code{status} command, are: + +@c The order of items is chosen to group logically +@c similar outputs together. +@c People who want alphabetical can use the index... +@table @asis +@cindex Up-to-date +@item Up-to-date +The file is identical with the latest revision in the +repository for the branch in use. +@c FIXME: should we clarify "in use"? The answer is +@c sticky tags, and trying to distinguish branch sticky +@c tags from non-branch sticky tags seems rather awkward +@c here. +@c FIXME: What happens with non-branch sticky tags? Is +@c a stuck file "Up-to-date" or "Needs checkout" or what? + +@item Locally Modified +@cindex Locally Modified +You have edited the file, and not yet committed your changes. + +@item Locally Added +@cindex Locally Added +You have added the file with @code{add}, and not yet +committed your changes. +@c There are many cases involving the file being +@c added/removed/modified in the working directory, and +@c added/removed/modified in the repository, which we +@c don't try to describe here. I'm not sure that "cvs +@c status" produces a non-confusing output in most of +@c those cases. + +@item Locally Removed +@cindex Locally Removed +You have removed the file with @code{remove}, and not yet +committed your changes. + +@item Needs Checkout +@cindex Needs Checkout +Someone else has committed a newer revision to the +repository. The name is slightly misleading; you will +ordinarily use @code{update} rather than +@code{checkout} to get that newer revision. + +@item Needs Patch +@cindex Needs Patch +@c See also newb-123j0 in sanity.sh (although that case +@c should probably be changed rather than documented). +Like Needs Checkout, but the @sc{cvs} server will send +a patch rather than the entire file. Sending a patch or +sending an entire file accomplishes the same thing. + +@item Needs Merge +@cindex Needs Merge +Someone else has committed a newer revision to the repository, and you +have also made modifications to the file. + +@item Unresolved Conflict +@cindex Unresolved Conflict +@c FIXCVS - This file status needs to be changed to some more informative +@c text that distinguishes it more clearly from each of the Locally Added, +@c File had conflicts on merge, and Unknown status types, but an exact and +@c succinct wording escapes me at the moment. +A file with the same name as this new file has been added to the repository +from a second workspace. This file will need to be moved out of the way +to allow an @code{update} to complete. + +@item File had conflicts on merge +@cindex File had conflicts on merge +@c is it worth saying that this message was "Unresolved +@c Conflict" in CVS 1.9 and earlier? I'm inclined to +@c think that is unnecessarily confusing to new users. +This is like Locally Modified, except that a previous +@code{update} command gave a conflict. If you have not +already done so, you need to +resolve the conflict as described in @ref{Conflicts example}. + +@item Unknown +@cindex Unknown +@sc{cvs} doesn't know anything about this file. For +example, you have created a new file and have not run +@code{add}. +@c +@c "Entry Invalid" and "Classify Error" are also in the +@c status.c. The latter definitely indicates a CVS bug +@c (should it be worded more like "internal error" so +@c people submit bug reports if they see it?). The former +@c I'm not as sure; I haven't tracked down whether/when it +@c appears in "cvs status" output. + +@end table + +To help clarify the file status, @code{status} also +reports the @code{Working revision} which is the +revision that the file in the working directory derives +from, and the @code{Repository revision} which is the +latest revision in the repository for the branch in +use. +@c FIXME: should we clarify "in use"? The answer is +@c sticky tags, and trying to distinguish branch sticky +@c tags from non-branch sticky tags seems rather awkward +@c here. +@c FIXME: What happens with non-branch sticky tags? +@c What is the Repository Revision there? See the +@c comment at vn_rcs in cvs.h, which is kind of +@c confused--we really need to document better what this +@c field contains. +@c Q: Should we document "New file!" and other such +@c outputs or are they self-explanatory? +@c FIXME: what about the date to the right of "Working +@c revision"? It doesn't appear with client/server and +@c seems unnecessary (redundant with "ls -l") so +@c perhaps it should be removed for non-client/server too? +@c FIXME: Need some examples. +@c FIXME: Working revision can also be something like +@c "-1.3" for a locally removed file. Not at all +@c self-explanatory (and it is possible that CVS should +@c be changed rather than documenting this). + +@c Would be nice to have an @example showing output +@c from cvs status, with comments showing the xref +@c where each part of the output is described. This +@c might fit in nicely if it is desirable to split this +@c node in two; one to introduce "cvs status" and one +@c to list each of the states. +The options to @code{status} are listed in +@ref{Invoking CVS}. For information on its @code{Sticky tag} +and @code{Sticky date} output, see @ref{Sticky tags}. +For information on its @code{Sticky options} output, +see the @samp{-k} option in @ref{update options}. + +You can think of the @code{status} and @code{update} +commands as somewhat complementary. You use +@code{update} to bring your files up to date, and you +can use @code{status} to give you some idea of what an +@code{update} would do (of course, the state of the +repository might change before you actually run +@code{update}). In fact, if you want a command to +display file status in a more brief format than is +displayed by the @code{status} command, you can invoke + +@cindex update, to display file status +@example +$ cvs -n -q update +@end example + +The @samp{-n} option means to not actually do the +update, but merely to display statuses; the @samp{-q} +option avoids printing the name of each directory. For +more information on the @code{update} command, and +these options, see @ref{Invoking CVS}. + +@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{cvs update -d} +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 directory. The +@code{-d} option, not necessary with @code{checkout}, tells @sc{cvs} +that you wish it to create directories added by other developers. + +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"); +@asis{}<<<<<<< driver.c + exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); +@asis{}======= + exit(!!nerr); +@asis{}>>>>>>> 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 + +For your protection, @sc{cvs} will refuse to check in a +file if a conflict occurred and you have not resolved +the conflict. Currently to resolve a conflict, you +must change the timestamp on the file. In previous +versions of @sc{cvs}, you also needed to +insure that the file contains no conflict markers. +Because +your file may legitimately contain conflict markers (that +is, occurrences of @samp{>>>>>>> } at the start of a +line that don't mark a conflict), the current +version of @sc{cvs} will print a warning and proceed to +check in the file. +@c The old behavior was really icky; the only way out +@c was to start hacking on +@c the @code{CVS/Entries} file or other such workarounds. +@c +@c If the timestamp thing isn't considered nice enough, +@c maybe there should be a "cvs resolved" command +@c which clears the conflict indication. For a nice user +@c interface, this should be invoked by an interactive +@c merge tool like emerge rather than by the user +@c directly--such a tool can verify that the user has +@c really dealt with each conflict. + +@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 @file{loginfo} file can be +used to automate this process. +@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, introduction +@c For a discussion of *why* CVS creates locks, see +@c the comment at the start of src/lock.c +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 + +@cindex #cvs.rfl, removing +@cindex #cvs.wfl, removing +@cindex #cvs.lock, removing +@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 in the repository directory mentioned in +the message and remove files which they own whose names +start with @file{#cvs.rfl}, +@file{#cvs.wfl}, or @file{#cvs.lock}. + +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}---which refers to reserved checkouts +(@pxref{Multiple developers}). + +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 +@c the following talks about what one might call commit/update +@c atomicity. +@c Probably also should say something about +@c commit/commit atomicity, that is, "An update will +@c not get partial versions of more than one commit". +@c CVS currently has this property and I guess we can +@c make it a documented feature. +@c For example one person commits +@c a/one.c and b/four.c and another commits a/two.c and +@c b/three.c. Then an update cannot get the new a/one.c +@c and a/two.c and the old b/four.c and b/three.c. +One might hope for the following property: + +@quotation +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 quotation + +@noindent +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 + +@noindent +if someone runs + +@example +cvs ci a/two.c b/three.c +@end example + +@noindent +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. + +@c Some people might ask why CVS does not enforce the +@c rule on chmod, by requiring a cvs edit before a cvs +@c commit. The main reason is that it could always be +@c circumvented--one could edit the file, and +@c then when ready to check it in, do the cvs edit and put +@c in the new contents and do the cvs commit. One +@c implementation note: if we _do_ want to have cvs commit +@c require a cvs edit, we should store the state on +@c whether the cvs edit has occurred in the working +@c directory, rather than having the server try to keep +@c track of what working directories exist. +@c FIXME: should the above discussion be part of the +@c manual proper, somewhere, not just in a comment? +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{-lR}] [@var{files}]@dots{} + +@cindex Read-only files, and watches +Specify that developers should run @code{cvs edit} +before editing @var{files}. @sc{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, @sc{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. +The @code{-R} option can be used to force recursion if the @code{-l} +option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}). + +If @var{files} is omitted, it defaults to the current directory. + +@cindex watch off (subcommand) +@end deffn + +@deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{} + +Do not create @var{files} read-only on checkout; thus, +developers will not be reminded to use @code{cvs edit} +and @code{cvs unedit}. +@ignore +@sc{cvs} will check out @var{files} +read-write as usual, unless other permissions override +due to the @code{PreservePermissions} option being +enabled in the @file{config} administrative file +(@pxref{Special Files}, @pxref{config}) +@end ignore + +The @var{files} and options 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}, to remind developers to use the @code{cvs edit} +command. + +@cindex watch add (subcommand) +@deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{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 @sc{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 watched file. + +@item commit +Another user has committed changes to one of the named @var{files}. + +@item unedit +Another user has abandoned editing a file (other than by committing changes). +They can do this in several ways, by: + +@itemize @bullet + +@item +applying the @code{cvs unedit} command (described below) to the file + +@item +applying the @code{cvs release} command (@pxref{release}) to the file's parent directory +(or recursively to a directory more than one level up) + +@item +deleting the file and allowing @code{cvs update} to recreate it + +@end itemize + +@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 options are processed as for +@code{cvs watch on}. + +@end deffn + + +@cindex watch remove (subcommand) +@deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{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 + +@cindex notify (admin file) +When the conditions exist for notification, @sc{cvs} +calls the @file{notify} administrative file. Edit +@file{notify} as one edits the other administrative +files (@pxref{Intro administrative files}). This +file follows the usual conventions for administrative +files (@pxref{syntax}), where each line is a regular +expression followed by a command to execute. The +command should contain a single occurrence of @samp{%s} +which will be replaced by the user to notify; the rest +of the information regarding the notification will be +supplied to the command on standard input. The +standard thing to put in the @code{notify} file is the +single line: + +@example +ALL mail %s -s "CVS notification" +@end example + +@noindent +This causes users to be notified by electronic mail. +@c FIXME: should it be this hard to set up this +@c behavior (and the result when one fails to do so, +@c silent failure to notify, so non-obvious)? Should +@c CVS give a warning if no line in notify matches (and +@c document the use of "DEFAULT :" for the case where +@c skipping the notification is indeed desired)? + +@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). + +@sc{cvs} does not notify you for your own changes. +Currently this check is done based on whether the user +name of the person taking the action which triggers +notification matches the user name of the person +getting notification. In fact, in general, the watches +features only track one edit by each user. It probably +would be more useful if watches tracked each working +directory separately, so this behavior might be worth +changing. +@c "behavior might be worth changing" is an effort to +@c point to future directions while also not promising +@c that "they" (as in "why don't they fix CVS to....") +@c will do this. +@c one implementation issue is identifying whether a +@c working directory is same or different. Comparing +@c pathnames/hostnames is hopeless, but having the server +@c supply a serial number which the client stores in the +@c CVS directory as a magic cookie should work. + +@node Editing files +@subsection How to edit a file which is being watched + +@cindex Checkout, as term for getting ready to edit +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. Some systems +call this a @dfn{checkout}, but @sc{cvs} uses that term +for obtaining a copy of the sources (@pxref{Getting the +source}), an operation which those systems call a +@dfn{get} or a @dfn{fetch}. +@c Issue to think about: should we transition CVS +@c towards the "get" terminology? "cvs get" is already a +@c synonym for "cvs checkout" and that section of the +@c manual refers to "Getting the source". If this is +@c done, needs to be done gingerly (for example, we should +@c still accept "checkout" in .cvsrc files indefinitely +@c even if the CVS's messages are changed from "cvs checkout: " +@c to "cvs get: "). +@c There is a concern about whether "get" is not as +@c good for novices because it is a more general term +@c than "checkout" (and thus arguably harder to assign +@c a technical meaning for). + +@cindex edit (subcommand) +@deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} + +Prepare to edit the working files @var{files}. @sc{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 options as the +@code{cvs watch add} command, and establishes a temporary watch for the +user on @var{files}; @sc{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 the options are processed as for the @code{cvs +watch} commands. + +@ignore +@strong{Caution: If the @code{PreservePermissions} +option is enabled in the repository (@pxref{config}), +@sc{cvs} will not change the permissions on any of the +@var{files}. The reason for this change is to ensure +that using @samp{cvs edit} does not interfere with the +ability to store file permissions in the @sc{cvs} +repository.} +@end ignore + +@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) +@cindex Abandoning work +@cindex Reverting to repository version +@deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{} + +Abandon work on the working files @var{files}, and revert them to the +repository versions on which they are based. @sc{cvs} makes those +@var{files} read-only for which users have requested notification using +@code{cvs watch on}. @sc{cvs} notifies users who have requested @code{unedit} +notification for any of @var{files}. + +The @var{files} and options are processed as for the +@code{cvs watch} commands. + +If watches are not in use, the @code{unedit} command +probably does not work, and the way to revert to the +repository version is with the command @code{cvs update -C file} +(@pxref{update}). +The meaning is +not precisely the same; the latter may also +bring in some changes which have been made in the +repository since the last time you updated. +@c It would be a useful enhancement to CVS to make +@c unedit work in the non-watch case as well. +@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 successfully 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{-lR}] [@var{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 options are processed as for the +@code{cvs watch} commands. + +@end deffn + + +@cindex editors (subcommand) +@deffn Command {cvs editors} [@code{-lR}] [@var{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 options 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 the +following (all on one line): + +@example +cvs update: cannot open CVS/Entries for reading: +No such file or directory +@end example + +@noindent +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. + +@node Choosing a model +@section Choosing between reserved or unreserved checkouts +@cindex Choosing, reserved or unreserved checkouts + +Reserved and unreserved checkouts each have pros and +cons. Let it be said that a lot of this is a matter of +opinion or what works given different groups' working +styles, but here is a brief description of some of the +issues. 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. + +Reserved checkouts 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. Also, it is common for someone to take out a +lock on a file, because they are planning to edit it, +but then forget to release the lock. + +@c "many groups"? specifics? cites to papers on this? +@c some way to weasel-word it a bit more so we don't +@c need facts :-)? +People, especially people who are familiar with +reserved checkouts, often wonder how often conflicts +occur if unreserved checkouts are used, and how +difficult they are to resolve. The experience with +many groups is that they occur rarely and usually are +relatively straightforward to resolve. + +The rarity of serious conflicts may be surprising, until one realizes +that they occur only when two developers disagree on the proper design +for a given section of code; such a disagreement suggests that the +team has not been communicating properly in the first place. In order +to collaborate under @emph{any} source management regimen, developers +must agree on the general design of the system; given this agreement, +overlapping changes are usually straightforward to merge. + +In some cases unreserved checkouts are clearly +inappropriate. If no merge tool exists for the kind of +file you are managing (for example word processor files +or files edited by Computer Aided Design programs), and +it is not desirable to change to a program which uses a +mergeable data format, then resolving conflicts is +going to be unpleasant enough that you generally will +be better off to simply avoid the conflicts instead, by +using reserved checkouts. + +The watches features described above in @ref{Watches} +can be considered to be an intermediate model between +reserved checkouts and unreserved checkouts. When you +go to edit a file, it is possible to find out who else +is editing it. And rather than having the system +simply forbid both people editing the file, it can tell +you what the situation is and let you figure out +whether it is a problem in that particular case or not. +Therefore, for some groups it can be considered the +best of both the reserved checkout and unreserved +checkout worlds. + +@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 Committing, 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 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 a working +directory 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{cvs} can use 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:: Keywords +* Using keywords:: Using keywords +* Avoiding substitution:: Avoiding substitution +* Substitution modes:: Substitution modes +* Log keyword:: Problems with the $@splitrcskeyword{Log}$ keyword. +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Keyword list +@section Keyword List +@cindex Keyword List + +@c FIXME: need some kind of example here I think, +@c perhaps in a +@c "Keyword intro" node. The intro in the "Keyword +@c substitution" node itself seems OK, but to launch +@c into a list of the keywords somehow seems too abrupt. + +This is a list of the keywords: + +@table @code +@cindex Author keyword +@item $@splitrcskeyword{Author}$ +The login name of the user who checked in the revision. + +@cindex Date keyword +@item $@splitrcskeyword{Date}$ +The date and time (UTC) the revision was checked in. + +@cindex Header keyword +@item $@splitrcskeyword{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 $@splitrcskeyword{Id}$ +Same as @code{$@splitrcskeyword{Header}$}, except that the @sc{rcs} +filename is without a path. + +@cindex Name keyword +@item $@splitrcskeyword{Name}$ +Tag name used to check out this file. The keyword is +expanded only if one checks out with an explicit tag +name. For example, when running the command @code{cvs +co -r first}, the keyword expands to @samp{Name: first}. + +@cindex Locker keyword +@item $@splitrcskeyword{Locker}$ +The login name of the user who locked the revision +(empty if not locked, which is the normal case unless +@code{cvs admin -l} is in use). + +@cindex Log keyword +@item $@splitrcskeyword{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{$@splitrcskeyword{Log}:@dots{}$}. +Each new line is prefixed with the same string which +precedes the @code{$Log} keyword. For example, if the +file contains: + +@example + /* Here is what people have been up to: + * + * $@splitrcskeyword{Log}: frob.c,v $ + * Revision 1.1 1997/01/03 14:23:51 joe + * Add the superfrobnicate option + * + */ +@end example + +@noindent +then additional lines which are added when expanding +the @code{$Log} keyword will be preceded by @samp{ * }. +Unlike previous versions of @sc{cvs} and @sc{rcs}, the +@dfn{comment leader} from the @sc{rcs} file is not used. +The @code{$Log} 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 $@splitrcskeyword{RCSfile}$ +The name of the RCS file without a path. + +@cindex Revision keyword +@item $@splitrcskeyword{Revision}$ +The revision number assigned to the revision. + +@cindex Source keyword +@item $@splitrcskeyword{Source}$ +The full pathname of the RCS file. + +@cindex State keyword +@item $@splitrcskeyword{State}$ +The state assigned to the revision. States can be +assigned with @code{cvs admin -s}---see @ref{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{$@splitrcskeyword{Id}$}, inside the +file, and commit the file. @sc{cvs} will automatically (Or, +more accurately, as part of the update run that +automatically happens after a commit.) +expand the string as part of the commit operation. + +It is common to embed the @code{$@splitrcskeyword{Id}$} string in +the source files so that it gets passed through to +generated files. For example, if you are managing +computer program source code, you might include a +variable which is initialized to contain that string. +Or some C compilers may provide a @code{#pragma ident} +directive. Or a document management system might +provide a way to pass a string through to generated +files. + +@c Would be nice to give an example, but doing this in +@c portable C is not possible and the problem with +@c picking any one language (VMS HELP files, Ada, +@c troff, whatever) is that people use CVS for all +@c kinds of files. + +@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: + $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ +$ gcc samp.c +$ ident a.out +a.out: + $@splitrcskeyword{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 keyword with the +magic @sc{sccs} phrase, like this: + +@example +static char *id="@@(#) $@splitrcskeyword{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{$@splitrcskeyword{Author}$} to appear inside a file without +@sc{cvs} interpreting it as a keyword and expanding it +into something like @samp{$@splitrcskeyword{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 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{$@splitrcskeyword{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 Keyword substitution, changing modes +@cindex -k (keyword substitution) +@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 @samp{-k} or @samp{-A} options to @code{cvs +checkout} or @code{cvs update}. +@code{cvs diff} and @code{cvs rdiff} also +have @samp{-k} options. +For some examples, +see @ref{Binary files}, and @ref{Merging and keywords}. +@c The fact that -A is overloaded to mean both reset +@c sticky options and reset sticky tags/dates is +@c somewhat questionable. Perhaps there should be +@c separate options to reset sticky options (e.g. -k +@c A") and tags/dates (someone suggested -r HEAD could +@c do this instead of setting a sticky tag of "HEAD" +@c as in the status quo but I haven't thought much +@c about that idea. Of course -r .reset or something +@c could be coined if this needs to be a new option). +@c On the other hand, having -A mean "get things back +@c into the state after a fresh checkout" has a certain +@c appeal, and maybe there is no sufficient reason for +@c creeping featurism in this area. + +The modes available are: + +@table @samp +@item -kkv +Generate keyword strings using the default form, e.g. +@code{$@splitrcskeyword{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. +The locker's name is only relevant if @code{cvs admin +-l} is in use. + +@item -kk +Generate only keyword names in keyword strings; omit +their values. For example, for the @code{Revision} +keyword, generate the string @code{$@splitrcskeyword{Revision}$} +instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. This option +is useful to ignore differences due to keyword +substitution when comparing different revisions of a +file (@pxref{Merging and keywords}). + +@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{$@splitrcskeyword{Revision}: 1.1 $} instead of +@code{$@splitrcskeyword{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{$@splitrcskeyword{Revision}: 5.7 $}. +This can help generate files in programming languages +where it is hard to strip keyword delimiters like +@code{$@splitrcskeyword{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 $@splitrcskeyword{Log}$ keyword. + +The @code{$@splitrcskeyword{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{$@splitrcskeyword{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{cvs} is not good at +handling @code{$@splitrcskeyword{Log}$} entries when a branch is +merged onto the main trunk. Conflicts often result +from the merging operation. +@c Might want to check whether the CVS implementation +@c of RCS_merge has this problem the same way rcsmerge +@c does. I would assume so.... + +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{$@splitrcskeyword{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 Tracking sources +@chapter Tracking third-party sources +@cindex Third-party sources +@cindex Tracking sources + +@c FIXME: Need discussion of added and removed files. +@c FIXME: This doesn't really adequately introduce the +@c concepts of "vendor" and "you". They don't *have* +@c to be separate organizations or separate people. +@c We want a description which is somewhat more based on +@c the technical issues of which sources go where, but +@c also with enough examples of how this relates to +@c relationships like customer-supplier, developer-QA, +@c maintainer-contributor, or whatever, to make it +@c seem concrete. +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. When you import a new file, +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 for the first time +* Update imports:: Updating with the import command +* Reverting local changes:: Reverting to the latest vendor release +* Binary files in imports:: Binary files require special handling +* Keywords in imports:: Keyword substitution might be undesirable +* Multiple vendor branches:: What if you get sources from several places? +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node First import +@section Importing for the first time +@cindex Importing modules + +@c Should mention naming conventions for vendor tags, +@c release tags, and perhaps directory names. +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---see @ref{Multiple vendor branches}.). The +@dfn{release tags} are symbolic names for a particular +release, such as @samp{FSF_0_04}. + +@c I'm not completely sure this belongs here. But +@c we need to say it _somewhere_ reasonably obvious; it +@c is a common misconception among people first learning CVS +Note that @code{import} does @emph{not} change the +directory in which you invoke it. In particular, it +does not set up that directory as a @sc{cvs} working +directory; if you want to work with the sources import +them first and then check them out into a different +directory (@pxref{Getting the source}). + +@cindex wdiff (import example) +Suppose you have the sources to a program called +@code{wdiff} in a directory @file{wdiff-0.04}, +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 +$ 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 FIXME: Need to say where fsf/wdiff comes from. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Update imports +@section Updating 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 + +@strong{WARNING: If you use a release tag that already exists in one of the +repository archives, files removed by an import may not be detected.} + +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: + +@c FIXME: why "wdiff" here and "fsf/wdiff" in the +@c "import"? I think the assumption is that one has +@c "wdiff fsf/wdiff" or some such in modules, but it +@c would be better to not use modules in this example. +@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. + +However, it is much better to use the two release tags rather than using +a date on the branch as suggested above: + +@example +$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff +@end example + +@noindent +The reason this is better is that +using a date, as suggested above, assumes that you do +not import more than one release of a product per day. +More importantly, using the release tags allows @sc{cvs} to detect files +that were removed between the two vendor releases and mark them for +removal. Since @code{import} has no way to detect removed files, you +should do a merge like this even if @code{import} doesn't tell you to. + +@node Reverting local changes +@section Reverting to the latest vendor release + +You can also revert local changes completely and return +to the latest vendor release by changing the `head' +revision back to the vendor branch on all files. For +example, if you have a checked-out copy of the sources +in @file{~/work.d/wdiff}, and you want to revert to the +vendor's version for all the files in that directory, +you would type: + +@example +$ cd ~/work.d/wdiff +$ cvs admin -bFSF_DIST . +@end example + +@noindent +You must specify the @samp{-bFSF_DIST} without any space +after the @samp{-b}. @xref{admin options}. + +@node Binary files in imports +@section How to handle binary files with cvs import + +Use the @samp{-k} wrapper option to tell import which +files are binary. @xref{Wrappers}. + +@node Keywords in imports +@section How to handle keyword substitution with cvs import + +The sources which you are importing may contain +keywords (@pxref{Keyword substitution}). For example, +the vendor may use @sc{cvs} or some other system +which uses similar keyword expansion syntax. If you +just import the files in the default fashion, then +the keyword expansions supplied by the vendor will +be replaced by keyword expansions supplied by your +own copy of @sc{cvs}. It may be more convenient to +maintain the expansions supplied by the vendor, so +that this information can supply information about +the sources that you imported from the vendor. + +To maintain the keyword expansions supplied by the +vendor, supply the @samp{-ko} option to @code{cvs +import} the first time you import the file. +This will turn off keyword expansion +for that file entirely, so if you want to be more +selective you'll have to think about what you want +and use the @samp{-k} option to @code{cvs update} or +@code{cvs admin} as appropriate. +@c Supplying -ko to import if the file already existed +@c has no effect. Not clear to me whether it should +@c or not. + +@node Multiple vendor branches +@section Multiple vendor branches + +All the examples so far assume that there is only one +vendor from which you are getting sources. In some +situations you might get sources from a variety of +places. For example, suppose that you are dealing with +a project where many different people and teams are +modifying the software. There are a variety of ways to +handle this, but in some cases you have a bunch of +source trees lying around and what you want to do more +than anything else is just to all put them in @sc{cvs} so +that you at least have them in one place. + +For handling situations in which there may be more than +one vendor, you may specify the @samp{-b} option to +@code{cvs import}. It takes as an argument the vendor +branch to import to. The default is @samp{-b 1.1.1}. + +For example, suppose that there are two teams, the red +team and the blue team, that are sending you sources. +You want to import the red team's efforts to branch +1.1.1 and use the vendor tag RED. You want to import +the blue team's efforts to branch 1.1.3 and use the +vendor tag BLUE. So the commands you might use are: + +@example +$ cvs import dir RED RED_1-0 +$ cvs import -b 1.1.3 dir BLUE BLUE_1-5 +@end example + +Note that if your vendor tag does not match your +@samp{-b} option, @sc{cvs} will not detect this case! For +example, + +@example +$ cvs import -b 1.1.3 dir RED RED_1-0 +@end example + +@noindent +Be careful; this kind of mismatch is sure to sow +confusion or worse. I can't think of a useful purpose +for the ability to specify a mismatch here, but if you +discover such a use, don't. @sc{cvs} is likely to make this +an error in some future release. + +@c Probably should say more about the semantics of +@c multiple branches. What about the default branch? +@c What about joining (perhaps not as useful with +@c multiple branches, or perhaps it is. Either way +@c should be mentioned). + +@c I'm not sure about the best location for this. In +@c one sense, it might belong right after we've introduced +@c CVS's basic version control model, because people need +@c to figure out builds right away. The current location +@c is based on the theory that it kind of akin to the +@c "Revision management" section. +@node Builds +@chapter How your build system interacts with CVS +@cindex Builds +@cindex make + +As mentioned in the introduction, @sc{cvs} does not +contain software for building your software from source +code. This section describes how various aspects of +your build system might interact with @sc{cvs}. + +@c Is there a way to discuss this without reference to +@c tools other than CVS? I'm not sure there is; I +@c wouldn't think that people who learn CVS first would +@c even have this concern. +One common question, especially from people who are +accustomed to @sc{rcs}, is how to make their build get +an up to date copy of the sources. The answer to this +with @sc{cvs} is two-fold. First of all, since +@sc{cvs} itself can recurse through directories, there +is no need to modify your @file{Makefile} (or whatever +configuration file your build tool uses) to make sure +each file is up to date. Instead, just use two +commands, first @code{cvs -q update} and then +@code{make} or whatever the command is to invoke your +build tool. Secondly, you do not necessarily +@emph{want} to get a copy of a change someone else made +until you have finished your own work. One suggested +approach is to first update your sources, then +implement, build and +test the change you were thinking of, and then commit +your sources (updating first if necessary). By +periodically (in between changes, using the approach +just described) updating your entire tree, you ensure +that your sources are sufficiently up to date. + +@cindex Bill of materials +One common need is to record which versions of which +source files went into a particular build. This kind +of functionality is sometimes called @dfn{bill of +materials} or something similar. The best way to do +this with @sc{cvs} is to use the @code{tag} command to +record which versions went into a given build +(@pxref{Tags}). + +Using @sc{cvs} in the most straightforward manner +possible, each developer will have a copy of the entire +source tree which is used in a particular build. If +the source tree is small, or if developers are +geographically dispersed, this is the preferred +solution. In fact one approach for larger projects is +to break a project down into smaller +@c I say subsystem instead of module because they may or +@c may not use the modules file. +separately-compiled subsystems, and arrange a way of +releasing them internally so that each developer need +check out only those subsystems which they are +actively working on. + +Another approach is to set up a structure which allows +developers to have their own copies of some files, and +for other files to access source files from a central +location. Many people have come up with some such a +@c two such people are paul@sander.cupertino.ca.us (for +@c a previous employer) +@c and gunnar.tornblom@se.abb.com (spicm and related tools), +@c but as far as I know +@c no one has nicely packaged or released such a system (or +@c instructions for constructing one). +system using features such as the symbolic link feature +found in many operating systems, or the @code{VPATH} +feature found in many versions of @code{make}. One build +tool which is designed to help with this kind of thing +is Odin (see +@code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}). +@c Should we be saying more about Odin? Or how you use +@c it with CVS? Also, the Prime Time Freeware for Unix +@c disk (see http://www.ptf.com/) has Odin (with a nice +@c paragraph summarizing it on the web), so that might be a +@c semi-"official" place to point people. +@c +@c Of course, many non-CVS systems have this kind of +@c functionality, for example OSF's ODE +@c (http://www.osf.org/ode/) or mk +@c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html +@c He has changed providers in the past; a search engine search +@c for "Peter Ziobrzynski" probably won't get too many +@c spurious hits :-). A more stable URL might be +@c ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure +@c there is any point in mentioning them here unless they +@c can work with CVS. + +@c --------------------------------------------------------------------- +@node Special Files +@chapter Special Files + +@cindex Special files +@cindex Device nodes +@cindex Ownership, saving in CVS +@cindex Permissions, saving in CVS +@cindex Hard links +@cindex Symbolic links + +In normal circumstances, @sc{cvs} works only with regular +files. Every file in a project is assumed to be +persistent; it must be possible to open, read and close +them; and so on. @sc{cvs} also ignores file permissions and +ownerships, leaving such issues to be resolved by the +developer at installation time. In other words, it is +not possible to "check in" a device into a repository; +if the device file cannot be opened, @sc{cvs} will refuse to +handle it. Files also lose their ownerships and +permissions during repository transactions. + +@ignore +If the configuration variable @code{PreservePermissions} +(@pxref{config}) is set in the repository, @sc{cvs} will +save the following file characteristics in the +repository: + +@itemize @bullet +@item user and group ownership +@item permissions +@item major and minor device numbers +@item symbolic links +@item hard link structure +@end itemize + +Using the @code{PreservePermissions} option affects the +behavior of @sc{cvs} in several ways. First, some of the +new operations supported by @sc{cvs} are not accessible to +all users. In particular, file ownership and special +file characteristics may only be changed by the +superuser. When the @code{PreservePermissions} +configuration variable is set, therefore, users will +have to be `root' in order to perform @sc{cvs} operations. + +When @code{PreservePermissions} is in use, some @sc{cvs} +operations (such as @samp{cvs status}) will not +recognize a file's hard link structure, and so will +emit spurious warnings about mismatching hard links. +The reason is that @sc{cvs}'s internal structure does not +make it easy for these operations to collect all the +necessary data about hard links, so they check for file +conflicts with inaccurate data. + +A more subtle difference is that @sc{cvs} considers a file +to have changed only if its contents have changed +(specifically, if the modification time of the working +file does not match that of the repository's file). +Therefore, if only the permissions, ownership or hard +linkage have changed, or if a device's major or minor +numbers have changed, @sc{cvs} will not notice. In order to +commit such a change to the repository, you must force +the commit with @samp{cvs commit -f}. This also means +that if a file's permissions have changed and the +repository file is newer than the working copy, +performing @samp{cvs update} will silently change the +permissions on the working copy. + +Changing hard links in a @sc{cvs} repository is particularly +delicate. Suppose that file @file{foo} is linked to +file @file{old}, but is later relinked to file +@file{new}. You can wind up in the unusual situation +where, although @file{foo}, @file{old} and @file{new} +have all had their underlying link patterns changed, +only @file{foo} and @file{new} have been modified, so +@file{old} is not considered a candidate for checking +in. It can be very easy to produce inconsistent +results this way. Therefore, we recommend that when it +is important to save hard links in a repository, the +prudent course of action is to @code{touch} any file +whose linkage or status has changed since the last +checkin. Indeed, it may be wise to @code{touch *} +before each commit in a directory with complex hard +link structures. + +It is worth noting that only regular files may +be merged, for reasons that hopefully are obvious. If +@samp{cvs update} or @samp{cvs checkout -j} attempts to +merge a symbolic link with a regular file, or two +device files for different kinds of devices, @sc{cvs} will +report a conflict and refuse to perform the merge. At +the same time, @samp{cvs diff} will not report any +differences between these files, since no meaningful +textual comparisons can be made on files which contain +no text. + +The @code{PreservePermissions} features do not work +with client/server @sc{cvs}. Another limitation is +that hard links must be to other files within the same +directory; hard links across directories are not +supported. +@end ignore + +@c --------------------------------------------------------------------- +@c ----- START MAN 1 ----- +@node CVS commands +@appendix Guide to CVS commands + +This appendix describes the overall structure of +@sc{cvs} commands, and describes some commands in +detail (others are described elsewhere; for a quick +reference to @sc{cvs} commands, @pxref{Invoking CVS}). +@c The idea is that we want to move the commands which +@c are described here into the main body of the manual, +@c in the process reorganizing the manual to be +@c organized around what the user wants to do, not +@c organized around CVS commands. +@c +@c Note that many users do expect a manual which is +@c organized by command. At least some users do. +@c One good addition to the "organized by command" +@c section (if any) would be "see also" links. +@c The awk manual might be a good example; it has a +@c reference manual which is more verbose than Invoking +@c CVS but probably somewhat less verbose than CVS +@c Commands. + +@menu +* Structure:: Overall structure of CVS commands +* Exit status:: Indicating CVS's success or failure +* ~/.cvsrc:: Default options with the ~/.cvsrc 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 files and directories to the repository +* admin:: Administration +* annotate:: What revision modified each line of a file? +* checkout:: Checkout sources for editing +* commit:: Check files into the repository +* diff:: Show differences 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:: Show log messages for files +* rdiff:: 'patch' format diffs between releases +* release:: Indicate that a directory is no longer in use +* remove:: Remove files from active development +* 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 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 name of the @sc{cvs} program. + +@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}. +When given as a @code{cvs_option}, some options only +affect some of the commands. When given as a +@code{command_option} it may have a different meaning, and +be accepted by more commands. In other words, do not +take the above categorization too seriously. Look at +the documentation instead. + +@node Exit status +@appendixsec CVS's exit status +@cindex Exit status, of CVS + +@sc{cvs} can indicate to the calling environment whether it +succeeded or failed by setting its @dfn{exit status}. +The exact way of testing the exit status will vary from +one operating system to another. For example in a unix +shell script the @samp{$?} variable will be 0 if the +last command returned a successful exit status, or +greater than 0 if the exit status indicated failure. + +If @sc{cvs} is successful, it returns a successful status; +if there is an error, it prints an error message and +returns a failure status. The one exception to this is +the @code{cvs diff} command. It will return a +successful status if it found no differences, or a +failure status if there were differences or if there +was an error. Because this behavior provides no good +way to detect errors, in the future it is possible that +@code{cvs diff} will be changed to behave like the +other @sc{cvs} commands. +@c It might seem like checking whether cvs -q diff +@c produces empty or non-empty output can tell whether +@c there were differences or not. But it seems like +@c there are cases with output but no differences +@c (testsuite basica-8b). It is not clear to me how +@c useful it is for a script to be able to check +@c whether there were differences. +@c FIXCVS? In previous versions of CVS, cvs diff +@c returned 0 for no differences, 1 for differences, or +@c 2 for errors. Is this behavior worth trying to +@c bring back (but what does it mean for VMS?)? + +@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 +@file{.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 -uN +rdiff -u +update -Pd +checkout -P +release -d +@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 + +@noindent +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 +@item --allow-root=@var{rootdir} +Specify legal @sc{cvsroot} directory. See +@ref{Password authentication server}. + +@cindex Authentication, stream +@cindex Stream authentication +@item -a +Authenticate all communication between the client and +the server. Only has an effect on the @sc{cvs} client. +As of this writing, this is only implemented when using +a GSSAPI connection (@pxref{GSSAPI authenticated}). +Authentication prevents certain sorts of attacks +involving hijacking the active @sc{tcp} connection. +Enabling authentication does not enable encryption. + +@cindex RCSBIN, overriding +@cindex Overriding RCSBIN +@item -b @var{bindir} +In @sc{cvs} 1.9.18 and older, this specified that +@sc{rcs} programs are in the @var{bindir} directory. +Current versions of @sc{cvs} do not run @sc{rcs} +programs; for compatibility this option is accepted, +but it does nothing. + +@cindex TMPDIR, overriding +@cindex Overriding TMPDIR +@item -T @var{tempdir} +Use @var{tempdir} as the directory where temporary files are +located. Overrides the setting of the @code{$TMPDIR} environment +variable and any precompiled directory. This parameter should be +specified as an absolute pathname. +(When running client/server, @samp{-T} affects only the local process; +specifying @samp{-T} for the client has no effect on the server and +vice versa.) + +@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. See @ref{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. For more information, see +@ref{Committing your changes}. + +@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{log}, +you may need to use @samp{-f} to show the tag names. + +@item -H +@itemx --help +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 overall help for +@sc{cvs}, including a list of other help options. +@c It seems to me it is better to document it this way +@c rather than trying to update this documentation +@c every time that we add a --help-foo option. But +@c perhaps that is confusing... + +@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. + +Note that @sc{cvs} will not necessarily produce exactly +the same output as without @samp{-n}. In some cases +the output will be the same, but in other cases +@sc{cvs} will skip some of the processing that would +have been required to produce the exact same output. + +@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, and -r +@item -r +Make new working 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 +@item --version +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. +@c Note that -w only overrides -r and CVSREAD; it has +@c no effect on files which are readonly because of +@c "cvs watch on". My guess is that is the way it +@c should be (or should "cvs -w get" on a watched file +@c be the same as a get and a cvs edit?), but I'm not +@c completely sure whether to document it this way. + +@item -x +@cindex Encryption +Encrypt all communication between the client and the +server. Only has an effect on the @sc{cvs} client. As +of this writing, this is only implemented when using a +GSSAPI connection (@pxref{GSSAPI authenticated}) or a +Kerberos connection (@pxref{Kerberos authenticated}). +Enabling encryption implies that message traffic is +also authenticated. Encryption support is not +available by default; it must be enabled using a +special configure option, @file{--enable-encryption}, +when you build @sc{cvs}. + +@item -z @var{gzip-level} +@cindex Compression +@cindex Gzip +Set the compression level. +Valid levels are 1 (high speed, low compression) to +9 (low speed, high compression), or 0 to disable +compression (the default). +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{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}). + +@samp{-D} is available with the @code{annotate}, @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}). + +@c What other formats should we accept? I don't want +@c to start accepting a whole mess of non-standard +@c new formats (there are a lot which are in wide use in +@c one context or another), but practicality does +@c dictate some level of flexibility. +@c * POSIX.2 (e.g. touch, ls output, date) and other +@c POSIX and/or de facto unix standards (e.g. at). The +@c practice here is too inconsistent to be of any use. +@c * VMS dates. This is not a formal standard, but +@c there is a published specification (see SYS$ASCTIM +@c and SYS$BINTIM in the _VMS System Services Reference +@c Manual_), it is implemented consistently in VMS +@c utilities, and VMS users will expect CVS running on +@c VMS to support this format (and if we're going to do +@c that, better to make CVS support it on all +@c platforms. Maybe). +@c +@c NOTE: The tar manual has some documentation for +@c getdate.y (just for our info; we don't want to +@c attempt to document all the formats accepted by +@c getdate.y). +@c +@c One more note: In output, CVS should consistently +@c use one date format, and that format should be one that +@c it accepts in input as well. The former isn't +@c really true (see survey below), and I'm not +@c sure that either of those formats is accepted in +@c input. +@c +@c cvs log +@c current 1996/01/02 13:45:31 +@c Internet 02 Jan 1996 13:45:31 UT +@c ISO 1996-01-02 13:45:31 +@c cvs ann +@c current 02-Jan-96 +@c Internet-like 02 Jan 96 +@c ISO 96-01-02 +@c cvs status +@c current Tue Jun 11 02:54:53 1996 +@c Internet [Tue,] 11 Jun 1996 02:54:53 +@c ISO 1996-06-11 02:54:53 +@c note: date possibly should be omitted entirely for +@c other reasons. +@c cvs editors +@c current Tue Jun 11 02:54:53 1996 GMT +@c cvs history +@c current 06/11 02:54 +0000 +@c any others? +@c There is a good chance the proper solution has to +@c involve at least some level of letting the user +@c decide which format (with the default being the +@c formats CVS has always used; changing these might be +@c _very_ disruptive since scripts may very well be +@c parsing them). +@c +@c Another random bit of prior art concerning dates is +@c the strptime function which takes templates such as +@c "%m/%d/%y", and apparent a variant of getdate() +@c which also honors them. See +@c X/Open CAE Specification, System Interfaces and +@c Headers Issue 4, Version 2 (September 1994), in the +@c entry for getdate() on page 231 + +@cindex Timezone, in input +@cindex Zone, time, in input +A wide variety of date formats are supported by +@sc{cvs}. The most standard ones are ISO8601 (from the +International Standards Organization) and the Internet +e-mail standard (specified in RFC822 as amended by +RFC1123). + +@c Probably should be doing more to spell out just what +@c the rules are, rather than just giving examples. +@c But I want to keep this simple too. +@c So I don't know.... +@c A few specific issues: (1) Maybe should reassure +@c people that years after 2000 +@c work (they are in the testsuite, so they do indeed +@c work). (2) What do two digit years +@c mean? Where do we accept them? (3) Local times can +@c be ambiguous or nonexistent if they fall during the +@c hour when daylight savings time goes into or out of +@c effect. Pretty obscure, so I'm not at all sure we +@c should be documenting the behavior in that case. +ISO8601 dates have many variants but a few examples +are: + +@example +1972-09-24 +1972-09-24 20:05 +@end example +@c I doubt we really accept all ISO8601 format dates +@c (for example, decimal hours like 1972-09-24 20,2) +@c I'm not sure we should, many of them are pretty +@c bizarre and it has lots of gratuitous multiple ways +@c to specify the same thing. + +There are a lot more ISO8601 date formats, and @sc{cvs} +accepts many of them, but you probably don't want to +hear the @emph{whole} long story :-). + +@c Citing a URL here is kind of problematic given how +@c much they change and people who have old versions of +@c this manual, but in case we want to reinstate an +@c ISO8601 URL, a few are: +@c http://www.saqqara.demon.co.uk/datefmt.htm +@c http://www.cl.cam.ac.uk/~mgk25/iso-time.html +@c Citing some other ISO8601 source is probably even +@c worse :-). + +In addition to the dates allowed in Internet e-mail +itself, @sc{cvs} also allows some of the fields to be +omitted. For example: +@c FIXME: Need to figure out better, and document, +@c what we want to allow the user to omit. +@c NOTE: "omit" does not imply "reorder". +@c FIXME: Need to cite a web page describing how to get +@c RFC's. + +@example +24 Sep 1972 20:05 +24 Sep +@end example + +The date is interpreted as being in the +local timezone, unless a specific timezone is +specified. + +These two date formats are preferred. However, +@sc{cvs} currently accepts a wide variety of other date +formats. They are intentionally not documented here in +any detail, and future versions of @sc{cvs} might not +accept all of them. +@c We should document and testsuite "now" and +@c "yesterday". "now" is mentioned in the FAQ and +@c "yesterday" is mentioned in this document (and the +@c message from "cvs import" suggesting a merge +@c command). What else? Probably some/all of the "3 +@c weeks ago" family. +@c +@c Maybe at +@c some point have CVS start give warnings on "unofficial" +@c formats (many of which might be typos or user +@c misunderstandings, and/or formats people never/rarely +@c use to specify dates)? + +One such format is +@code{@var{month}/@var{day}/@var{year}}. This may +confuse people who are accustomed to having the month +and day in the other order; @samp{1/4/96} is January 4, +not April 1. + +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). + +Note that even with @samp{-f}, a tag that you specify +must exist (that is, in some file, not necessary in +every file). This is so that @sc{cvs} will continue to +give an error if you mistype a tag name. + +@need 800 +@samp{-f} is available with these commands: +@code{annotate}, @code{checkout}, @code{export}, +@code{rdiff}, @code{rtag}, and @code{update}. + +@strong{WARNING: The @code{commit} and @code{remove} +commands also have a +@samp{-f} option, but it has a different behavior for +those commands. See @ref{commit options}, and +@ref{Removing files}.} + +@item -k @var{kflag} +Alter the default processing of keywords. +See @ref{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}, @code{rdiff}, @code{import} and +@code{update} commands. + +@item -l +Local; run only in current working directory, rather than +recursing through subdirectories. + +Available with the following commands: @code{annotate}, @code{checkout}, +@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, +@code{log}, @code{rdiff}, @code{remove}, @code{rtag}, +@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, +and @code{watchers}. + +@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 tag program. (A program can be +specified to run in the modules +database (@pxref{modules}); this option bypasses it). + +@strong{This is not the same as the @samp{cvs -n} +program option, which you can specify to the left of a cvs command!} + +Available with the @code{checkout}, @code{export}, +and @code{rtag} commands. + +@item -P +Prune empty directories. See @ref{Removing directories}. + +@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 -R +Process directories recursively. This is on by default. + +Available with the following commands: @code{annotate}, @code{checkout}, +@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, +@code{rdiff}, @code{remove}, @code{rtag}, +@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, +and @code{watchers}. + +@item -r @var{tag} +@cindex HEAD, special tag +@cindex BASE, special 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. + +@c FIXME: What does HEAD really mean? I believe that +@c the current answer is the head of the default branch +@c for all cvs commands except diff. For diff, it +@c seems to be (a) the head of the trunk (or the default +@c branch?) if there is no sticky tag, (b) the head of the +@c branch for the sticky tag, if there is a sticky tag. +@c (b) is ugly as it differs +@c from what HEAD means for other commands, but people +@c and/or scripts are quite possibly used to it. +@c See "head" tests in sanity.sh. +@c Probably the best fix is to introduce two new +@c special tags, ".thead" for the head of the trunk, +@c and ".bhead" for the head of the current branch. +@c Then deprecate HEAD. This has the advantage of +@c not surprising people with a change to HEAD, and a +@c side benefit of also phasing out the poorly-named +@c HEAD (see discussion of reserved tag names in node +@c "Tags"). Of course, .thead and .bhead should be +@c carefully implemented (with the implementation the +@c same for "diff" as for everyone else), test cases +@c written (similar to the ones in "head"), new tests +@c cases written for things like default branches, &c. + +The tag specification is sticky when you use this +@c 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, as +described in @ref{Tags}, or the name of a branch, as +described in @ref{Branching and merging}. +When a command expects a specific revision, +the name of a branch is interpreted as the most recent +revision on that branch. + +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} file +does not contain the specified tag. + +@strong{This is not the same as the overall @samp{cvs -r} option, +which you can specify to the left of a @sc{cvs} command!} + +@samp{-r} is available with the @code{annotate}, @code{checkout}, +@code{commit}, @code{diff}, @code{history}, @code{export}, @code{rdiff}, +@code{rtag}, 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. +Available with the following commands: @code{import}, +and @code{update}. + +@end table + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node add +@appendixsec add---Add files and directories to the repository +@cindex add (subcommand) + +@itemize @bullet +@item +Synopsis: add [-k rcs-kflag] [-m message] files... +@item +Requires: repository, working directory. +@item +Changes: repository, working directory. +@end itemize + +The @code{add} command is used to present new files +and directories for addition into the @sc{cvs} +repository. When @code{add} is used on a directory, +a new directory is created in the repository +immediately. When used on a file, only the working +directory is updated. Changes to the repository are +not made until the @code{commit} command is used on +the newly added file. + +The @code{add} command also resurrects files that +have been previously removed. This can be done +before or after the @code{commit} command is used +to finalize the removal of files. Resurrected files +are restored into the working directory at the time +the @code{add} command is executed. + +@menu +* add options:: add options +* add examples:: add examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node add options +@appendixsubsec add options + +These standard options are supported by @code{add} +(@pxref{Common options}, for a complete description of +them): + +@table @code +@item -k @var{kflag} +Process keywords according to @var{kflag}. See +@ref{Keyword substitution}. +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. For more information on +the @code{status} command, @xref{Invoking CVS}. + +@item -m @var{message} +Use @var{message} as the log message, instead of +invoking an editor. +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node add examples +@appendixsubsec add examples + +@appendixsubsubsec Adding a directory + +@example +$ mkdir doc +$ cvs add doc +Directory /path/to/repository/doc added to the repository +@end example + +@appendixsubsubsec Adding a file + +@example + +$ >TODO +$ cvs add TODO +cvs add: scheduling file `TODO' for addition +cvs add: use 'cvs commit' to add this file permanently +@end example + +@appendixsubsubsec Undoing a @code{remove} command + +@example +$ rm -f makefile +$ cvs remove makefile +cvs remove: scheduling `makefile' for removal +cvs remove: use 'cvs commit' to remove this file permanently +$ cvs add makefile +U makefile +cvs add: makefile, version 1.2, resurrected +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node admin +@appendixsec admin---Administration +@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 facilities. Some of them have +questionable usefulness for @sc{cvs} but exist for +historical purposes. Some of the questionable options +are likely to disappear in the future. This command +@emph{does} work recursively, so extreme care should be +used. + +@cindex cvsadmin +On unix, if there is a group named @code{cvsadmin}, +only members of that group can run @code{cvs admin} +(except for the @code{cvs admin -k} command, which can +be run by anybody). This group should exist on the +server, or any system running the non-client/server +@sc{cvs}. To disallow @code{cvs admin} for all users, +create a group with no users in it. On NT, the +@code{cvsadmin} feature does not exist and all users +can run @code{cvs admin}. + +@menu +* admin options:: admin options +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node admin options +@appendixsubsec admin options + +Some of these options have questionable usefulness for +@sc{cvs} but exist for historical purposes. Some even +make it impossible to use @sc{cvs} until you undo the +effect! + +@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}] +Set the default branch to @var{rev}. In @sc{cvs}, you +normally do not manipulate default branches; sticky +tags (@pxref{Sticky tags}) are a better way to decide +which branch you want to work on. There is one reason +to run @code{cvs admin -b}: to revert to the vendor's +version when using vendor branches (@pxref{Reverting +local changes}). +There can be no space between @samp{-b} and its argument. +@c Hmm, we don't document the usage where rev is +@c omitted. Maybe that usage can/should be deprecated +@c (and replaced with -bHEAD or something?) (so we can toss +@c the optional argument). Note that -bHEAD does not +@c work, as of 17 Sep 1997, but probably will once "cvs +@c admin" is internal to CVS. + +@cindex Comment leader +@item -c@var{string} +Sets the comment leader to @var{string}. The comment +leader is not used by current versions of @sc{cvs} or +@sc{rcs} 5.7. Therefore, you can almost surely not +worry about it. See @ref{Keyword substitution}. + +@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. +There can be no space between @samp{-e} and its argument. + +@item -I +Run interactively, even if the standard input is not a +terminal. This option does not work with the +client/server @sc{cvs} and is likely to disappear in +a future release of @sc{cvs}. + +@item -i +Useless with @sc{cvs}. This creates and initializes a +new @sc{rcs} file, without depositing a revision. With +@sc{cvs}, add files with the @code{cvs add} command +(@pxref{Adding files}). + +@item -k@var{subst} +Set the default keyword +substitution to @var{subst}. See @ref{Keyword +substitution}. Giving an explicit @samp{-k} option to +@code{cvs update}, @code{cvs export}, or @code{cvs +checkout} overrides this default. + +@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. There can be no space between +@samp{-l} and its argument. + +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}. + +@c The rcs -M option, to suppress sending mail, has never been +@c documented as a cvs admin option. + +@item -N@var{name}[:[@var{rev}]] +Act like @samp{-n}, except override any previous +assignment of @var{name}. For use with magic branches, +see @ref{Magic branch numbers}. + +@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{cvs admin -n@var{name}:} associates @var{name} with the +current latest revision of all the RCS files; +this contrasts with @samp{cvs admin -n@var{name}:$} 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} +Deletes (@dfn{outdates}) the revisions given by +@var{range}. + +Note that this command can be quite dangerous unless +you know @emph{exactly} what you are doing (for example +see the warnings below about how the +@var{rev1}:@var{rev2} syntax is confusing). + +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! +If you delete different revisions than you planned, +either due to carelessness or (heaven forbid) a @sc{cvs} +bug, there is no opportunity to correct the error +before the revisions are deleted. It probably would be +a good idea to experiment on a copy of the repository +first. + +Specify @var{range} in one of the following ways: + +@table @code +@item @var{rev1}::@var{rev2} +Collapse all revisions between rev1 and rev2, so that +@sc{cvs} only stores the differences associated with going +from rev1 to rev2, not intermediate steps. For +example, after @samp{-o 1.3::1.5} one can retrieve +revision 1.3, revision 1.5, or the differences to get +from 1.3 to 1.5, but not the revision 1.4, or the +differences between 1.3 and 1.4. Other examples: +@samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no +effect, because there are no intermediate revisions to +remove. + +@item ::@var{rev} +Collapse revisions between the beginning of the branch +containing @var{rev} and @var{rev} itself. The +branchpoint and @var{rev} are left intact. For +example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1, +revision 1.3.2.5, and everything in between, but leaves +1.3 and 1.3.2.6 intact. + +@item @var{rev}:: +Collapse revisions between @var{rev} and the end of the +branch containing @var{rev}. Revision @var{rev} is +left intact but the head revision is deleted. + +@item @var{rev} +Delete the revision @var{rev}. For example, @samp{-o +1.3} is equivalent to @samp{-o 1.2::1.4}. + +@item @var{rev1}:@var{rev2} +Delete the revisions from @var{rev1} to @var{rev2}, +inclusive, on the same branch. One will not be able to +retrieve @var{rev1} or @var{rev2} or any of the +revisions in between. For example, the command +@samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful. +It means to delete revisions up to, and including, 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! In most cases you want to +specify @var{rev1}::@var{rev2} instead. + +@item :@var{rev} +Delete revisions from the beginning of the +branch containing @var{rev} up to and including +@var{rev}. + +@item @var{rev}: +Delete revisions from revision @var{rev}, including +@var{rev} itself, to the end of the branch containing +@var{rev}. +@end table + +None of the revisions to be deleted may have +branches or locks. + +If any of the revisions to be deleted have symbolic +names, and one specifies one of the @samp{::} syntaxes, +then @sc{cvs} will give an error and not delete any +revisions. If you really want to delete both the +symbolic names and the revisions, first delete the +symbolic names with @code{cvs tag -d}, then run +@code{cvs admin -o}. If one specifies the +non-@samp{::} syntaxes, then @sc{cvs} will delete the +revisions but leave the symbolic names pointing to +nonexistent revisions. This behavior is preserved for +compatibility with previous versions of @sc{cvs}, but +because it isn't very useful, in the future it may +change to be like the @samp{::} case. + +Due to the way @sc{cvs} handles branches @var{rev} +cannot be specified symbolically if it is a branch. +See @ref{Magic branch numbers} for an explanation. +@c FIXME: is this still true? I suspect not. + +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{$@splitrcskeyword{Log}$} and @samp{$@splitrcskeyword{State}$} keywords +(@pxref{Keyword substitution}). Note that @sc{cvs} +uses the @code{dead} state for its own purposes (@pxref{Attic}); to +take a file to or from the @code{dead} state use +commands like @code{cvs remove} and @code{cvs add} +(@pxref{Adding and removing}), 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{-}. The descriptive text can be seen in the +output from @samp{cvs log} (@pxref{log}). +There can be no space between @samp{-t} and its argument. + +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}. + +@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. +There can be no space between @samp{-t} and its argument. + +@c The rcs -T option, do not update last-mod time for +@c minor changes, has never been documented as a +@c cvs admin option. + +@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 the original locker to be sent a @code{commit} +notification (@pxref{Getting Notified}). +There can be no space between @samp{-u} and its argument. + +@item -V@var{n} +In previous versions of @sc{cvs}, this option meant to +write an @sc{rcs} file which would be acceptable to +@sc{rcs} version @var{n}, but it is now obsolete and +specifying it will produce an error. +@c Note that -V without an argument has never been +@c documented as a cvs admin option. + +@item -x@var{suffixes} +In previous versions of @sc{cvs}, this was documented +as a way of specifying the names of the @sc{rcs} +files. However, @sc{cvs} has always required that the +@sc{rcs} files used by @sc{cvs} end in @samp{,v}, so +this option has never done anything useful. + +@c The rcs -z option, to specify the timezone, has +@c never been documented as a cvs admin option. +@end table + + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node annotate +@appendixsec annotate---What revision modified each line of a file? +@cindex annotate (subcommand) + +@itemize @bullet +@item +Synopsis: annotate [options] files@dots{} +@item +Requires: repository. +@item +Synonym: blame +@item +Changes: nothing. +@end itemize + +For each file in @var{files}, print the head revision +of the trunk, together with information on the last +modification for each line. + +@menu +* annotate options:: annotate options +* annotate example:: annotate example +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node annotate options +@appendixsubsec annotate options + +These standard options are supported by @code{annotate} +(@pxref{Common options} for a complete description of +them): + +@table @code +@item -l +Local directory only, no recursion. + +@item -R +Process directories recursively. + +@item -f +Use head revision if tag/date not found. + +@item -F +Annotate binary files. + +@item -r @var{revision} +Annotate file as of specified revision/tag. + +@item -D @var{date} +Annotate file as of specified date. +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node annotate example +@appendixsubsec annotate example + +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}). + +The options to @code{cvs annotate} are listed in +@ref{Invoking CVS}, and can be used to select the files +and revisions to annotate. The options are described +in more detail there and in @ref{Common options}. + +@c FIXME: maybe an example using the options? Just +@c what it means to select a revision might be worth a +@c few words of explanation ("you want to see who +@c changed this line *before* 1.4"...). + + +@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 + +Create or update 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} 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. +See @ref{modules}. +@c Needs an example, particularly of the non-"modules" +@c case but probably of both. + +@c FIXME: this seems like a very odd place to introduce +@c people to how CVS works. The bit about unreserved +@c checkouts is also misleading as it depends on how +@c things are set up. +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}). + +Note that running @code{checkout} on a directory that was already +built by a prior @code{checkout} is also permitted. +This is similar to specifying the @samp{-d} option +to the @code{update} command in the sense that new +directories that have been created in the repository +will appear in your work area. +However, @code{checkout} takes a module name whereas +@code{update} takes a directory name. Also +to use @code{checkout} this way it must be run from the +top level directory (where you originally ran +@code{checkout} from), so before you run +@code{checkout} to update an existing directory, don't +forget to change your directory to the top level +directory. + +For the output produced by the @code{checkout} command, +@xref{update output}. + +@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 keywords according to @var{kflag}. See +@ref{Keyword substitution}. +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. See @ref{Invoking CVS} for +more information on the @code{status} command. + +@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. See @ref{Moving directories}. + +@item -p +Pipe files to the standard output. + +@item -R +Checkout directories recursively. This option is on by default. + +@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. +Does not reset sticky @samp{-k} options on modified files. +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. In general, +using this flag is equivalent to using @samp{mkdir +@var{dir}; cd @var{dir}} followed by the checkout +command without the @samp{-d} flag. + +There is an important exception, however. It is very +convenient when checking out a single item to have the +output appear in a directory that doesn't contain empty +intermediate directories. In this case @emph{only}, +@sc{cvs} tries to ``shorten'' pathnames to avoid those empty +directories. + +For example, given a module @samp{foo} that contains +the file @samp{bar.c}, the command @samp{cvs co -d dir +foo} will create directory @samp{dir} and place +@samp{bar.c} inside. Similarly, given a module +@samp{bar} which has subdirectory @samp{baz} wherein +there is a file @samp{quux.c}, the command @samp{cvs co +-d dir bar/baz} will create directory @samp{dir} and +place @samp{quux.c} inside. + +Using the @samp{-N} flag will defeat this behavior. +Given the same module definitions above, @samp{cvs co +-N -d dir foo} will create directories @samp{dir/foo} +and place @samp{bar.c} inside, while @samp{cvs co -N -d +dir bar/baz} will create directories @samp{dir/bar/baz} +and place @samp{quux.c} inside. + +@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}}. + +See @ref{Branching and 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 when you check out a single +module. See the @samp{-d} flag for examples and a +discussion. + +@item -s +Like @samp{-c}, but include the status of all modules, +and sort it by the status string. See @ref{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 +Synopsis: commit [-lRf] [-m 'log_message' | +-F file] [-r revision] [files@dots{}] +@item +Requires: working directory, repository. +@item +Changes: repository. +@item +Synonym: ci +@end itemize + +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} 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 +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 -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 +(@pxref{Assigning revisions}). You +cannot commit to a specific revision on a branch. +@c FIXME: Need xref for branch case. +@end table + +@code{commit} also supports these options: + +@table @code +@item -F @var{file} +Read the log message from @var{file}, instead +of invoking an editor. + +@item -f +Note that this is not the standard behavior of +the @samp{-f} option as defined in @ref{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 + +@c This is odd, but it's how CVS has worked for some +@c time. +The @samp{-f} option disables recursion (i.e., it +implies @samp{-l}). To force @sc{cvs} to commit a new +revision for all files in all subdirectories, you must +use @samp{-f -R}. + +@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 + +@c FIXME: this material wants to be somewhere +@c in "Branching and merging". + +@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{Branching and merging}). 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---Show differences between revisions +@cindex diff (subcommand) + +@itemize @bullet +@item +Synopsis: diff [-lR] [-k kflag] [format_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 for diff is different than for other +@sc{cvs} commands; for details @xref{Exit status}. + +@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. + +@item -k @var{kflag} +Process keywords according to @var{kflag}. See +@ref{Keyword substitution}. + +@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). +@c We should be a lot more explicit, with examples, +@c about the difference between "cvs diff" and "cvs +@c diff -r HEAD". This often confuses new users. + +One or both @samp{-r} options can be replaced by a +@samp{-D @var{date}} option, described above. +@end table + +@c Conceptually, this is a disaster. There are 3 +@c zillion diff formats that we support via the diff +@c library. It is not obvious to me that we should +@c document them all. Maybe just the most common ones +@c like -c and -u, and think about phasing out the +@c obscure ones. +@c FIXCVS: also should be a way to specify an external +@c diff program (which can be different for different +@c file types) and pass through +@c arbitrary options, so that the user can do +@c "--pass=-Z --pass=foo" or something even if CVS +@c doesn't know about the "-Z foo" option to diff. +@c This would fit nicely with deprecating/eliminating +@c the obscure options of the diff library, because it +@c would let people specify an external GNU diff if +@c they are into that sort of thing. +The following options specify the format of the +output. They have the same meaning as in GNU diff. +Most options have two equivalent names, one of which is a single letter +preceded by @samp{-}, and the other of which is a long name preceded by +@samp{--}. + +@table @samp +@item -@var{lines} +Show @var{lines} (an integer) lines of context. This option does not +specify an output format by itself; it has no effect unless it is +combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper +operation, @code{patch} typically needs at least two lines of context. + +@item -a +Treat all files as text and compare them line-by-line, even if they +do not seem to be text. + +@item -b +Ignore trailing white space and consider all other sequences of one or +more white space characters to be equivalent. + +@item -B +Ignore changes that just insert or delete blank lines. + +@item --binary +Read and write data in binary mode. + +@item --brief +Report only whether the files differ, not the details of the +differences. + +@item -c +Use the context output format. + +@item -C @var{lines} +@itemx --context@r{[}=@var{lines}@r{]} +Use the context output format, showing @var{lines} (an integer) lines of +context, or three if @var{lines} is not given. +For proper operation, @code{patch} typically needs at least two lines of +context. + +@item --changed-group-format=@var{format} +Use @var{format} to output a line group containing differing lines from +both files in if-then-else format. See @ref{Line group formats}. + +@item -d +Change the algorithm to perhaps find a smaller set of changes. This makes +@code{diff} slower (sometimes much slower). + +@item -e +@itemx --ed +Make output that is a valid @code{ed} script. + +@item --expand-tabs +Expand tabs to spaces in the output, to preserve the alignment of tabs +in the input files. + +@item -f +Make output that looks vaguely like an @code{ed} script but has changes +in the order they appear in the file. + +@item -F @var{regexp} +In context and unified format, for each hunk of differences, show some +of the last preceding line that matches @var{regexp}. + +@item --forward-ed +Make output that looks vaguely like an @code{ed} script but has changes +in the order they appear in the file. + +@item -H +Use heuristics to speed handling of large files that have numerous +scattered small changes. + +@item --horizon-lines=@var{lines} +Do not discard the last @var{lines} lines of the common prefix +and the first @var{lines} lines of the common suffix. + +@item -i +Ignore changes in case; consider upper- and lower-case letters +equivalent. + +@item -I @var{regexp} +Ignore changes that just insert or delete lines that match @var{regexp}. + +@item --ifdef=@var{name} +Make merged if-then-else output using @var{name}. + +@item --ignore-all-space +Ignore white space when comparing lines. + +@item --ignore-blank-lines +Ignore changes that just insert or delete blank lines. + +@item --ignore-case +Ignore changes in case; consider upper- and lower-case to be the same. + +@item --ignore-matching-lines=@var{regexp} +Ignore changes that just insert or delete lines that match @var{regexp}. + +@item --ignore-space-change +Ignore trailing white space and consider all other sequences of one or +more white space characters to be equivalent. + +@item --initial-tab +Output a tab rather than a space before the text of a line in normal or +context format. This causes the alignment of tabs in the line to look +normal. + +@item -L @var{label} +Use @var{label} instead of the file name in the context format +and unified format headers. + +@item --label=@var{label} +Use @var{label} instead of the file name in the context format +and unified format headers. + +@item --left-column +Print only the left column of two common lines in side by side format. + +@item --line-format=@var{format} +Use @var{format} to output all input lines in if-then-else format. +See @ref{Line formats}. + +@item --minimal +Change the algorithm to perhaps find a smaller set of changes. This +makes @code{diff} slower (sometimes much slower). + +@item -n +Output RCS-format diffs; like @samp{-f} except that each command +specifies the number of lines affected. + +@item -N +@itemx --new-file +In directory comparison, if a file is found in only one directory, +treat it as present but empty in the other directory. + +@item --new-group-format=@var{format} +Use @var{format} to output a group of lines taken from just the second +file in if-then-else format. See @ref{Line group formats}. + +@item --new-line-format=@var{format} +Use @var{format} to output a line taken from just the second file in +if-then-else format. See @ref{Line formats}. + +@item --old-group-format=@var{format} +Use @var{format} to output a group of lines taken from just the first +file in if-then-else format. See @ref{Line group formats}. + +@item --old-line-format=@var{format} +Use @var{format} to output a line taken from just the first file in +if-then-else format. See @ref{Line formats}. + +@item -p +Show which C function each change is in. + +@item --rcs +Output RCS-format diffs; like @samp{-f} except that each command +specifies the number of lines affected. + +@item --report-identical-files +@itemx -s +Report when two files are the same. + +@item --show-c-function +Show which C function each change is in. + +@item --show-function-line=@var{regexp} +In context and unified format, for each hunk of differences, show some +of the last preceding line that matches @var{regexp}. + +@item --side-by-side +Use the side by side output format. + +@item --speed-large-files +Use heuristics to speed handling of large files that have numerous +scattered small changes. + +@item --suppress-common-lines +Do not print common lines in side by side format. + +@item -t +Expand tabs to spaces in the output, to preserve the alignment of tabs +in the input files. + +@item -T +Output a tab rather than a space before the text of a line in normal or +context format. This causes the alignment of tabs in the line to look +normal. + +@item --text +Treat all files as text and compare them line-by-line, even if they +do not appear to be text. + +@item -u +Use the unified output format. + +@item --unchanged-group-format=@var{format} +Use @var{format} to output a group of common lines taken from both files +in if-then-else format. @xref{Line group formats}. + +@item --unchanged-line-format=@var{format} +Use @var{format} to output a line common to both files in if-then-else +format. @xref{Line formats}. + +@item -U @var{lines} +@itemx --unified@r{[}=@var{lines}@r{]} +Use the unified output format, showing @var{lines} (an integer) lines of +context, or three if @var{lines} is not given. +For proper operation, @code{patch} typically needs at least two lines of +context. + +@item -w +Ignore white space when comparing lines. + +@item -W @var{columns} +@itemx --width=@var{columns} +Use an output width of @var{columns} in side by side format. + +@item -y +Use the side by side output format. +@end table + +@menu +* Line group formats:: Line group formats +* Line formats:: Line formats +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node Line group formats +@appendixsubsubsec Line group formats + +Line group formats let you specify formats suitable for many +applications that allow if-then-else input, including programming +languages and text formatting languages. A line group format specifies +the output format for a contiguous group of similar lines. + +For example, the following command compares the TeX file @file{myfile} +with the original version from the repository, +and outputs a merged file in which old regions are +surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new +regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines. + +@example +cvs diff \ + --old-group-format='\begin@{em@} +%<\end@{em@} +' \ + --new-group-format='\begin@{bf@} +%>\end@{bf@} +' \ + myfile +@end example + +The following command is equivalent to the above example, but it is a +little more verbose, because it spells out the default line group formats. + +@example +cvs diff \ + --old-group-format='\begin@{em@} +%<\end@{em@} +' \ + --new-group-format='\begin@{bf@} +%>\end@{bf@} +' \ + --unchanged-group-format='%=' \ + --changed-group-format='\begin@{em@} +%<\end@{em@} +\begin@{bf@} +%>\end@{bf@} +' \ + myfile +@end example + +Here is a more advanced example, which outputs a diff listing with +headers containing line numbers in a ``plain English'' style. + +@example +cvs diff \ + --unchanged-group-format='' \ + --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: +%<' \ + --new-group-format='-------- %dN line%(N=1?:s) added after %de: +%>' \ + --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: +%<-------- to: +%>' \ + myfile +@end example + +To specify a line group format, use one of the options +listed below. You can specify up to four line group formats, one for +each kind of line group. You should quote @var{format}, because it +typically contains shell metacharacters. + +@table @samp +@item --old-group-format=@var{format} +These line groups are hunks containing only lines from the first file. +The default old group format is the same as the changed group format if +it is specified; otherwise it is a format that outputs the line group as-is. + +@item --new-group-format=@var{format} +These line groups are hunks containing only lines from the second +file. The default new group format is same as the changed group +format if it is specified; otherwise it is a format that outputs the +line group as-is. + +@item --changed-group-format=@var{format} +These line groups are hunks containing lines from both files. The +default changed group format is the concatenation of the old and new +group formats. + +@item --unchanged-group-format=@var{format} +These line groups contain lines common to both files. The default +unchanged group format is a format that outputs the line group as-is. +@end table + +In a line group format, ordinary characters represent themselves; +conversion specifications start with @samp{%} and have one of the +following forms. + +@table @samp +@item %< +stands for the lines from the first file, including the trailing newline. +Each line is formatted according to the old line format (@pxref{Line formats}). + +@item %> +stands for the lines from the second file, including the trailing newline. +Each line is formatted according to the new line format. + +@item %= +stands for the lines common to both files, including the trailing newline. +Each line is formatted according to the unchanged line format. + +@item %% +stands for @samp{%}. + +@item %c'@var{C}' +where @var{C} is a single character, stands for @var{C}. +@var{C} may not be a backslash or an apostrophe. +For example, @samp{%c':'} stands for a colon, even inside +the then-part of an if-then-else format, which a colon would +normally terminate. + +@item %c'\@var{O}' +where @var{O} is a string of 1, 2, or 3 octal digits, +stands for the character with octal code @var{O}. +For example, @samp{%c'\0'} stands for a null character. + +@item @var{F}@var{n} +where @var{F} is a @code{printf} conversion specification and @var{n} is one +of the following letters, stands for @var{n}'s value formatted with @var{F}. + +@table @samp +@item e +The line number of the line just before the group in the old file. + +@item f +The line number of the first line in the group in the old file; +equals @var{e} + 1. + +@item l +The line number of the last line in the group in the old file. + +@item m +The line number of the line just after the group in the old file; +equals @var{l} + 1. + +@item n +The number of lines in the group in the old file; equals @var{l} - @var{f} + 1. + +@item E, F, L, M, N +Likewise, for lines in the new file. + +@end table + +The @code{printf} conversion specification can be @samp{%d}, +@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal, +lower case hexadecimal, or upper case hexadecimal output +respectively. After the @samp{%} the following options can appear in +sequence: a @samp{-} specifying left-justification; an integer +specifying the minimum field width; and a period followed by an +optional integer specifying the minimum number of digits. +For example, @samp{%5dN} prints the number of new lines in the group +in a field of width 5 characters, using the @code{printf} format @code{"%5d"}. + +@item (@var{A}=@var{B}?@var{T}:@var{E}) +If @var{A} equals @var{B} then @var{T} else @var{E}. +@var{A} and @var{B} are each either a decimal constant +or a single letter interpreted as above. +This format spec is equivalent to @var{T} if +@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}. + +For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to +@samp{no lines} if @var{N} (the number of lines in the group in the +new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines} +otherwise. +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node Line formats +@appendixsubsubsec Line formats + +Line formats control how each line taken from an input file is +output as part of a line group in if-then-else format. + +For example, the following command outputs text with a one-column +change indicator to the left of the text. The first column of output +is @samp{-} for deleted lines, @samp{|} for added lines, and a space +for unchanged lines. The formats contain newline characters where +newlines are desired on output. + +@example +cvs diff \ + --old-line-format='-%l +' \ + --new-line-format='|%l +' \ + --unchanged-line-format=' %l +' \ + myfile +@end example + +To specify a line format, use one of the following options. You should +quote @var{format}, since it often contains shell metacharacters. + +@table @samp +@item --old-line-format=@var{format} +formats lines just from the first file. + +@item --new-line-format=@var{format} +formats lines just from the second file. + +@item --unchanged-line-format=@var{format} +formats lines common to both files. + +@item --line-format=@var{format} +formats all lines; in effect, it sets all three above options simultaneously. +@end table + +In a line format, ordinary characters represent themselves; +conversion specifications start with @samp{%} and have one of the +following forms. + +@table @samp +@item %l +stands for the contents of the line, not counting its trailing +newline (if any). This format ignores whether the line is incomplete. + +@item %L +stands for the contents of the line, including its trailing newline +(if any). If a line is incomplete, this format preserves its +incompleteness. + +@item %% +stands for @samp{%}. + +@item %c'@var{C}' +where @var{C} is a single character, stands for @var{C}. +@var{C} may not be a backslash or an apostrophe. +For example, @samp{%c':'} stands for a colon. + +@item %c'\@var{O}' +where @var{O} is a string of 1, 2, or 3 octal digits, +stands for the character with octal code @var{O}. +For example, @samp{%c'\0'} stands for a null character. + +@item @var{F}n +where @var{F} is a @code{printf} conversion specification, +stands for the line number formatted with @var{F}. +For example, @samp{%.5dn} prints the line number using the +@code{printf} format @code{"%.5d"}. @xref{Line group formats}, for +more about printf conversion specifications. + +@end table + +The default line format is @samp{%l} followed by a newline character. + +If the input contains tab characters and it is important that they line +up on output, you should ensure that @samp{%l} or @samp{%L} in a line +format is just after a tab stop (e.g.@: by preceding @samp{%l} or +@samp{%L} with a tab character), or you should use the @samp{-t} or +@samp{--expand-tabs} option. + +Taken together, the line and line group formats let you specify many +different formats. For example, the following command uses a format +similar to @code{diff}'s normal format. You can tailor this command +to get fine control over @code{diff}'s output. + +@example +cvs diff \ + --old-line-format='< %l +' \ + --new-line-format='> %l +' \ + --old-group-format='%df%(f=l?:,%dl)d%dE +%<' \ + --new-group-format='%dea%dF%(F=L?:,%dL) +%>' \ + --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) +%<--- +%>' \ + --unchanged-group-format='' \ + myfile +@end example + +@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 [-flNnR] [-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 +(and thus it always prunes empty directories). + +One often would like to use @samp{-kv} with @code{cvs +export}. This causes any 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 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. +See @ref{checkout options} for complete details on how +@sc{cvs} handles this flag. + +@item -k @var{subst} +Set keyword expansion mode (@pxref{Substitution modes}). + +@item -N +Only useful together with @samp{-d @var{dir}}. +See @ref{checkout options} for complete details on how +@sc{cvs} handles this flag. +@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{@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{-x} with all record types. Of course, +@samp{-e} will also include record types which are +added in a future version of @sc{cvs}; if you are +writing a script which can only handle certain record +types, you'll want to specify @samp{-x}. + +@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. This is the default report type. + +@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 E +export +@item T +rtag +@end table + +@noindent +One of five 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 P +A working file was patched to match 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 -f @var{file} +Show data for a particular file +(you can specify several @samp{-f} options on the same command line). +This is equivalent to specifying the file on the command line. + +@item -n @var{module} +Show data for a particular module +(you can specify several @samp{-n} options on the same command line). + +@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 +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}. + +@item -z @var{timezone} +Show times in the selected records using the specified +time zone instead of UTC. +@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) + +@c FIXME: This node is way too long for one which has subnodes. + +@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. See @ref{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 (@pxref{import output} for a +complete description of the output). + +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. See @ref{Wrappers}. + +The outside source is saved in a first-level +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 uniquely identify the files at +the leaves created each time you execute @code{import}. The +@var{releasetag} should be new, not previously existing in the +repository file, and uniquely identify the imported release, + +@c I'm not completely sure this belongs here. But +@c we need to say it _somewhere_ reasonably obvious; it +@c is a common misconception among people first learning CVS +Note that @code{import} does @emph{not} change the +directory in which you invoke it. In particular, it +does not set up that directory as a @sc{cvs} working +directory; if you want to work with the sources import +them first and then check them out into a different +directory (@pxref{Getting the source}). + +@menu +* import options:: import options +* import output:: import output +* 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 the following additional special options. + +@table @code +@item -b @var{branch} +See @ref{Multiple vendor branches}. + +@item -k @var{subst} +Indicate the 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. +See @ref{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 output +@appendixsubsec import output + +@code{import} 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 already exists in the repository and has not been locally +modified; a new revision has been created (if necessary). + +@item N @var{file} +The file is a new file which has been added to the repository. + +@item C @var{file} +The file already exists in the repository but has been locally modified; +you will have to merge the changes. + +@item I @var{file} +The file is being ignored (@pxref{cvsignore}). + +@cindex Symbolic link, importing +@cindex Link, symbolic, importing +@c FIXME: also (somewhere else) probably +@c should be documenting what happens if you "cvs add" +@c a symbolic link. Also maybe what happens if +@c you manually create symbolic links within the +@c repository (? - not sure why we'd want to suggest +@c doing that). +@item L @var{file} +The file is a symbolic link; @code{cvs import} ignores symbolic links. +People periodically suggest that this behavior should +be changed, but if there is a consensus on what it +should be changed to, it doesn't seem to be apparent. +(Various options in the @file{modules} file can be used +to recreate symbolic links on checkout, update, etc.; +@pxref{modules}.) +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node import examples +@appendixsubsec import examples + +See @ref{Tracking sources}, and @ref{From files}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node log +@appendixsec log---Print out log information for files +@cindex log (subcommand) + +@itemize @bullet +@item +Synopsis: log [options] [files@dots{}] +@item +Requires: repository, working directory. +@item +Changes: nothing. +@end itemize + +Display log information for files. @code{log} used to +call the @sc{rcs} utility @code{rlog}. Although this +is no longer true in the current sources, this history +determines the format of the output and the options, +which are not quite in the style of the other @sc{cvs} +commands. + +@cindex Timezone, in output +@cindex Zone, time, in output +@c Kind of a funny place to document the timezone used +@c in output from commands other than @code{log}. +@c There is also more we need to say about this, +@c including what happens in a client/server environment. +The output 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 FIXCVS: need a better way to control the timezone +@c used in output. Previous/current versions of CVS did/do +@c sometimes support -z in RCSINIT, and/or an +@c undocumented (except by reference to 'rlog') -z option +@c to cvs log, but this has not been a consistent, +@c documented feature. Perhaps a new global option, +@c where LT means the client's timezone, which the +@c client then communicates to the server, is the +@c right solution. + +@strong{@code{log} uses @samp{-R} in a way that conflicts +with the normal use inside @sc{cvs} (@pxref{Common options}).} + +@menu +* log options:: log options +* log examples:: log examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node log options +@appendixsubsec log options + +By default, @code{log} prints all information that is +available. All other options restrict the output. Note that the revision +selection options (@code{-b}, @code{-d}, @code{-r}, @code{-s}, and @code{-w}) +have no +effect, other than possibly causing a search for files in Attic directories, +when used in conjunction with the options that restrict the output to only +@code{log} header fields (@code{-h}, @code{-R}, and @code{-t}) +unless the @code{-S} option is also specified. + +@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 date formats +accepted are those accepted by the @samp{-D} option to +many other @sc{cvs} commands (@pxref{Common options}). +Dates can be combined into ranges as follows: + +@c Should we be thinking about accepting ISO8601 +@c ranges? For example "1972-09-10/1972-09-12". +@table @code +@item @var{d1}<@var{d2} +@itemx @var{d2}>@var{d1} +Select the revisions that were deposited between +@var{d1} and @var{d2}. + +@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 @samp{>} or @samp{<} characters may be followed by +@samp{=} to indicate an inclusive range rather than an +exclusive one. + +Note that the separator is a semicolon (;). + +@item -h +Print only the name of the @sc{rcs} file, name +of the file in the working directory, head, +default branch, access list, locks, symbolic names, and +suffix. + +@item -l +Local; run only in current working directory. (Default +is to run recursively). + +@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 -n +Print the list of tags for this file. This option can +be very useful when your @file{.cvsrc} file has a +@samp{log -N} entry as a way to get a full list of all +of the tags. + +@item -R +Print only the name of the @sc{rcs} file. + +@c Note that using a bare revision (in addition to not +@c being explicitly documented here) is potentially +@c confusing; it shows the log message to get from the +@c previous revision to that revision. "-r1.3 -r1.6" +@c (equivalent to "-r1.3,1.6") is even worse; it +@c prints the messages to get from 1.2 to 1.3 and 1.5 +@c to 1.6. By analogy with "cvs diff", users might +@c expect that it is more like specifying a range. +@c It is not 100% clear to me how much of this should +@c be documented (for example, multiple -r options +@c perhaps could/should be deprecated given the false +@c analogy with "cvs diff"). +@c In general, this section should be rewritten to talk +@c about messages to get from revision rev1 to rev2, +@c rather than messages for revision rev2 (that is, the +@c messages are associated with a change not a static +@c revision and failing to make this distinction causes +@c much confusion). +@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{rev1}::@var{rev2} +The same, but excluding @var{rev1}. + +@item :@var{rev} +@itemx ::@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{rev}:: +Revisions starting just after @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. + +@item @var{branch1}:@var{branch2} +@itemx @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. +There can be no space between the @samp{-r} option and +its argument. + +@item -S +Suppress the header if no revisions are selected. + +@item -s @var{states} +Print information about revisions whose state +attributes match one of the states given in the +comma-separated list @var{states}. Individual states may +be any text string, though @sc{cvs} commonly only uses two +states, @samp{Exp} and @samp{dead}. See @ref{admin options} +for more information. + +@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. There can be no space between the +@samp{-w} option and its argument. +@end table + +@code{log} prints the intersection of the revisions +selected with the options @samp{-d}, @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 @code{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 @code{patch} command when +patching the old sources, so that @code{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 -k @var{kflag} +Process keywords according to @var{kflag}. See +@ref{Keyword substitution}. + +@item -l +Local; don't descend subdirectories. + +@item -R +Examine directories recursively. This option is on by default. + +@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. +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 keywords according to the rules current in +@sc{rcs} version @var{vn} (the expansion format changed with +@sc{rcs} version 5). Note that this option is no +longer accepted. @sc{cvs} will always expand keywords the +way that @sc{rcs} version 5 does. +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node rdiff examples +@appendixsubsec rdiff examples + +Suppose you receive mail from @t{foo@@example.net} 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@@example.net +@end example + +Suppose you have made release 1.3, and forked a branch +called @samp{R_1_3fix} for bug fixes. @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 output +* 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 deletes +all directories and files recursively. This +has the very serious side-effect that any directory +created inside checked-out sources, and not added to +the repository (using the @code{add} command; +@pxref{Adding files}) 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. + +@table @code +@item U @var{file} +@itemx P @var{file} +There exists a newer revision of this file in the +repository, and you have not modified your local copy +of the file (@samp{U} and @samp{P} mean the same thing). + +@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. See @ref{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. +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node release examples +@appendixsubsec release examples + +Release the @file{tc} directory, 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) directory `tc': y +$ +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node remove +@appendixsec remove---Remove files from active use +@cindex remove (subcommand) + +@itemize @bullet +@item +Synopsis: remove [-flR] [files...] +@item +Requires: repository, working directory. +@item +Changes: working directory. +@end itemize + +The @code{remove} command is used to remove unwanted +files from active use. The user normally deletes the +files from the working directory prior to invocation +of the @code{remove} command. Only the working +directory is updated. Changes to the repository are +not made until the @code{commit} command is run. + +The @code{remove} command does not delete files from +from the repository. @sc{cvs} keeps all historical +data in the repository so that it is possible to +reconstruct previous states of the projects under +revision control. + +To undo @sc{cvs} @code{remove} or to resurrect files +that were previously removed, @xref{add}. + +@menu +* remove options:: remove options +* remove examples:: remove examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node remove options +@appendixsubsec remove options + +These standard options are supported by @code{remove} +(@pxref{Common options} for a complete description of +them): + +@table @code +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -R +Process directories recursively. See @ref{Recursive behavior}. + +@end table + +In addition, these options are also supported: + +@table @code +@item -f +Note that this is not the standard behavior of +the @samp{-f} option as defined in @ref{Common options}. + +Delete files before removing them. + +Entire directory hierarchies are easily removed +using @samp{-f}, but take note that it is not as +easy to resurrect directory hierarchies as it is +to remove them. + +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node remove examples +@appendixsubsec remove examples + +@appendixsubsubsec Removing a file + +@example +$ cvs remove remove.me +cvs remove: file `remove.me' still in working directory +cvs remove: 1 file exists; remove it first +$ rm -f remove.me +$ cvs remove remove.me +cvs remove: scheduling `remove.me' for removal +cvs remove: use 'cvs commit' to remove this file permanently + +$ ls remove.it +remove.it +$ cvs remove -f remove.it +cvs remove: scheduling `remove.it' for removal +cvs remove: use 'cvs commit' to remove this file permanently +@end example + +@appendixsubsubsec Removing entire directories +@example +$ tree -d a +a +|-- CVS +`-- b + `-- CVS + +3 directories +$ cvs remove -f a +cvs remove: Removing a +cvs remove: Removing a/b +cvs remove: scheduling `a/b/c' for removal +cvs remove: use 'cvs commit' to remove this file permanently +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node update +@appendixsec update---Bring work tree in sync with repository +@cindex update (subcommand) + +@itemize @bullet +@item +update [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag|-D date] [-W spec] 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 +@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 keywords according to @var{kflag}. See +@ref{Keyword substitution}. +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. See @ref{Invoking CVS} for +more information on the @code{status} command. + +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -P +Prune empty directories. See @ref{Moving directories}. + +@item -p +Pipe files to the standard output. + +@item -R +Update directories recursively (default). See @ref{Recursive +behavior}. + +@item -r rev +Retrieve revision/tag @var{rev}. 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. +Does not reset sticky @samp{-k} options on modified files. +See @ref{Sticky tags} for more information on sticky tags/dates. + +@item -C +Overwrite locally modified files with clean copies from +the repository (the modified file is saved in +@file{.#@var{file}.@var{revision}}, however). + +@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. See @ref{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. See @ref{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. + +Note that using a single @samp{-j @var{tagname}} option rather than +@samp{-j @var{branchname}} to merge changes from a branch will +often not remove files which were removed on the branch. +See @ref{Merging adds and removals} for more information. + +In addition, each @samp{-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}}. + +See @ref{Branching and merging}. + +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node update output +@appendixsubsec update output + +@code{update} and @code{checkout} keep you informed of +their 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 working directory, and for files +that you haven't changed but are not the most recent +versions available in the repository. + +@item P @var{file} +Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire +file. This accomplishes the same thing as @samp{U} using less bandwidth. + +@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} +@cindex .# files +@cindex __ files (VMS) +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 result of attempting to merge +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 revision that your modified file started +from. Resolve the conflict as described in +@ref{Conflicts example}. +@c "some systems" as in out-of-the-box OSes? Not as +@c far as I know. We need to advise sysadmins as well +@c as users how to set up this kind of purge, if that is +@c what they want. +@c We also might want to think about cleaner solutions, +@c like having CVS remove the .# file once the conflict +@c has been resolved or something like that. +(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.) Under @sc{vms}, the file name starts with +@file{__} rather than @file{.#}. + +@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}). +@end table + +@c ----- END MAN 1 ----- +@c --------------------------------------------------------------------- +@node Invoking CVS +@appendix Quick reference to CVS commands +@cindex Command reference +@cindex Reference, commands +@cindex Invoking CVS + +This appendix describes how to invoke @sc{cvs}, with +references to where each command or feature is +described in detail. For other references run the +@code{cvs --help} command, or see @ref{Index}. + +A @sc{cvs} command looks like: + +@example +cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ] +@end example + +Global options: + +@table @code +@item --allow-root=@var{rootdir} +Specify legal @sc{cvsroot} directory (server only) (not +in @sc{cvs} 1.9 and older). See @ref{Password +authentication server}. + +@item -a +Authenticate all communication (client only) (not in @sc{cvs} +1.9 and older). See @ref{Global options}. + +@item -b +Specify RCS location (@sc{cvs} 1.9 and older). See +@ref{Global options}. + +@item -d @var{root} +Specify the @sc{cvsroot}. See @ref{Repository}. + +@item -e @var{editor} +Edit messages with @var{editor}. See @ref{Committing +your changes}. + +@item -f +Do not read the @file{~/.cvsrc} file. See @ref{Global +options}. + +@item -H +@itemx --help +Print a help message. See @ref{Global options}. + +@item -n +Do not change any files. See @ref{Global options}. + +@item -Q +Be really quiet. See @ref{Global options}. + +@item -q +Be somewhat quiet. See @ref{Global options}. + +@item -r +Make new working files read-only. See @ref{Global options}. + +@item -s @var{variable}=@var{value} +Set a user variable. See @ref{Variables}. + +@item -T @var{tempdir} +Put temporary files in @var{tempdir}. See @ref{Global +options}. + +@item -t +Trace @sc{cvs} execution. See @ref{Global options}. + +@item -v +@item --version +Display version and copyright information for @sc{cvs}. + +@item -w +Make new working files read-write. See @ref{Global +options}. + +@item -x +Encrypt all communication (client only). +See @ref{Global options}. + +@item -z @var{gzip-level} +@cindex Compression +@cindex Gzip +Set the compression level (client only). +See @ref{Global options}. +@end table + +Keyword expansion modes (@pxref{Substitution modes}): + +@example +-kkv $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp $ +-kkvl $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ +-kk $@splitrcskeyword{Id}$ +-kv file1,v 1.1 1993/12/09 03:21:13 joe Exp +-ko @i{no expansion} +-kb @i{no expansion, file is binary} +@end example + +Keywords (@pxref{Keyword list}): + +@example +$@splitrcskeyword{Author}: joe $ +$@splitrcskeyword{Date}: 1993/12/09 03:21:13 $ +$@splitrcskeyword{Header}: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ +$@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ +$@splitrcskeyword{Locker}: harry $ +$@splitrcskeyword{Name}: snapshot_1_14 $ +$@splitrcskeyword{RCSfile}: file1,v $ +$@splitrcskeyword{Revision}: 1.1 $ +$@splitrcskeyword{Source}: /home/files/file1,v $ +$@splitrcskeyword{State}: Exp $ +$@splitrcskeyword{Log}: file1,v $ +Revision 1.1 1993/12/09 03:30:17 joe +Initial revision + +@end example + +@c The idea behind this table is that we want each item +@c to be a sentence or two at most. Preferably a +@c single line. +@c +@c In some cases refs to "foo options" are just to get +@c this thing written quickly, not because the "foo +@c options" node is really the best place to point. +Commands, command options, and command arguments: + +@table @code +@c ------------------------------------------------------------ +@item add [@var{options}] [@var{files}@dots{}] +Add a new file/directory. See @ref{Adding files}. + +@table @code +@item -k @var{kflag} +Set keyword expansion. + +@item -m @var{msg} +Set file description. +@end table + +@c ------------------------------------------------------------ +@item admin [@var{options}] [@var{files}@dots{}] +Administration of history files in the repository. See +@ref{admin}. +@c This list omits those options which are not +@c documented as being useful with CVS. That might be +@c a mistake... + +@table @code +@item -b[@var{rev}] +Set default branch. See @ref{Reverting local changes}. + +@item -c@var{string} +Set comment leader. + +@item -k@var{subst} +Set keyword substitution. See @ref{Keyword +substitution}. + +@item -l[@var{rev}] +Lock revision @var{rev}, or latest revision. + +@item -m@var{rev}:@var{msg} +Replace the log message of revision @var{rev} with +@var{msg}. + +@item -o@var{range} +Delete revisions from the repository. See +@ref{admin options}. + +@item -q +Run quietly; do not print diagnostics. + +@item -s@var{state}[:@var{rev}] +Set the state. See @ref{admin options} for more information on possible +states. + +@c Does not work for client/server CVS +@item -t +Set file description from standard input. + +@item -t@var{file} +Set file description from @var{file}. + +@item -t-@var{string} +Set file description to @var{string}. + +@item -u[@var{rev}] +Unlock revision @var{rev}, or latest revision. +@end table + +@c ------------------------------------------------------------ +@item annotate [@var{options}] [@var{files}@dots{}] +Show last revision where each line was modified. See +@ref{annotate}. + +@table @code +@item -D @var{date} +Annotate the most recent revision no later than +@var{date}. See @ref{Common options}. + +@item -F +Force annotation of binary files. (Without this option, +binary files are skipped with a message.) + +@item -f +Use head revision if tag/date not found. See +@ref{Common options}. + +@item -l +Local; run only in current working directory. @xref{Recursive behavior}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. + +@item -r @var{tag} +Annotate revision @var{tag}. See @ref{Common options}. +@end table + +@c ------------------------------------------------------------ +@item checkout [@var{options}] @var{modules}@dots{} +Get a copy of the sources. See @ref{checkout}. + +@table @code +@item -A +Reset any sticky tags/date/options. See @ref{Sticky +tags} and @ref{Keyword substitution}. + +@item -c +Output the module database. See @ref{checkout options}. + +@item -D @var{date} +Check out revisions as of @var{date} (is sticky). See +@ref{Common options}. + +@item -d @var{dir} +Check out into @var{dir}. See @ref{checkout options}. + +@item -f +Use head revision if tag/date not found. See +@ref{Common options}. + +@c Probably want to use rev1/rev2 style like for diff +@c -r. Here and in on-line help. +@item -j @var{rev} +Merge in changes. See @ref{checkout options}. + +@item -k @var{kflag} +Use @var{kflag} keyword expansion. See +@ref{Substitution modes}. + +@item -l +Local; run only in current working directory. @xref{Recursive behavior}. + +@item -N +Don't ``shorten'' module paths if -d specified. See +@ref{checkout options}. + +@item -n +Do not run module program (if any). See @ref{checkout options}. + +@item -P +Prune empty directories. See @ref{Moving directories}. + +@item -p +Check out files to standard output (avoids +stickiness). See @ref{checkout options}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. + +@item -r @var{tag} +Checkout revision @var{tag} (is sticky). See @ref{Common options}. + +@item -s +Like -c, but include module status. See @ref{checkout options}. +@end table + +@c ------------------------------------------------------------ +@item commit [@var{options}] [@var{files}@dots{}] +Check changes into the repository. See @ref{commit}. + +@table @code +@item -F @var{file} +Read log message from @var{file}. See @ref{commit options}. + +@item -f +@c What is this "disables recursion"? It is from the +@c on-line help; is it documented in this manual? +Force the file to be committed; disables recursion. +See @ref{commit options}. + +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -m @var{msg} +Use @var{msg} as log message. See @ref{commit options}. + +@item -n +Do not run module program (if any). See @ref{commit options}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. + +@item -r @var{rev} +Commit to @var{rev}. See @ref{commit options}. +@c FIXME: should be dragging over text from +@c commit options, especially if it can be cleaned up +@c and made concise enough. +@end table + +@c ------------------------------------------------------------ +@item diff [@var{options}] [@var{files}@dots{}] +Show differences between revisions. See @ref{diff}. +In addition to the options shown below, accepts a wide +variety of options to control output style, for example +@samp{-c} for context diffs. + +@table @code +@item -D @var{date1} +Diff revision for date against working file. See +@ref{diff options}. + +@item -D @var{date2} +Diff @var{rev1}/@var{date1} against @var{date2}. See +@ref{diff options}. + +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -N +Include diffs for added and removed files. See +@ref{diff options}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. + +@item -r @var{rev1} +Diff revision for @var{rev1} against working file. See +@ref{diff options}. + +@item -r @var{rev2} +Diff @var{rev1}/@var{date1} against @var{rev2}. See @ref{diff options}. +@end table + +@c ------------------------------------------------------------ +@item edit [@var{options}] [@var{files}@dots{}] +Get ready to edit a watched file. See @ref{Editing files}. + +@table @code +@item -a @var{actions} +Specify actions for temporary watch, where +@var{actions} is @code{edit}, @code{unedit}, +@code{commit}, @code{all}, or @code{none}. See +@ref{Editing files}. + +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. +@end table + +@c ------------------------------------------------------------ +@item editors [@var{options}] [@var{files}@dots{}] +See who is editing a watched file. See @ref{Watch information}. + +@table @code +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. +@end table + +@c ------------------------------------------------------------ +@item export [@var{options}] @var{modules}@dots{} +Export files from @sc{cvs}. See @ref{export}. + +@table @code +@item -D @var{date} +Check out revisions as of @var{date}. See +@ref{Common options}. + +@item -d @var{dir} +Check out into @var{dir}. See @ref{export options}. + +@item -f +Use head revision if tag/date not found. See +@ref{Common options}. + +@item -k @var{kflag} +Use @var{kflag} keyword expansion. See +@ref{Substitution modes}. + +@item -l +Local; run only in current working directory. @xref{Recursive behavior}. + +@item -N +Don't ``shorten'' module paths if -d specified. See +@ref{export options}. + +@item -n +Do not run module program (if any). See @ref{export options}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. + +@item -r @var{tag} +Checkout revision @var{tag}. See @ref{Common options}. +@end table + +@c ------------------------------------------------------------ +@item history [@var{options}] [@var{files}@dots{}] +Show repository access history. See @ref{history}. + +@table @code +@item -a +All users (default is self). See @ref{history options}. + +@item -b @var{str} +Back to record with @var{str} in module/file/repos +field. See @ref{history options}. + +@item -c +Report on committed (modified) files. See @ref{history options}. + +@item -D @var{date} +Since @var{date}. See @ref{history options}. + +@item -e +Report on all record types. See @ref{history options}. + +@item -l +Last modified (committed or modified report). See @ref{history options}. + +@item -m @var{module} +Report on @var{module} (repeatable). See @ref{history options}. + +@item -n @var{module} +In @var{module}. See @ref{history options}. + +@item -o +Report on checked out modules. See @ref{history options}. + +@item -p @var{repository} +In @var{repository}. See @ref{history options}. + +@item -r @var{rev} +Since revision @var{rev}. See @ref{history options}. + +@item -T +@c What the @#$@# is a TAG? Same as a tag? This +@c wording is also in the online-line help. +Produce report on all TAGs. See @ref{history options}. + +@item -t @var{tag} +Since tag record placed in history file (by anyone). +See @ref{history options}. + +@item -u @var{user} +For user @var{user} (repeatable). See @ref{history options}. + +@item -w +Working directory must match. See @ref{history options}. + +@item -x @var{types} +Report on @var{types}, one or more of +@code{TOEFWUPCGMAR}. See @ref{history options}. + +@item -z @var{zone} +Output for time zone @var{zone}. See @ref{history options}. +@end table + +@c ------------------------------------------------------------ +@item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{} +Import files into @sc{cvs}, using vendor branches. See +@ref{import}. + +@table @code +@item -b @var{bra} +Import to vendor branch @var{bra}. See +@ref{Multiple vendor branches}. + +@item -d +Use the file's modification time as the time of +import. See @ref{import options}. + +@item -k @var{kflag} +Set default keyword substitution mode. See +@ref{import options}. + +@item -m @var{msg} +Use @var{msg} for log message. See +@ref{import options}. + +@item -I @var{ign} +More files to ignore (! to reset). See +@ref{import options}. + +@item -W @var{spec} +More wrappers. See @ref{import options}. +@end table + +@c ------------------------------------------------------------ +@item init +Create a @sc{cvs} repository if it doesn't exist. See +@ref{Creating a repository}. + +@c ------------------------------------------------------------ +@item kserver +Kerberos authenticated server. +See @ref{Kerberos authenticated}. + +@c ------------------------------------------------------------ +@item log [@var{options}] [@var{files}@dots{}] +Print out history information for files. See @ref{log}. + +@table @code +@item -b +Only list revisions on the default branch. See @ref{log options}. + +@item -d @var{dates} +Specify dates (@var{d1}<@var{d2} for range, @var{d} for +latest before). See @ref{log options}. + +@item -h +Only print header. See @ref{log options}. + +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -N +Do not list tags. See @ref{log options}. + +@item -R +Only print name of RCS file. See @ref{log options}. + +@item -r@var{revs} +Only list revisions @var{revs}. See @ref{log options}. + +@item -s @var{states} +Only list revisions with specified states. See @ref{log options}. + +@item -t +Only print header and descriptive text. See @ref{log +options}. + +@item -w@var{logins} +Only list revisions checked in by specified logins. See @ref{log options}. +@end table + +@c ------------------------------------------------------------ +@item login +Prompt for password for authenticating server. See +@ref{Password authentication client}. + +@c ------------------------------------------------------------ +@item logout +Remove stored password for authenticating server. See +@ref{Password authentication client}. + +@c ------------------------------------------------------------ +@item pserver +Password authenticated server. +See @ref{Password authentication server}. + +@c ------------------------------------------------------------ +@item rannotate [@var{options}] [@var{modules}@dots{}] +Show last revision where each line was modified. See +@ref{annotate}. + +@table @code +@item -D @var{date} +Annotate the most recent revision no later than +@var{date}. See @ref{Common options}. + +@item -F +Force annotation of binary files. (Without this option, +binary files are skipped with a message.) + +@item -f +Use head revision if tag/date not found. See +@ref{Common options}. + +@item -l +Local; run only in current working directory. @xref{Recursive behavior}. + +@item -R +Operate recursively (default). @xref{Recursive behavior}. + +@item -r @var{tag} +Annotate revision @var{tag}. See @ref{Common options}. +@end table + +@c ------------------------------------------------------------ +@item rdiff [@var{options}] @var{modules}@dots{} +Show differences between releases. See @ref{rdiff}. + +@table @code +@item -c +Context diff output format (default). See @ref{rdiff options}. + +@item -D @var{date} +Select revisions based on @var{date}. See @ref{Common options}. + +@item -f +Use head revision if tag/date not found. See +@ref{Common options}. + +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. + +@item -r @var{rev} +Select revisions based on @var{rev}. See @ref{Common options}. + +@item -s +Short patch - one liner per file. See @ref{rdiff options}. + +@item -t +Top two diffs - last change made to the file. See +@ref{diff options}. + +@item -u +Unidiff output format. See @ref{rdiff options}. + +@item -V @var{vers} +Use RCS Version @var{vers} for keyword expansion (obsolete). See +@ref{rdiff options}. +@end table + +@c ------------------------------------------------------------ +@item release [@var{options}] @var{directory} +Indicate that a directory is no longer in use. See +@ref{release}. + +@table @code +@item -d +Delete the given directory. See @ref{release options}. +@end table + +@c ------------------------------------------------------------ +@item remove [@var{options}] [@var{files}@dots{}] +Remove an entry from the repository. See @ref{Removing files}. + +@table @code +@item -f +Delete the file before removing it. See @ref{Removing files}. + +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. +@end table + +@c ------------------------------------------------------------ +@item rlog [@var{options}] [@var{files}@dots{}] +Print out history information for modules. See @ref{log}. + +@table @code +@item -b +Only list revisions on the default branch. See @ref{log options}. + +@item -d @var{dates} +Specify dates (@var{d1}<@var{d2} for range, @var{d} for +latest before). See @ref{log options}. + +@item -h +Only print header. See @ref{log options}. + +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -N +Do not list tags. See @ref{log options}. + +@item -R +Only print name of RCS file. See @ref{log options}. + +@item -r@var{revs} +Only list revisions @var{revs}. See @ref{log options}. + +@item -s @var{states} +Only list revisions with specified states. See @ref{log options}. + +@item -t +Only print header and descriptive text. See @ref{log options}. + +@item -w@var{logins} +Only list revisions checked in by specified logins. See @ref{log options}. +@end table + +@c ------------------------------------------------------------ +@item rtag [@var{options}] @var{tag} @var{modules}@dots{} +Add a symbolic tag to a module. +See @ref{Revisions} and @ref{Branching and merging}. + +@table @code +@item -a +Clear tag from removed files that would not otherwise +be tagged. See @ref{Tagging add/remove}. + +@item -b +Create a branch named @var{tag}. See @ref{Branching and merging}. + +@item -B +Used in conjunction with -F or -d, enables movement and deletion of +branch tags. Use with extreme caution. + +@item -D @var{date} +Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. + +@item -d +Delete @var{tag}. See @ref{Modifying tags}. + +@item -F +Move @var{tag} if it already exists. See @ref{Modifying tags}. + +@item -f +Force a head revision match if tag/date not found. +See @ref{Tagging by date/tag}. + +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -n +No execution of tag program. See @ref{Common options}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. + +@item -r @var{rev} +Tag existing tag @var{rev}. See @ref{Tagging by date/tag}. +@end table + +@c ------------------------------------------------------------ +@item server +Rsh server. See @ref{Connecting via rsh}. + +@c ------------------------------------------------------------ +@item status [@var{options}] @var{files}@dots{} +Display status information in a working directory. See +@ref{File status}. + +@table @code +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. + +@item -v +Include tag information for file. See @ref{Tags}. +@end table + +@c ------------------------------------------------------------ +@item tag [@var{options}] @var{tag} [@var{files}@dots{}] +Add a symbolic tag to checked out version of files. +See @ref{Revisions} and @ref{Branching and merging}. + +@table @code +@item -b +Create a branch named @var{tag}. See @ref{Branching and merging}. + +@item -c +Check that working files are unmodified. See +@ref{Tagging the working directory}. + +@item -D @var{date} +Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. + +@item -d +Delete @var{tag}. See @ref{Modifying tags}. + +@item -F +Move @var{tag} if it already exists. See @ref{Modifying tags}. + +@item -f +Force a head revision match if tag/date not found. +See @ref{Tagging by date/tag}. + +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. + +@item -r @var{rev} +Tag existing tag @var{rev}. See @ref{Tagging by date/tag}. +@end table + +@c ------------------------------------------------------------ +@item unedit [@var{options}] [@var{files}@dots{}] +Undo an edit command. See @ref{Editing files}. + +@table @code +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -R +Operate recursively (default). @xref{Recursive behavior}. +@end table + +@c ------------------------------------------------------------ +@item update [@var{options}] [@var{files}@dots{}] +Bring work tree in sync with repository. See +@ref{update}. + +@table @code +@item -A +Reset any sticky tags/date/options. See @ref{Sticky +tags} and @ref{Keyword substitution}. + +@item -C +Overwrite locally modified files with clean copies from +the repository (the modified file is saved in +@file{.#@var{file}.@var{revision}}, however). + +@item -D @var{date} +Check out revisions as of @var{date} (is sticky). See +@ref{Common options}. + +@item -d +Create directories. See @ref{update options}. + +@item -f +Use head revision if tag/date not found. See +@ref{Common options}. + +@item -I @var{ign} +More files to ignore (! to reset). See +@ref{import options}. + +@c Probably want to use rev1/rev2 style like for diff +@c -r. Here and in on-line help. +@item -j @var{rev} +Merge in changes. See @ref{update options}. + +@item -k @var{kflag} +Use @var{kflag} keyword expansion. See +@ref{Substitution modes}. + +@item -l +Local; run only in current working directory. @xref{Recursive behavior}. + +@item -P +Prune empty directories. See @ref{Moving directories}. + +@item -p +Check out files to standard output (avoids +stickiness). See @ref{update options}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. + +@item -r @var{tag} +Checkout revision @var{tag} (is sticky). See @ref{Common options}. + +@item -W @var{spec} +More wrappers. See @ref{import options}. +@end table + +@c ------------------------------------------------------------ +@item version +@cindex version (subcommand) + +Display the version of @sc{cvs} being used. If the repository +is remote, display both the client and server versions. + +@c ------------------------------------------------------------ +@item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}] + +on/off: turn on/off read-only checkouts of files. See +@ref{Setting a watch}. + +add/remove: add or remove notification on actions. See +@ref{Getting Notified}. + +@table @code +@item -a @var{actions} +Specify actions for temporary watch, where +@var{actions} is @code{edit}, @code{unedit}, +@code{commit}, @code{all}, or @code{none}. See +@ref{Editing files}. + +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. +@end table + +@c ------------------------------------------------------------ +@item watchers [@var{options}] [@var{files}@dots{}] +See who is watching a file. See @ref{Watch information}. + +@table @code +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. +@end table + +@end table + +@c --------------------------------------------------------------------- +@node Administrative files +@appendix Reference manual for Administrative files +@cindex Administrative files (reference) +@cindex Files, reference manual +@cindex Reference manual (files) +@cindex CVSROOT (file) + +@c FIXME? Somewhere there needs to be a more "how-to" +@c guide to writing these. I think the triggers +@c (commitinfo, loginfo, taginfo, &c) are perhaps a +@c different case than files like modules. One +@c particular issue that people sometimes are +@c (unnecessarily?) worried about is performance, and +@c the impact of writing in perl or sh or ____. +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. For a +discussion of how to edit them, see @ref{Intro +administrative files}. + +The most important of these files is the @file{modules} +file, which defines the modules inside the repository. + +@menu +* modules:: Defining modules +* Wrappers:: Specify binary-ness based on file name +* Trigger Scripts:: Some notes on the commit support files and + taginfo, referenced below. +* commit files:: The commit support files (commitinfo, + verifymsg, editinfo, loginfo) +* taginfo:: Verifying/Logging tags +* rcsinfo:: Templates for the log messages +* cvsignore:: Ignoring files via cvsignore +* checkoutlist:: Adding your own administrative files +* history file:: History information +* Variables:: Various variables are expanded +* config:: Miscellaneous CVS configuration +@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. + +There are three basic types of modules: alias modules, +regular modules, and ampersand modules. The difference +between them is the way that they map files in the +repository to files in the working directory. In all +of the following examples, the top-level repository +contains a directory called @file{first-dir}, which +contains two files, @file{file1} and @file{file2}, and a +directory @file{sdir}. @file{first-dir/sdir} contains +a file @file{sfile}. + +@c FIXME: should test all the examples in this section. + +@menu +* Alias modules:: The simplest kind of module +* Regular modules:: +* Ampersand modules:: +* Excluding directories:: Excluding directories from a module +* Module options:: Regular and ampersand modules can take options +* Module program options:: How the modules ``program options'' programs + are run. +@end menu + +@node Alias modules +@appendixsubsec Alias modules +@cindex Alias modules +@cindex -a, in modules file + +Alias modules are the simplest kind of module: + +@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. +@end table + +For example, if the modules file contains: + +@example +amodule -a first-dir +@end example + +@noindent +then the following two commands are equivalent: + +@example +$ cvs co amodule +$ cvs co first-dir +@end example + +@noindent +and they each would provide output such as: + +@example +cvs checkout: Updating first-dir +U first-dir/file1 +U first-dir/file2 +cvs checkout: Updating first-dir/sdir +U first-dir/sdir/sfile +@end example + +@node Regular modules +@appendixsubsec Regular modules +@cindex Regular modules + +@table @code +@item @var{mname} [ options ] @var{dir} [ @var{files}@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. +@end table + +For example, if a module is defined by: + +@example +regmodule first-dir +@end example + +@noindent +then regmodule will contain the files from first-dir: + +@example +$ cvs co regmodule +cvs checkout: Updating regmodule +U regmodule/file1 +U regmodule/file2 +cvs checkout: Updating regmodule/sdir +U regmodule/sdir/sfile +$ +@end example + +By explicitly specifying files in the module definition +after @var{dir}, you can select particular files from +directory @var{dir}. Here is +an example: + +@example +regfiles first-dir/sdir sfile +@end example + +@noindent +With this definition, getting the regfiles module +will create a single working directory +@file{regfiles} containing the file listed, which +comes from a directory deeper +in the @sc{cvs} source repository: + +@example +$ cvs co regfiles +U regfiles/sfile +$ +@end example + +@node Ampersand modules +@appendixsubsec Ampersand modules +@cindex Ampersand modules +@cindex &, in modules file + +A module definition can refer to other modules by +including @samp{&@var{module}} in its definition. +@example +@var{mname} [ options ] @var{&module}@dots{} +@end example + +Then getting the module creates a subdirectory for each such +module, in the directory containing the module. For +example, if modules contains + +@example +ampermod &first-dir +@end example + +@noindent +then a checkout will create an @code{ampermod} directory +which contains a directory called @code{first-dir}, +which in turns contains all the directories and files +which live there. For example, the command + +@example +$ cvs co ampermod +@end example + +@noindent +will create the following files: + +@example +ampermod/first-dir/file1 +ampermod/first-dir/file2 +ampermod/first-dir/sdir/sfile +@end example + +There is one quirk/bug: the messages that @sc{cvs} +prints omit the @file{ampermod}, and thus do not +correctly display the location to which it is checking +out the files: + +@example +$ cvs co ampermod +cvs checkout: Updating first-dir +U first-dir/file1 +U first-dir/file2 +cvs checkout: Updating first-dir/sdir +U first-dir/sdir/sfile +$ +@end example + +Do not rely on this buggy behavior; it may get fixed in +a future release of @sc{cvs}. + +@c FIXCVS: What happens if regular and & modules are +@c combined, as in "ampermodule first-dir &second-dir"? +@c When I tried it, it seemed to just ignore the +@c "first-dir". I think perhaps it should be an error +@c (but this needs further investigation). +@c In addition to discussing what each one does, we +@c should put in a few words about why you would use one or +@c the other in various situations. + +@node Excluding directories +@appendixsubsec Excluding directories +@cindex Excluding directories, in modules file +@cindex !, in modules file + +An alias module may exclude particular directories from +other modules by using an exclamation mark (@samp{!}) +before the name of each directory to be excluded. + +For example, if the modules file contains: + +@example +exmodule -a !first-dir/sdir first-dir +@end example + +@noindent +then checking out the module @samp{exmodule} will check +out everything in @samp{first-dir} except any files in +the subdirectory @samp{first-dir/sdir}. +@c Note that the "!first-dir/sdir" sometimes must be listed +@c before "first-dir". That seems like a probable bug, in which +@c case perhaps it should be fixed (to allow either +@c order) rather than documented. See modules4 in testsuite. + +@node Module options +@appendixsubsec Module options +@cindex Options, in modules file + +Either regular modules or ampersand modules can contain +options, which supply additional information concerning +the module. + +@table @code +@cindex -d, in modules file +@item -d @var{name} +Name the working directory something other than the +module name. +@c FIXME: Needs a bunch of examples, analogous to the +@c examples for alias, regular, and ampersand modules +@c which show where the files go without -d. + +@cindex Export program +@cindex -e, in modules file +@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. +@c FIXME: Is it run on server? client? + +@cindex Checkout program +@cindex -o, in modules file +@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. See @ref{Module program options} for +information on how @var{prog} is called. +@c FIXME: Is it run on server? client? + +@cindex Status of a module +@cindex Module status +@cindex -s, in modules file +@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 +@cindex -t, in modules file +@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}. It is not run +when @code{tag} is executed. Generally you will find +that the @file{taginfo} file is a better solution (@pxref{taginfo}). +@c FIXME: Is it run on server? client? +@c Problems with -t include: +@c * It is run after the tag not before +@c * It doesn't get passed all the information that +@c taginfo does ("mov", &c). +@c * It only is run for rtag, not tag. +@end table + +You should also see @pxref{Module program options} about how the +``program options'' programs are run. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +@node Module program options +@appendixsubsec How the modules file ``program options'' programs are run +@cindex Modules file program options +@cindex -t, in modules file +@cindex -o, in modules file +@cindex -e, in modules file + +@noindent +For checkout, rtag, and export, the program is server-based, and as such the +following applies:- + +If using remote access methods (pserver, ext, etc.), +@sc{cvs} will execute this program on the server from a temporary +directory. The path is searched for this program. + +If using ``local access'' (on a local or remote NFS file system, i.e., +repository set just to a path), +the program will be executed from the newly checked-out tree, if +found there, or alternatively searched for in the path if not. + +The programs are all run after the operation has effectively +completed. + + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Wrappers +@appendixsec The cvswrappers file +@cindex cvswrappers (admin file) +@cindex CVSWRAPPERS, environment variable +@cindex Wrappers + +@c FIXME: need some better way of separating this out +@c by functionality. -m is +@c one feature, and -k is a another. And this discussion +@c should be better motivated (e.g. start with the +@c problems, then explain how the feature solves it). + +Wrappers refers to a @sc{cvs} feature which lets you +control certain settings based on the name of the file +which is being operated on. The settings are @samp{-k} +for binary files, and @samp{-m} for nonmergeable text +files. + +The @samp{-m} option +specifies the merge methodology that should be used when +a non-binary file is updated. @code{MERGE} means the usual +@sc{cvs} behavior: try to merge the files. @code{COPY} +means that @code{cvs update} will refuse to merge +files, as it also does for files specified as binary +with @samp{-kb} (but if the file is specified as +binary, there is no need to specify @samp{-m 'COPY'}). +@sc{cvs} will provide the user with the +two versions of the files, and require the user using +mechanisms outside @sc{cvs}, to insert any necessary +changes. + +@strong{WARNING: Do not use @code{COPY} with +@sc{cvs} 1.9 or earlier - such versions of @sc{cvs} will +copy one version of your file over the other, wiping +out the previous contents.} +@c Ordinarily we don't document the behavior of old +@c versions. But this one is so dangerous, I think we +@c must. I almost renamed it to -m 'NOMERGE' so we +@c could say "never use -m 'COPY'". +The @samp{-m} wrapper option only affects behavior when +merging is done on update; it does not affect how files +are stored. See @ref{Binary files}, for more on +binary files. + +The basic format of the file @file{cvswrappers} is: + +@c FIXME: @example is all wrong for this. Use @deffn or +@c something more sensible. +@example +wildcard [option value][option value]... + +where option is one of +-m update methodology value: MERGE or COPY +-k keyword expansion value: expansion mode + +and value is a single-quote delimited value. +@end example + +@ignore +@example +*.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY' +*.c -t 'indent %s %s' +@end example +@c When does the filter need to be an absolute pathname +@c and when will something like the above work? I +@c suspect it relates to the PATH of the server (which +@c in turn depends on all kinds of stuff, e.g. inetd +@c for pserver). I'm not sure whether/where to discuss +@c this. +@c FIXME: What do the %s's stand for? + +@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). + +@c What pitfalls arise when using indent this way? Is +@c it a winning thing to do? Would be nice to at least +@c hint at those issues; we want our examples to tell +@c how to solve problems, not just to say that cvs can +@c do certain things. +The last example line says that all files that end with +@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. + +Note that the @samp{-t}/@samp{-f} features do not +conveniently handle one portion of @sc{cvs}'s operation: +determining when files are modified. @sc{cvs} will still +want a file (or directory) to exist, and it will use +its modification time to determine whether a file is +modified. If @sc{cvs} erroneously thinks a file is +unmodified (for example, a directory is unchanged but +one of the files within it is changed), you can force +it to check in the file anyway by specifying the +@samp{-f} option to @code{cvs commit} (@pxref{commit +options}). +@c This is, of course, a serious design flaw in -t/-f. +@c Probably the whole functionality needs to be +@c redesigned (starting from requirements) to fix this. +@end ignore + +@c FIXME: We don't document -W or point to where it is +@c documented. Or .cvswrappers. +For example, the following command imports a +directory, treating files whose name ends in +@samp{.exe} as binary: + +@example +cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag +@end example + +@c Another good example, would be storing files +@c (e.g. binary files) compressed in the repository. +@c :::::::::::::::::: +@c cvswrappers +@c :::::::::::::::::: +@c *.t12 -m 'COPY' +@c *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY' +@c +@c :::::::::::::::::: +@c gunzipcp +@c :::::::::::::::::: +@c : +@c [ -f $1 ] || exit 1 +@c zcat $1 > /tmp/.#$1.$$ +@c mv /tmp/.#$1.$$ $1 +@c +@c :::::::::::::::::: +@c gzipcp +@c :::::::::::::::::: +@c : +@c DIRNAME=`echo $1 | sed -e "s|/.*/||g"` +@c if [ ! -d $DIRNAME ] ; then +@c DIRNAME=`echo $1 | sed -e "s|.*/||g"` +@c fi +@c gzip -c $DIRNAME > $2 +@c One catch--"cvs diff" will not invoke the wrappers +@c (probably a CVS bug, although I haven't thought it out). + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node Trigger Scripts +@appendixsec The Trigger Scripts +@cindex Info files +@cindex Trigger scripts + +Several of the administrative files support triggers, or the launching external +scripts or programs at specific times before or after particular events. The +individual files are discussed in the later sections, @ref{commit files} and +@ref{taginfo}, but some of the common elements are discussed here. + +All the trigger scripts are launched in a copy of the user sandbox being +committed, on the server, in client-server mode. In local mode, the scripts +are actually launched directly from the user sandbox directory being committed. +For most intents and purposes, the same scripts can be run in both locations +without alteration. + +@menu +* syntax:: The common syntax +* Trigger Script Security:: Trigger script security +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node syntax +@appendixsubsec The common syntax +@cindex Info files (syntax) +@cindex Syntax of info files +@cindex Common syntax of info files + +@c FIXME: having this so totally separate from the +@c Variables node is rather bogus. + +The administrative files such as @file{commitinfo}, +@file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc., +all have a common format. The purpose of the files are +described later on. The common syntax is described +here. + +@cindex Regular expression syntax +Each line contains the following: +@itemize @bullet +@item +@c Say anything about DEFAULT and ALL? Right now we +@c leave that to the description of each file (and in fact +@c the practice is inconsistent which is really annoying). +A regular expression. This is a basic regular +expression in the syntax used by GNU emacs. +@c FIXME: What we probably should be saying is "POSIX Basic +@c Regular Expression with the following extensions (`\(' +@c `\|' '+' etc)" +@c rather than define it with reference to emacs. +@c The reference to emacs is not strictly speaking +@c true, as we don't support \=, \s, or \S. Also it isn't +@c clear we should document and/or promise to continue to +@c support all the obscure emacs extensions like \<. +@c Also need to better cite (or include) full +@c documentation for the syntax. +@c Also see comment in configure.in about what happens to the +@c syntax if we pick up a system-supplied regexp matcher. + +@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 FIXME: need an example. In particular, show what +@c the regular expression is matched against (one +@c ordinarily clueful person got confused about whether it +@c includes the filename--"directory name" above should be +@c unambiguous but there is nothing like an example to +@c confirm people's understanding of this sort of thing). + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node Trigger Script Security +@appendixsubsec Security and the Trigger Scripts +@cindex Info files, security +@cindex Trigger scripts, security + +Security is a huge subject, and implementing a secure system is a non-trivial +task. This section will barely touch on all the issues involved, but it is +well to note that, as with any script you will be allowing an untrusted +user to run on your server, there are measures you can take to help prevent +your trigger scripts from being abused. + +For instance, since the CVS trigger scripts all run in a copy of the user's +sandbox on the server, a naively coded Perl trigger script which attempts to +use a Perl module that is not installed on the system can be hijacked by any +user with commit access who is checking in a file with the correct name. Other +scripting languages may be vulnerable to similar hacks. + +One way to make a script more secure, at least with Perl, is to use scripts +which invoke the @code{-T}, or "taint-check" switch on their @code{#!} line. +In the most basic terms, this causes Perl to avoid running code that may have +come from an external source. Please run the @code{perldoc perlsec} command +for more on Perl security. Again, other languages may implement other security +verification hooks which look more or less like Perl's "taint-check" mechanism. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node commit files +@appendixsec The commit support files +@cindex Committing, administrative support files + +There are three kinds of trigger scripts (@pxref{Trigger Scripts}) that can be +run at various times during a 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 verifymsg +The specified program is used to evaluate 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 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}). (obsolete) + +@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 +* commitinfo:: Pre-commit checking +* verifymsg:: How are log messages evaluated? +* editinfo:: Specifying how log messages are created + (obsolete) +* loginfo:: Where should log messages be sent? +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node commitinfo +@appendixsubsec Commitinfo +@cindex @file{commitinfo} +@cindex Commits, precommit verification of +@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). + +@cindex Exit status, of commitinfo +The first line with a regular expression matching the +directory within the repository will be used. If the +command returns a non-zero exit status the commit will +be aborted. +@c FIXME: need example(s) of what "directory within the +@c repository" means. + +@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 occurrences 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}. + +@cindex @file{commitinfo}, working directory +@cindex @file{commitinfo}, command environment +The command will be run in the root of the workspace +containing the new versions of any files the user would like +to modify (commit), @emph{or in a copy of the workspace on +the server (@pxref{Remote repositories})}. If a file is +being removed, there will be no copy of the file under the +current directory. If a file is being added, there will be +no corresponding archive file in the repository unless the +file is being resurrected. + +Note that both the repository directory and the corresponding +Attic (@pxref{Attic}) directory may need to be checked to +locate the archive file corresponding to any given file being +committed. Much of the information about the specific commit +request being made, including the destination branch, commit +message, and command line options specified, is not available +to the command. + +@c FIXME: should discuss using commitinfo to control +@c who has checkin access to what (e.g. Joe can check into +@c directories a, b, and c, and Mary can check into +@c directories b, c, and d--note this case cannot be +@c conveniently handled with unix groups). Of course, +@c adding a new set of features to CVS might be a more +@c natural way to fix this problem than telling people to +@c use commitinfo. +@c FIXME: Should make some reference, especially in +@c the context of controlling who has access, to the fact +@c that commitinfo can be circumvented. Perhaps +@c mention SETXID (but has it been carefully examined +@c for holes?). This fits in with the discussion of +@c general CVS security in "Password authentication +@c security" (the bit which is not pserver-specific). + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node verifymsg +@appendixsubsec Verifying log messages +@cindex @file{verifymsg} (admin file) +@cindex Log message, verifying + +Once you have entered a log message, you can evaluate +that message to check for specific content, such as +a bug ID. Use the @file{verifymsg} file to +specify a program that is used to verify the log message. +This program could be a simple script that checks +that the entered message contains the required fields. + +The @file{verifymsg} 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{verifymsg} 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 verification script in a +directory, and then overriding it in a subdirectory. + +@cindex DEFAULT in @file{verifymsg} +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 Exit status, of @file{verifymsg} +If the verification script exits with a non-zero exit status, +the commit is aborted. + +@cindex @file{verifymsg}, changing the log message +In the default configuration, CVS allows the +verification script to change the log message. This is +controlled via the RereadLogAfterVerify CVSROOT/config +option. + +When @samp{RereadLogAfterVerify=always} or +@samp{RereadLogAfterVerify=stat}, the log message will +either always be reread after the verification script +is run or reread only if the log message file status +has changed. + +@xref{config}, for more on CVSROOT/config options. + +It is NOT a good idea for a @file{verifymsg} script to +interact directly with the user in the various +client/server methods. For the @code{pserver} method, +there is no protocol support for communicating between +@file{verifymsg} and the client on the remote end. For the +@code{ext} and @code{server} methods, it is possible +for CVS to become confused by the characters going +along the same channel as the CVS protocol +messages. See @ref{Remote repositories}, for more +information on client/server setups. In addition, at the time +the @file{verifymsg} script runs, the CVS +server has locks in place in the repository. If control is +returned to the user here then other users may be stuck waiting +for access to the repository. + +This option can be useful if you find yourself using an +rcstemplate that needs to be modified to remove empty +elements or to fill in default values. It can also be +useful if the rcstemplate has changed in the repository +and the CVS/Template was not updated, but is able to be +adapted to the new format by the verification script +that is run by @file{verifymsg}. + +An example of an update might be to change all +occurrences of 'BugId:' to be 'DefectId:' (which can be +useful if the rcstemplate has recently been changed and +there are still checked-out user trees with cached +copies in the CVS/Template file of the older version). + +Another example of an update might be to delete a line +that contains 'BugID: none' from the log message after +validation of that value as being allowed is made. + +The following is a little silly example of a +@file{verifymsg} file, together with the corresponding +@file{rcsinfo} file, the log message template and an +verification 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.verify} is used to +evaluate the log message. + +@example +#!/bin/sh +# +# bugid.verify filename +# +# Verify that the log message contains a valid bugid +# on the first line. +# +if sed 1q < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then + exit 0 +elif sed 1q < $1 | grep '^BugId:[ ]*none$' > /dev/null; then + # It is okay to allow commits with 'BugId: none', + # but do not put that text into the real log message. + grep -v '^BugId:[ ]*none$' > $1.rewrite + mv $1.rewrite $1 + exit 0 +else + echo "No BugId found." + exit 1 +fi +@end example + +The @file{verifymsg} file contains this line: + +@example +^tc /usr/cvssupport/bugid.verify +@end example + +The @file{rcsinfo} file contains this line: + +@example +^tc /usr/cvssupport/tc.template +@end example + +The @file{config} file contains this line: + +@example +RereadLogAfterVerify=always +@end example + + + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node editinfo +@appendixsubsec Editinfo +@cindex editinfo (admin file) +@cindex Editor, specifying per module +@cindex Per-module editor +@cindex Log messages, editing + +@strong{The @file{editinfo} feature has been +rendered obsolete. To set a default editor for log +messages use the @code{CVSEDITOR}, @code{EDITOR} environment variables +(@pxref{Environment variables}) or the @samp{-e} global +option (@pxref{Global options}). See @ref{verifymsg}, +for information on the use of the @file{verifymsg} +feature for evaluating log messages.} + +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 default will be used. See @ref{Committing your changes}. + +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, +or when the @samp{-m} or @samp{-F} options to @code{cvs +commit} are used, @file{editinfo} will not be consulted. +There is no good workaround for this; use +@file{verifymsg} instead. + +@menu +* editinfo example:: Editinfo example +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node editinfo example +@appendixsubsubsec 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 +@appendixsubsec Loginfo +@cindex loginfo (admin file) +@cindex Storing log messages +@cindex Mailing log messages +@cindex Distributing log messages +@cindex Log messages + +@c "cvs commit" is not quite right. What we +@c mean is "when the repository gets changed" which +@c also includes "cvs import" and "cvs add" on a directory. +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. +Note that the filter program @strong{must} read @strong{all} +of the log information or @sc{cvs} may fail with a broken pipe signal. + +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 occurrences 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. + +The user may specify a format string as +part of the filter. The string is composed of a +@samp{%} followed by a space, or followed by a single +format character, or followed by a set of format +characters surrounded by @samp{@{} and @samp{@}} as +separators. The format characters are: + +@table @t +@item s +file name +@item V +old version number (pre-checkin) +@item v +new version number (post-checkin) +@end table + +All other characters that appear in a format string +expand to an empty field (commas separating fields are +still provided). + +For example, some valid format strings are @samp{%}, +@samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}. + +The output will be a space separated string of tokens enclosed in +quotation marks (@t{"}). +Any embedded dollar signs (@t{$}), backticks (@t{`}), +backslashes (@t{\}), or quotation marks will be preceded +by a backslash (this allows the shell to correctly parse it +as a single string, reguardless of the characters it contains). +For backwards compatibility, the first +token will be the repository subdirectory. The rest of the +tokens will be comma-delimited lists of the information +requested in the format string. For example, if +@samp{/u/src/master/yoyodyne/tc} is the repository, @samp{%@{sVv@}} +is the format string, and three files (@t{ChangeLog}, +@t{Makefile}, @t{foo.c}) were modified, the output +might be: + +@example +"yoyodyne/tc ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13" +@end example + +As another example, @samp{%@{@}} means that only the +name of the repository will be generated. + +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 +* Keeping a checked out copy:: Updating a tree on every checkin +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node loginfo example +@appendixsubsubsec 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}. +Commits to the @file{prog1} directory are 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? For example, if we wanted +@c to run both "cvs-log" and "Mail" for the CVSROOT +@c directory, it is kind of awkward if +@c only the first matching line is used. +@example +ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER +^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log +^prog1 Mail -s %s ceder +@end example + +The shell-script @file{/usr/local/bin/cvs-log} looks +like this: + +@example +#!/bin/sh +(echo "------------------------------------------------------"; + echo -n $2" "; + date; + echo; + cat) >> $1 +@end example + +@node Keeping a checked out copy +@appendixsubsubsec Keeping a checked out copy + +@c What other index entries? It seems like +@c people might want to use a lot of different +@c words for this functionality. +@cindex Keeping a checked out copy +@cindex Checked out copy, keeping +@cindex Web pages, maintaining with CVS + +It is often useful to maintain a directory tree which +contains files which correspond to the latest version +in the repository. For example, other developers might +want to refer to the latest sources without having to +check them out, or you might be maintaining a web site +with @sc{cvs} and want every checkin to cause the files +used by the web server to be updated. +@c Can we offer more details on the web example? Or +@c point the user at how to figure it out? This text +@c strikes me as sufficient for someone who already has +@c some idea of what we mean but not enough for the naive +@c user/sysadmin to understand it and set it up. + +The way to do this is by having loginfo invoke +@code{cvs update}. Doing so in the naive way will +cause a problem with locks, so the @code{cvs update} +must be run in the background. +@c Should we try to describe the problem with locks? +@c It seems like a digression for someone who just +@c wants to know how to make it work. +@c Another choice which might work for a single file +@c is to use "cvs -n update -p" which doesn't take +@c out locks (I think) but I don't see many advantages +@c of that and we might as well document something which +@c works for multiple files. +Here is an example for unix (this should all be on one line): + +@example +^cyclic-pages (date; cat; (sleep 2; cd /u/www/local-docs; + cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1 +@end example + +This will cause checkins to repository directories +starting with @code{cyclic-pages} to update the checked +out tree in @file{/u/www/local-docs}. +@c More info on some of the details? The "sleep 2" is +@c so if we are lucky the lock will be gone by the time +@c we start and we can wait 2 seconds instead of 30. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node rcsinfo +@appendixsec Rcsinfo +@cindex rcsinfo (admin file) +@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{verifymsg}, @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 occurrences of the name @samp{ALL} appearing as a +regular expression are used in addition to the first +matching regular expression or @samp{DEFAULT}. + +@c FIXME: should be offering advice, somewhere around +@c here, about where to put the template file. The +@c verifymsg example uses /usr/cvssupport but doesn't +@c say anything about what that directory is for or +@c whether it is hardwired into CVS or who creates +@c it or anything. In particular we should say +@c how to version control the template file. A +@c probably better answer than the /usr/cvssupport +@c stuff is to use checkoutlist (with xref to the +@c checkoutlist doc). +@c Also I am starting to see a connection between +@c this and the Keeping a checked out copy node. +@c Probably want to say something about that. +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{verifymsg}, 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 taginfo +@appendixsec Taginfo +@cindex taginfo (admin file) +@cindex Tags, logging +@cindex Tags, verifying +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 trigger scripts (@pxref{Trigger Scripts}), +where each line is a regular expression +followed by a command to execute (@pxref{syntax}). 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. + +Here is an example of using the @file{taginfo} file +to log @code{tag} and @code{rtag} +commands. In the @file{taginfo} file put: + +@example +ALL /usr/local/cvsroot/CVSROOT/loggit +@end example + +@noindent +Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the +following script: + +@example +#!/bin/sh +echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node cvsignore +@appendixsec Ignoring files via cvsignore +@cindex cvsignore (admin file), 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}. + +Specifying @samp{-I !} to @code{cvs import} will import +everything, which is generally what you want to do if +you are importing files from a pristine distribution or +any other source which is known to not contain any +extraneous files. However, looking at the rules above +you will see there is a fly in the ointment; if the +distribution contains any @file{.cvsignore} files, then +the patterns from those files will be processed even if +@samp{-I !} is specified. The only workaround is to +remove the @file{.cvsignore} files in order to do the +import. Because this is awkward, in the future +@samp{-I !} might be modified to override +@file{.cvsignore} files in each directory. + +Note that the syntax of the ignore files consists of a +series of lines, each of which contains a space +separated list of filenames. This offers no clean way +to specify filenames which contain spaces, but you can +use a workaround like @file{foo?bar} to match a file +named @file{foo bar} (it also matches @file{fooxbar} +and the like). Also note that there is currently no +way to specify comments. +@c FIXCVS? I don't _like_ this syntax at all, but +@c changing it raises all the usual compatibility +@c issues and I'm also not sure what to change it to. + +@node checkoutlist +@appendixsec The checkoutlist file +@cindex checkoutlist + +It may be helpful to use @sc{cvs} to maintain your own +files in the @file{CVSROOT} directory. For example, +suppose that you have a script @file{logcommit.pl} +which you run by including the following line in the +@file{commitinfo} administrative file: + +@example +ALL $CVSROOT/CVSROOT/logcommit.pl +@end example + +To maintain @file{logcommit.pl} with @sc{cvs} you would +add the following line to the @file{checkoutlist} +administrative file: + +@example +logcommit.pl +@end example + +The format of @file{checkoutlist} is one line for each +file that you want to maintain using @sc{cvs}, giving +the name of the file, followed optionally by more whitespace +and any error message that should print if the file cannot be +checked out into CVSROOT after a commit: + +@example +logcommit.pl Could not update CVSROOT/logcommit.pl. +@end example + +After setting up @file{checkoutlist} in this fashion, +the files listed there will function just like +@sc{cvs}'s built-in administrative files. For example, +when checking in one of the files you should get a +message such as: + +@example +cvs commit: Rebuilding administrative file database +@end example + +@noindent +and the checked out copy in the @file{CVSROOT} +directory should be updated. + +Note that listing @file{passwd} (@pxref{Password +authentication server}) in @file{checkoutlist} is not +recommended for security reasons. + +For information about keeping a checkout out copy in a +more general context than the one provided by +@file{checkoutlist}, see @ref{Keeping a checked out +copy}. + +@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{Creating a repository}). + +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}. + +@node Variables +@appendixsec Expansions in administrative files +@cindex Internal variables +@cindex Variables + +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 reasonable +expansion if pserver (@pxref{Password authenticated}) +is in use; 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 alphanumeric 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 +@cindex CVSROOT, internal variable +This is the absolute path to the current @sc{cvs} root directory. +@xref{Repository}, for a description of the various +ways to specify this, but note that the internal +variable contains just the directory and not any +of the access method information. + +@item RCSBIN +@cindex RCSBIN, internal variable +In @sc{cvs} 1.9.18 and older, this specified the +directory where @sc{cvs} was looking for @sc{rcs} +programs. Because @sc{cvs} no longer runs @sc{rcs} +programs, specifying this internal variable is now an +error. + +@item CVSEDITOR +@cindex CVSEDITOR, internal variable +@itemx EDITOR +@cindex EDITOR, internal variable +@itemx VISUAL +@cindex VISUAL, internal variable +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 +@cindex USER, internal variable +Username of the user running @sc{cvs} (on the @sc{cvs} +server machine). +When using pserver, this is the user specified in the repository +specification which need not be the same as the username the +server is running as (@pxref{Password authentication server}). +Do not confuse this with the environment variable of the same name. +@end table + +If you want to pass a value to the administrative files +which the user who is running @sc{cvs} can specify, +use a user variable. +@cindex User variables +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 + +@example +cvs -s TESTDIR=/work/local/tests +@end example + +@noindent +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. + +Environment variables passed to administrative files are: + +@table @code +@cindex environment variables, passed to administrative files + +@item CVS_USER +@cindex CVS_USER, environment variable +The @sc{cvs}-specific username provided by the user, if it +can be provided (currently just for the pserver access +method), and to the empty string otherwise. (@code{CVS_USER} +and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd} +is used to map @sc{cvs} usernames to system usernames.) + +@item LOGNAME +@cindex LOGNAME, environment variable +The username of the system user. + +@item USER +@cindex USER, environment variable +Same as @code{LOGNAME}. +Do not confuse this with the internal variable of the same name. +@end table + +@node config +@appendixsec The CVSROOT/config configuration file + +@cindex config, in CVSROOT +@cindex CVSROOT/config + +The administrative file @file{config} contains various +miscellaneous settings which affect the behavior of +@sc{cvs}. The syntax is slightly different from the +other administrative files. Variables are not +expanded. Lines which start with @samp{#} are +considered comments. +@c FIXME: where do we define comments for the other +@c administrative files. +Other lines consist of a keyword, @samp{=}, and a +value. Note that this syntax is very strict. +Extraneous spaces or tabs are not permitted. +@c See comments in parseinfo.c:parse_config for more +@c discussion of this strictness. + +Currently defined keywords are: + +@table @code +@cindex RCSBIN, in CVSROOT/config +@item RCSBIN=@var{bindir} +For @sc{cvs} 1.9.12 through 1.9.18, this setting told +@sc{cvs} to look for @sc{rcs} programs in the +@var{bindir} directory. Current versions of @sc{cvs} +do not run @sc{rcs} programs; for compatibility this +setting is accepted, but it does nothing. + +@cindex SystemAuth, in CVSROOT/config +@item SystemAuth=@var{value} +If @var{value} is @samp{yes}, then pserver should check +for users in the system's user database if not found in +@file{CVSROOT/passwd}. If it is @samp{no}, then all +pserver users must exist in @file{CVSROOT/passwd}. +The default is @samp{yes}. For more on pserver, see +@ref{Password authenticated}. + +@ignore +@cindex PreservePermissions, in CVSROOT/config +@item PreservePermissions=@var{value} +Enable support for saving special device files, +symbolic links, file permissions and ownerships in the +repository. The default value is @samp{no}. +@xref{Special Files}, for the full implications of using +this keyword. +@end ignore + +@cindex TopLevelAdmin, in CVSROOT/config +@item TopLevelAdmin=@var{value} +Modify the @samp{checkout} command to create a +@samp{CVS} directory at the top level of the new +working directory, in addition to @samp{CVS} +directories created within checked-out directories. +The default value is @samp{no}. + +This option is useful if you find yourself performing +many commands at the top level of your working +directory, rather than in one of the checked out +subdirectories. The @file{CVS} directory created there +will mean you don't have to specify @code{CVSROOT} for +each command. It also provides a place for the +@file{CVS/Template} file (@pxref{Working directory +storage}). + +@cindex LockDir, in CVSROOT/config +@item LockDir=@var{directory} +Put @sc{cvs} lock files in @var{directory} rather than +directly in the repository. This is useful if you want +to let users read from the repository while giving them +write access only to @var{directory}, not to the +repository. +It can also be used to put the locks on a very fast +in-memory file system to speed up locking and unlocking +the repository. +You need to create @var{directory}, but +@sc{cvs} will create subdirectories of @var{directory} as it +needs them. For information on @sc{cvs} locks, see +@ref{Concurrency}. + +@c Mention this in Compatibility section? +Before enabling the LockDir option, make sure that you +have tracked down and removed any copies of @sc{cvs} 1.9 or +older. Such versions neither support LockDir, nor will +give an error indicating that they don't support it. +The result, if this is allowed to happen, is that some +@sc{cvs} users will put the locks one place, and others will +put them another place, and therefore the repository +could become corrupted. @sc{cvs} 1.10 does not support +LockDir but it will print a warning if run on a +repository with LockDir enabled. + +@cindex LogHistory, in CVSROOT/config +@item LogHistory=@var{value} +Control what is logged to the @file{CVSROOT/history} file (@pxref{history}). +Default of @samp{TOEFWUPCGMAR} (or simply @samp{all}) will log +all transactions. Any subset of the default is +legal. (For example, to only log transactions that modify the +@file{*,v} files, use @samp{LogHistory=TMAR}.) + +@cindex RereadLogAfterVerify, in CVSROOT/config +@cindex @file{verifymsg}, changing the log message +@item RereadLogAfterVerify=@var{value} +Modify the @samp{commit} command such that CVS will reread the +log message after running the program specified by @file{verifymsg}. +@var{value} may be one of @samp{yes} or @samp{always}, indicating that +the log message should always be reread; @samp{no} +or @samp{never}, indicating that it should never be +reread; or @var{value} may be @samp{stat}, indicating +that the file should be checked with the file system +@samp{stat()} function to see if it has changed (see warning below) +before rereading. The default value is @samp{always}. + +@strong{The `stat' mode can cause CVS to pause for up to +one extra second per directory committed. This can be less IO and +CPU intensive but is not recommended for use with large repositories} + +@xref{verifymsg}, for more information on how verifymsg +may be used. + +@cindex IgnoreUnknownConfigKeys, in CVSROOT/config +@item IgnoreUnknownConfigKeys=@var{value} +If @var{value} is @samp{yes}, then @sc{cvs} should +ignore any keywords in @file{CVSROOT/config} which it +does not recognize. This option is intended primarily +for transitions between versions of @sc{cvs} which +support more configuration options in an environment +where a read-only mirror of the current @sc{cvs} server +may be maintained by someone else who is not yet ready +to upgrade to the same version. It is recommended that +this option be used only for a short time so that +problems with the @file{CVSROOT/config} file will be +found quickly. The default is @samp{no}. +@end table + +@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, environment variable +@item $CVSIGNORE +A whitespace-separated list of file name patterns that +@sc{cvs} should ignore. @xref{cvsignore}. + +@cindex CVSWRAPPERS, environment variable +@item $CVSWRAPPERS +A whitespace-separated list of file name patterns that +@sc{cvs} should treat as wrappers. @xref{Wrappers}. + +@cindex CVSREAD, environment variable +@cindex Read-only files, and 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. + +@item $CVSUMASK +Controls permissions of files in the repository. See +@ref{File permissions}. + +@item $CVSROOT +Should contain the full pathname to the root of the @sc{cvs} +source repository (where the @sc{rcs} 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. + +@item $CVSEDITOR +@cindex CVSEDITOR, environment variable +@itemx $EDITOR +@cindex EDITOR, environment variable +@itemx $VISUAL +@cindex VISUAL, environment variable +Specifies the program to use for recording log messages +during commit. @code{$CVSEDITOR} overrides +@code{$EDITOR}, which overrides @code{$VISUAL}. +See @ref{Committing your changes} for more or +@ref{Global options} for alternative ways of specifying a +log editor. + +@cindex PATH, environment variable +@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 HOME, environment variable +@item $HOME +@cindex HOMEPATH, environment variable +@item $HOMEPATH +@cindex HOMEDRIVE, environment variable +@item $HOMEDRIVE +Used to locate the directory where the @file{.cvsrc} +file, and other such files, are searched. On Unix, @sc{cvs} +just checks for @code{HOME}. On Windows NT, the system will +set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH}, +for example to @file{\joe}. On Windows 95, you'll +probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself. +@c We are being vague about whether HOME works on +@c Windows; see long comment in windows-NT/filesubr.c. + +@cindex CVS_RSH, environment variable +@item $CVS_RSH +Specifies the external program which @sc{cvs} connects with, +when @code{:ext:} access method is specified. +@pxref{Connecting via rsh}. + +@cindex CVS_SSH, environment variable +@item $CVS_SSH +Specifies the external program which @sc{cvs} connects with, +when @code{:extssh:} access method is specified. +@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 (and any +necessary arguments) when accessing a remote repository +using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods. +The default value for @code{:ext:} and @code{:server:} is @code{cvs}; +the default value for @code{:fork:} is the name used to run the client. +@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_CLIENT_PORT +Used in client-server mode to set the port to use when accessing the server +via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol +if the port is not specified in the CVSROOT. +@pxref{Remote repositories} + +@cindex CVS_RCMD_PORT, environment variable +@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, environment variable +@item $CVS_CLIENT_LOG +Used for debugging only in client-server +mode. If set, everything sent to the server is logged +into @file{@code{$CVS_CLIENT_LOG}.in} and everything +sent from the server is logged into +@file{@code{$CVS_CLIENT_LOG}.out}. + +@cindex CVS_SERVER_SLEEP, environment variable +@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 specified amount of +seconds so that you can attach to it with a debugger. + +@cindex CVS_IGNORE_REMOTE_ROOT, environment variable +@item $CVS_IGNORE_REMOTE_ROOT +For @sc{cvs} 1.10 and older, setting this variable +prevents @sc{cvs} from overwriting the @file{CVS/Root} +file when the @samp{-d} global option is specified. +Later versions of @sc{cvs} do not rewrite +@file{CVS/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no +effect. + +@cindex COMSPEC, environment variable +@item $COMSPEC +Used under OS/2 only. It specifies the name of the +command interpreter and defaults to @sc{cmd.exe}. + +@cindex TMPDIR, environment variable +@item $TMPDIR +@cindex TMP, environment variable +@itemx $TMP +@cindex TEMP, environment variable +@itemx $TEMP +@cindex Temporary files, location of +@c This is quite nuts. We don't talk about tempnam +@c or mkstemp which we sometimes use. The discussion +@c of "Global options" is semi-incoherent. +@c I'm not even sure those are the only inaccuracies. +@c Furthermore, the conventions are +@c pretty crazy and they should be simplified. +Directory in which temporary files are located. +The @sc{cvs} server uses +@code{TMPDIR}. @xref{Global options}, for a +description of how to specify this. +Some parts of @sc{cvs} will always use @file{/tmp} (via +the @code{tmpnam} function provided by the system). + +On Windows NT, @code{TMP} is used (via the @code{_tempnam} +function provided by the system). + +The @code{patch} program which is used by the @sc{cvs} +client uses @code{TMPDIR}, and if it is not set, uses +@file{/tmp} (at least with GNU patch 2.1). Note that +if your server and client are both running @sc{cvs} +1.9.10 or later, @sc{cvs} will not invoke an external +@code{patch} program. +@end table + +@node Compatibility +@appendix Compatibility between CVS Versions + +@cindex CVS, versions of +@cindex Versions, of CVS +@cindex Compatibility, between CVS versions +@c We don't mention versions older than CVS 1.3 +@c on the theory that it would clutter it up for the vast +@c majority of people, who don't have anything that old. +@c +The repository format is compatible going back to +@sc{cvs} 1.3. But see @ref{Watches Compatibility}, if +you have copies of @sc{cvs} 1.6 or older and you want +to use the optional developer communication features. +@c If you "cvs rm" and commit using 1.3, then you'll +@c want to run "rcs -sdead <file,v>" on each of the +@c files in the Attic if you then want 1.5 and +@c later to recognize those files as dead (I think the +@c symptom if this is not done is that files reappear +@c in joins). (Wait: the above will work but really to +@c be strictly correct we should suggest checking +@c in a new revision rather than just changing the +@c state of the head revision, shouldn't we?). +@c The old convert.sh script was for this, but it never +@c did get updated to reflect use of the RCS "dead" +@c state. +@c Note: this is tricky to document without confusing +@c people--need to carefully say what CVS version we +@c are talking about and keep in mind the distinction +@c between a +@c repository created with 1.3 and on which one now +@c uses 1.5+, and a repository on which one wants to +@c use both versions side by side (e.g. during a +@c transition period). +@c Wait, can't CVS just detect the case in which a file +@c is in the Attic but the head revision is not dead? +@c Not sure whether this should produce a warning or +@c something, and probably needs further thought, but +@c it would appear that the situation can be detected. +@c +@c We might want to separate out the 1.3 compatibility +@c section (for repository & working directory) from the +@c rest--that might help avoid confusing people who +@c are upgrading (for example) from 1.6 to 1.8. +@c +@c A minor incompatibility is if a current version of CVS +@c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will +@c see this as if there is no tag. Seems to me this is +@c too obscure to mention. + +The working directory format is compatible going back +to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3 +and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on +a working directory checked out with @sc{cvs} 1.3, +@sc{cvs} will convert it, but to go back to @sc{cvs} +1.3 you need to check out a new working directory with +@sc{cvs} 1.3. + +The remote protocol is interoperable going back to @sc{cvs} 1.5, but no +further (1.5 was the first official release with the remote protocol, +but some older versions might still be floating around). In many +cases you need to upgrade both the client and the server to take +advantage of new features and bug fixes, however. + +@c Perhaps should be saying something here about the +@c "D" lines in Entries (written by CVS 1.9; 1.8 and +@c older don't use them). These are supposed to be +@c compatible in both directions, but I'm not sure +@c they quite are 100%. One common gripe is if you +@c "rm -r" a directory and 1.9 gets confused, as it +@c still sees it in Entries. That one is fixed in +@c (say) 1.9.6. Someone else reported problems with +@c starting with a directory which was checked out with +@c an old version, and then using a new version, and +@c some "D" lines appeared, but not for every +@c directory, causing some directories to be skipped. +@c They weren't sure how to reproduce this, though. + +@c --------------------------------------------------------------------- +@node Troubleshooting +@appendix Troubleshooting + +If you are having trouble with @sc{cvs}, this appendix +may help. If there is a particular error message which +you are seeing, then you can look up the message +alphabetically. If not, you can look through the +section on other problems to see if your problem is +mentioned there. + +@menu +* Error messages:: Partial list of CVS errors +* Connection:: Trouble making a connection to a CVS server +* Other problems:: Problems not readily listed by error message +@end menu + +@ignore +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@c @node Bad administrative files +@appendixsec Bad administrative files + +@c -- Give hints on how to fix them +@end ignore + +@node Error messages +@appendixsec Partial list of error messages + +Here is a partial list of error messages that you may +see from @sc{cvs}. It is not a complete list---@sc{cvs} +is capable of printing many, many error messages, often +with parts of them supplied by the operating system, +but the intention is to list the common and/or +potentially confusing error messages. + +The messages are alphabetical, but introductory text +such as @samp{cvs update: } is not considered in +ordering them. + +In some cases the list includes messages printed by old +versions of @sc{cvs} (partly because users may not be +sure which version of @sc{cvs} they are using at any +particular moment). +@c If we want to start retiring messages, perhaps we +@c should pick a cutoff version (for example, no more +@c messages which are specific to versions before 1.9) +@c and then move the old messages to an "old messages" +@c node rather than deleting them completely. + +@table @code +@c FIXME: What is the correct way to format a multiline +@c error message here? Maybe @table is the wrong +@c choice? Texinfo gurus? +@item @var{file}:@var{line}: Assertion '@var{text}' failed +The exact format of this message may vary depending on +your system. It indicates a bug in @sc{cvs}, which can +be handled as described in @ref{BUGS}. + +@item cvs @var{command}: authorization failed: server @var{host} rejected access +This is a generic response when trying to connect to a +pserver server which chooses not to provide a +specific reason for denying authorization. Check that +the username and password specified are correct and +that the @code{CVSROOT} specified is allowed by @samp{--allow-root} +in @file{inetd.conf}. See @ref{Password authenticated}. + +@item cvs @var{command}: conflict: removed @var{file} was modified by second party +This message indicates that you removed a file, and +someone else modified it. To resolve the conflict, +first run @samp{cvs add @var{file}}. If desired, look +at the other party's modification to decide whether you +still want to remove it. If you don't want to remove +it, stop here. If you do want to remove it, proceed +with @samp{cvs remove @var{file}} and commit your +removal. +@c Tests conflicts2-142b* in sanity.sh test for this. + +@item cannot change permissions on temporary directory +@example +Operation not permitted +@end example +This message has been happening in a non-reproducible, +occasional way when we run the client/server testsuite, +both on Red Hat Linux 3.0.3 and 4.1. We haven't been +able to figure out what causes it, nor is it known +whether it is specific to Linux (or even to this +particular machine!). If the problem does occur on +other unices, @samp{Operation not permitted} would be +likely to read @samp{Not owner} or whatever the system +in question uses for the unix @code{EPERM} error. If +you have any information to add, please let us know as +described in @ref{BUGS}. If you experience this error +while using @sc{cvs}, retrying the operation which +produced it should work fine. +@c This has been seen in a variety of tests, including +@c multibranch-2, multibranch-5, and basic1-24-rm-rm, +@c so it doesn't seem particularly specific to any one +@c test. + +@item cvs [server aborted]: Cannot check out files into the repository itself +The obvious cause for this message (especially for +non-client/server @sc{cvs}) is that the @sc{cvs} root +is, for example, @file{/usr/local/cvsroot} and you try +to check out files when you are in a subdirectory, such +as @file{/usr/local/cvsroot/test}. However, there is a +more subtle cause, which is that the temporary +directory on the server is set to a subdirectory of the +root (which is also not allowed). If this is the +problem, set the temporary directory to somewhere else, +for example @file{/var/tmp}; see @code{TMPDIR} in +@ref{Environment variables}, for how to set the +temporary directory. + +@item cannot commit files as 'root' +See @samp{'root' is not allowed to commit files}. + +@c For one example see basica-1a10 in the testsuite +@c For another example, "cvs co ." on NT; see comment +@c at windows-NT/filesubr.c (expand_wild). +@c For another example, "cvs co foo/bar" where foo exists. +@item cannot open CVS/Entries for reading: No such file or directory +This generally indicates a @sc{cvs} internal error, and +can be handled as with other @sc{cvs} bugs +(@pxref{BUGS}). Usually there is a workaround---the +exact nature of which would depend on the situation but +which hopefully could be figured out. + +@c This is more obscure than it might sound; it only +@c happens if you run "cvs init" from a directory which +@c contains a CVS/Root file at the start. +@item cvs [init aborted]: cannot open CVS/Root: No such file or directory +This message is harmless. Provided it is not +accompanied by other errors, the operation has +completed successfully. This message should not occur +with current versions of @sc{cvs}, but it is documented +here for the benefit of @sc{cvs} 1.9 and older. + +@item cvs server: cannot open /root/.cvsignore: Permission denied +@itemx cvs [server aborted]: can't chdir(/root): Permission denied +See @ref{Connection}. + +@item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument +This message has been reported as intermittently +happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is +unknown; if you know more about what causes it, let us +know as described in @ref{BUGS}. + +@item cvs [@var{command} aborted]: cannot start server via rcmd +This, unfortunately, is a rather nonspecific error +message which @sc{cvs} 1.9 will print if you are +running the @sc{cvs} client and it is having trouble +connecting to the server. Current versions of @sc{cvs} +should print a much more specific error message. If +you get this message when you didn't mean to run the +client at all, you probably forgot to specify +@code{:local:}, as described in @ref{Repository}. + +@item ci: @var{file},v: bad diff output line: Binary files - and /tmp/T2a22651 differ +@sc{cvs} 1.9 and older will print this message +when trying to check in a binary file if +@sc{rcs} is not correctly installed. Re-read the +instructions that came with your @sc{rcs} distribution +and the @sc{install} file in the @sc{cvs} +distribution. Alternately, upgrade to a current +version of @sc{cvs}, which checks in files itself +rather than via @sc{rcs}. + +@item cvs checkout: could not check out @var{file} +With @sc{cvs} 1.9, this can mean that the @code{co} program +(part of @sc{rcs}) returned a failure. It should be +preceded by another error message, however it has been +observed without another error message and the cause is +not well-understood. With the current version of @sc{cvs}, +which does not run @code{co}, if this message occurs +without another error message, it is definitely a @sc{cvs} +bug (@pxref{BUGS}). +@c My current suspicion is that the RCS in the rcs (not +@c cvs/winnt/rcs57nt.zip) directory on the _Practical_ +@c CD is bad (remains to be confirmed). +@c There is also a report of something which looks +@c very similar on SGI, Irix 5.2, so I dunno. + +@item cvs [login aborted]: could not find out home directory +This means that you need to set the environment +variables that @sc{cvs} uses to locate your home directory. +See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in +@ref{Environment variables}. + +@item cvs update: could not merge revision @var{rev} of @var{file}: No such file or directory +@sc{cvs} 1.9 and older will print this message if there was +a problem finding the @code{rcsmerge} program. Make +sure that it is in your @code{PATH}, or upgrade to a +current version of @sc{cvs}, which does not require +an external @code{rcsmerge} program. + +@item cvs [update aborted]: could not patch @var{file}: No such file or directory +This means that there was a problem finding the +@code{patch} program. Make sure that it is in your +@code{PATH}. Note that despite appearances the message +is @emph{not} referring to whether it can find @var{file}. +If both the client and the server are running a current +version of @sc{cvs}, then there is no need for an +external patch program and you should not see this +message. But if either client or server is running +@sc{cvs} 1.9, then you need @code{patch}. + +@item cvs update: could not patch @var{file}; will refetch +This means that for whatever reason the client was +unable to apply a patch that the server sent. The +message is nothing to be concerned about, because +inability to apply the patch only slows things down and +has no effect on what @sc{cvs} does. +@c xref to update output. Or File status? +@c Or some place else that +@c explains this whole "patch"/P/Needs Patch thing? + +@item dying gasps from @var{server} unexpected +There is a known bug in the server for @sc{cvs} 1.9.18 +and older which can cause this. For me, this was +reproducible if I used the @samp{-t} global option. It +was fixed by Andy Piper's 14 Nov 1997 change to +src/filesubr.c, if anyone is curious. +If you see the message, +you probably can just retry the operation which failed, +or if you have discovered information concerning its +cause, please let us know as described in @ref{BUGS}. + +@item end of file from server (consult above messages if any) +The most common cause for this message is if you are +using an external @code{rsh} or @code{ssh} program and it exited with +an error. In this case the @code{rsh} program should +have printed a message, which will appear before the +above message. For more information on setting up a +@sc{cvs} client and server, see @ref{Remote repositories}. + +@item cvs [update aborted]: EOF in key in RCS file @var{file},v +@itemx cvs [checkout aborted]: EOF while looking for end of string in RCS file @var{file},v +This means that there is a syntax error in the given +@sc{rcs} file. Note that this might be true even if @sc{rcs} can +read the file OK; @sc{cvs} does more error checking of +errors in the RCS file. That is why you may see this +message when upgrading from @sc{cvs} 1.9 to @sc{cvs} +1.10. The likely cause for the original corruption is +hardware, the operating system, or the like. Of +course, if you find a case in which @sc{cvs} seems to +corrupting the file, by all means report it, +(@pxref{BUGS}). +There are quite a few variations of this error message, +depending on exactly where in the @sc{rcs} file @sc{cvs} +finds the syntax error. + +@cindex mkmodules +@item cvs commit: Executing 'mkmodules' +This means that your repository is set up for a version +of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs} +1.8 or later, the above message will be preceded by + +@example +cvs commit: Rebuilding administrative file database +@end example + +If you see both messages, the database is being rebuilt +twice, which is unnecessary but harmless. If you wish +to avoid the duplication, and you have no versions of +@sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules} +every place it appears in your @code{modules} +file. For more information on the @code{modules} file, +see @ref{modules}. + +@c This message comes from "co", and I believe is +@c possible only with older versions of CVS which call +@c co. The problem with being able to create the bogus +@c RCS file still exists, though (and I think maybe +@c there is a different symptom(s) now). +@c FIXME: Would be nice to have a more exact wording +@c for this message. +@item missing author +Typically this can happen if you created an RCS file +with your username set to empty. @sc{cvs} will, bogusly, +create an illegal RCS file with no value for the author +field. The solution is to make sure your username is +set to a non-empty value and re-create the RCS file. +@c "make sure your username is set" is complicated in +@c and of itself, as there are the environment +@c variables the system login name, &c, and it depends +@c on the version of CVS. + +@item cvs [checkout aborted]: no such tag @var{tag} +This message means that @sc{cvs} isn't familiar with +the tag @var{tag}. Usually this means that you have +mistyped a tag name; however there are (relatively +obscure) cases in which @sc{cvs} will require you to +@c Search sanity.sh for "no such tag" to see some of +@c the relatively obscure cases. +try a few other @sc{cvs} commands involving that tag, +before you find one which will cause @sc{cvs} to update +@cindex CVSROOT/val-tags file, forcing tags into +@cindex val-tags file, forcing tags into +the @file{val-tags} file; see discussion of val-tags in +@ref{File permissions}. You only need to worry about +this once for a given tag; when a tag is listed in +@file{val-tags}, it stays there. Note that using +@samp{-f} to not require tag matches does not override +this check; see @ref{Common options}. + +@item *PANIC* administration files missing +This typically means that there is a directory named +@sc{cvs} but it does not contain the administrative files +which @sc{cvs} puts in a CVS directory. If the problem is +that you created a CVS directory via some mechanism +other than @sc{cvs}, then the answer is simple, use a name +other than @sc{cvs}. If not, it indicates a @sc{cvs} bug +(@pxref{BUGS}). + +@item rcs error: Unknown option: -x,v/ +This message will be followed by a usage message for +@sc{rcs}. It means that you have an old version of +@sc{rcs} (probably supplied with your operating +system), as well as an old version of @sc{cvs}. +@sc{cvs} 1.9.18 and earlier only work with @sc{rcs} version 5 and +later; current versions of @sc{cvs} do not run @sc{rcs} programs. +@c For more information on installing @sc{cvs}, see +@c (FIXME: where? it depends on whether you are +@c getting binaries or sources or what). +@c The message can also say "ci error" or something +@c instead of "rcs error", I suspect. + +@item cvs [server aborted]: received broken pipe signal +This message can be caused by a loginfo program that fails to +read all of the log information from its standard input. +If you find it happening in any other circumstances, +please let us know as described in @ref{BUGS}. + +@item 'root' is not allowed to commit files +When committing a permanent change, @sc{cvs} makes a log entry of +who committed the change. If you are committing the change logged +in as "root" (not under "su" or other root-priv giving program), +@sc{cvs} cannot determine who is actually making the change. +As such, by default, @sc{cvs} disallows changes to be committed by users +logged in as "root". (You can disable this option by passing the +@code{--enable-rootcommit} option to @file{configure} and recompiling @sc{cvs}. +On some systems this means editing the appropriate @file{config.h} file +before building @sc{cvs}.) + +@item Terminated with fatal signal 11 +This message usually indicates that @sc{cvs} (the server, if you're +using client/server mode) has run out of (virtual) memory. +Although @sc{cvs} tries to catch the error and issue a more meaningful +message, there are many circumstances where that is not possible. +If you appear to have lots of memory available to the system, +the problem is most likely that you're running into a system-wide +limit on the amount of memory a single process can use or a +similar process-specific limit. +The mechanisms for displaying and setting such limits vary from +system to system, so you'll have to consult an expert for your +particular system if you don't know how to do that. + +@item Too many arguments! +This message is typically printed by the @file{log.pl} +script which is in the @file{contrib} directory in the +@sc{cvs} source distribution. In some versions of +@sc{cvs}, @file{log.pl} has been part of the default +@sc{cvs} installation. The @file{log.pl} script gets +called from the @file{loginfo} administrative file. +Check that the arguments passed in @file{loginfo} match +what your version of @file{log.pl} expects. In +particular, the @file{log.pl} from @sc{cvs} 1.3 and +older expects the log file as an argument whereas the +@file{log.pl} from @sc{cvs} 1.5 and newer expects the +log file to be specified with a @samp{-f} option. Of +course, if you don't need @file{log.pl} you can just +comment it out of @file{loginfo}. + +@item cvs [update aborted]: unexpected EOF reading @var{file},v +See @samp{EOF in key in RCS file}. + +@item cvs [login aborted]: unrecognized auth response from @var{server} +This message typically means that the server is not set +up properly. For example, if @file{inetd.conf} points +to a nonexistent cvs executable. To debug it further, +find the log file which inetd writes +(@file{/var/log/messages} or whatever inetd uses on +your system). For details, see @ref{Connection}, and +@ref{Password authentication server}. + +@item cvs commit: Up-to-date check failed for `@var{file}' +This means that someone else has committed a change to +that file since the last time that you did a @code{cvs +update}. So before proceeding with your @code{cvs +commit} you need to @code{cvs update}. @sc{cvs} will merge +the changes that you made and the changes that the +other person made. If it does not detect any conflicts +it will report @samp{M @var{file}} and you are ready +to @code{cvs commit}. If it detects conflicts it will +print a message saying so, will report @samp{C @var{file}}, +and you need to manually resolve the +conflict. For more details on this process see +@ref{Conflicts example}. + +@item Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3 +@example +Only one of [exEX3] allowed +@end example +This indicates a problem with the installation of +@code{diff3} and @code{rcsmerge}. Specifically +@code{rcsmerge} was compiled to look for GNU diff3, but +it is finding unix diff3 instead. The exact text of +the message will vary depending on the system. The +simplest solution is to upgrade to a current version of +@sc{cvs}, which does not rely on external +@code{rcsmerge} or @code{diff3} programs. + +@item warning: unrecognized response `@var{text}' from cvs server +If @var{text} contains a valid response (such as +@samp{ok}) followed by an extra carriage return +character (on many systems this will cause the second +part of the message to overwrite the first part), then +it probably means that you are using the @samp{:ext:} +access method with a version of rsh, such as most +non-unix rsh versions, which does not by default +provide a transparent data stream. In such cases you +probably want to try @samp{:server:} instead of +@samp{:ext:}. If @var{text} is something else, this +may signify a problem with your @sc{cvs} server. +Double-check your installation against the instructions +for setting up the @sc{cvs} server. +@c FIXCVS: should be printing CR as \r or \015 or some +@c such, probably. + +@item cvs commit: [@var{time}] waiting for @var{user}'s lock in @var{directory} +This is a normal message, not an error. See +@ref{Concurrency}, for more details. + +@item cvs commit: warning: editor session failed +@cindex Exit status, of editor +This means that the editor which @sc{cvs} is using exits with a nonzero +exit status. Some versions of vi will do this even when there was not +a problem editing the file. If so, point the +@code{CVSEDITOR} environment variable to a small script +such as: + +@example +#!/bin/sh +vi $* +exit 0 +@end example + +@item cvs update: warning: @var{file} was lost +This means that the working copy of @var{file} has been deleted +but it has not been removed from @sc{cvs}. +This is nothing to be concerned about, +the update will just recreate the local file from the repository. +(This is a convenient way to discard local changes to a file: +just delete it and then run @code{cvs update}.) + +@item cvs update: warning: @var{file} is not (any longer) pertinent +This means that the working copy of @var{file} has been deleted, +it has not been removed from @sc{cvs} in the current working directory, +but it has been removed from @sc{cvs} in some other working directory. +This is nothing to be concerned about, +the update would have removed the local file anyway. + +@end table + +@node Connection +@appendixsec Trouble making a connection to a CVS server + +This section concerns what to do if you are having +trouble making a connection to a @sc{cvs} server. If +you are running the @sc{cvs} command line client +running on Windows, first upgrade the client to +@sc{cvs} 1.9.12 or later. The error reporting in +earlier versions provided much less information about +what the problem was. If the client is non-Windows, +@sc{cvs} 1.9 should be fine. + +If the error messages are not sufficient to track down +the problem, the next steps depend largely on which +access method you are using. + +@table @code +@cindex :ext:, troubleshooting +@item :ext: +Try running the rsh program from the command line. For +example: "rsh servername cvs -v" should print @sc{cvs} +version information. If this doesn't work, you need to +fix it before you can worry about @sc{cvs} problems. + +@cindex :server:, troubleshooting +@item :server: +You don't need a command line rsh program to use this +access method, but if you have an rsh program around, +it may be useful as a debugging tool. Follow the +directions given for :ext:. + +@cindex :pserver:, troubleshooting +@item :pserver: +Errors along the lines of "connection refused" typically indicate +that inetd isn't even listening for connections on port 2401 +whereas errors like "connection reset by peer", +"received broken pipe signal", "recv() from server: EOF", +or "end of file from server" +typically indicate that inetd is listening for +connections but is unable to start @sc{cvs} (this is frequently +caused by having an incorrect path in @file{inetd.conf} +or by firewall software rejecting the connection). +"unrecognized auth response" errors are caused by a bad command +line in @file{inetd.conf}, typically an invalid option or forgetting +to put the @samp{pserver} command at the end of the line. +Another less common problem is invisible control characters that +your editor "helpfully" added without you noticing. + +One good debugging tool is to "telnet servername +2401". After connecting, send any text (for example +"foo" followed by return). If @sc{cvs} is working +correctly, it will respond with + +@example +cvs [pserver aborted]: bad auth protocol start: foo +@end example + +If instead you get: + +@example +Usage: cvs [cvs-options] command [command-options-and-arguments] +... +@end example + +@noindent +then you're missing the @samp{pserver} command at the end of the +line in @file{inetd.conf}; check to make sure that the entire command +is on one line and that it's complete. + +Likewise, if you get something like: + +@example +Unknown command: `pserved' + +CVS commands are: + add Add a new file/directory to the repository +... +@end example + +@noindent +then you've misspelled @samp{pserver} in some way. If it isn't +obvious, check for invisible control characters (particularly +carriage returns) in @file{inetd.conf}. + +If it fails to work at all, then make sure inetd is working +right. Change the invocation in @file{inetd.conf} to run the +echo program instead of cvs. For example: + +@example +2401 stream tcp nowait root /bin/echo echo hello +@end example + +After making that change and instructing inetd to +re-read its configuration file, "telnet servername +2401" should show you the text hello and then the +server should close the connection. If this doesn't +work, you need to fix it before you can worry about +@sc{cvs} problems. + +On AIX systems, the system will often have its own +program trying to use port 2401. This is AIX's problem +in the sense that port 2401 is registered for use with +@sc{cvs}. I hear that there is an AIX patch available +to address this problem. + +Another good debugging tool is the @samp{-d} +(debugging) option to inetd. Consult your system +documentation for more information. + +If you seem to be connecting but get errors like: + +@example +cvs server: cannot open /root/.cvsignore: Permission denied +cvs [server aborted]: can't chdir(/root): Permission denied +@end example + +@noindent +then you probably haven't specified @samp{-f} in @file{inetd.conf}. +(In releases prior to @sc{cvs} 1.11.1, this problem can be caused by +your system setting the @code{$HOME} environment variable +for programs being run by inetd. In this case, you can either +have inetd run a shell script that unsets @code{$HOME} and then runs +@sc{cvs}, or you can use @code{env} to run @sc{cvs} with a pristine +environment.) + +If you can connect successfully for a while but then can't, +you've probably hit inetd's rate limit. +(If inetd receives too many requests for the same service +in a short period of time, it assumes that something is wrong +and temporarily disables the service.) +Check your inetd documentation to find out how to adjust the +rate limit (some versions of inetd have a single rate limit, +others allow you to set the limit for each service separately.) +@end table + +@node Other problems +@appendixsec Other common problems + +Here is a list of problems which do not fit into the +above categories. They are in no particular order. + +@itemize @bullet +@item +On Windows, if there is a 30 second or so delay when +you run a @sc{cvs} command, it may mean that you have +your home directory set to @file{C:/}, for example (see +@code{HOMEDRIVE} and @code{HOMEPATH} in +@ref{Environment variables}). @sc{cvs} expects the home +directory to not end in a slash, for example @file{C:} +or @file{C:\cvs}. +@c FIXCVS: CVS should at least detect this and print an +@c error, presumably. + +@item +If you are running @sc{cvs} 1.9.18 or older, and +@code{cvs update} finds a conflict and tries to +merge, as described in @ref{Conflicts example}, but +doesn't tell you there were conflicts, then you may +have an old version of @sc{rcs}. The easiest solution +probably is to upgrade to a current version of +@sc{cvs}, which does not rely on external @sc{rcs} +programs. +@end itemize + +@c --------------------------------------------------------------------- +@node Credits +@appendix Credits + +@cindex Contributors (manual) +@cindex Credits (manual) +Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}> +wrote the manual pages which were distributed with +@sc{cvs} 1.3. Much of their text was copied into this +manual. 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} by David G. Grubbs has provided +useful material. The @sc{faq} is no longer maintained, +however, and this manual is about the closest thing there +is to a successor (with respect to documenting how to +use @sc{cvs}, at least). + +In addition, the following persons have helped by +telling me about mistakes I've made: + +@display +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}>. +@end display + +The list of contributors here is not comprehensive; for a more +complete list of who has contributed to this manual see +the file @file{doc/ChangeLog} in the @sc{cvs} source +distribution. + +@c --------------------------------------------------------------------- +@node BUGS +@appendix Dealing with bugs in CVS or this manual + +@cindex Bugs in this manual or CVS +Neither @sc{cvs} nor this manual is perfect, and they +probably never will be. If you are having trouble +using @sc{cvs}, or think you have found a bug, there +are a number of things you can do about it. Note that +if the manual is unclear, that can be considered a bug +in the manual, so these problems are often worth doing +something about as well as problems with @sc{cvs} itself. + +@cindex Reporting bugs +@cindex Bugs, reporting +@cindex Errors, reporting +@itemize @bullet +@item +If you want someone to help you and fix bugs that you +report, there are companies which will do that for a +fee. One such company is: + +@cindex Ximbiot +@cindex Support, getting CVS support +@example +Ximbiot LLC +Suite 230 +200 Diversion St. +Rochester Hills, MI 48307-6636 +USA +Email: info@@ximbiot.com +Phone: (248) 835-1260 +Fax: (248) 835-1263 +@url{http://ximbiot.com/} + +@end example + +@item +If you got @sc{cvs} through a distributor, such as an +operating system vendor or a vendor of freeware +@sc{cd-rom}s, you may wish to see whether the +distributor provides support. Often, they will provide +no support or minimal support, but this may vary from +distributor to distributor. + +@item +If you have the skills and time to do so, you may wish +to fix the bug yourself. If you wish to submit your +fix for inclusion in future releases of @sc{cvs}, see +the file @sc{hacking} in the @sc{cvs} source +distribution. It contains much more information on the +process of submitting fixes. + +@item +There may be resources on the net which can help. A +good place to start is: + +@example +@url{http://cvs.nongnu.org/} +@end example + +If you are so inspired, increasing the information +available on the net is likely to be appreciated. For +example, before the standard @sc{cvs} distribution +worked on Windows 95, there was a web page with some +explanation and patches for running @sc{cvs} on Windows +95, and various people helped out by mentioning this +page on mailing lists or newsgroups when the subject +came up. + +@item +It is also possible to report bugs to @email{bug-cvs@@nongnu.org}. +Note that someone may or may not want to do anything +with your bug report---if you need a solution consider +one of the options mentioned above. People probably do +want to hear about bugs which are particularly severe +in consequences and/or easy to fix, however. You can +also increase your odds by being as clear as possible +about the exact nature of the bug and any other +relevant information. The way to report bugs is to +send email to @email{bug-cvs@@nongnu.org}. Note +that submissions to @email{bug-cvs@@nongnu.org} may be distributed +under the terms of the @sc{gnu} Public License, so if +you don't like this, don't submit them. There is +usually no justification for sending mail directly to +one of the @sc{cvs} maintainers rather than to +@email{bug-cvs@@nongnu.org}; those maintainers who want to hear +about such bug reports read @email{bug-cvs@@nongnu.org}. Also note +that sending a bug report to other mailing lists or +newsgroups is @emph{not} a substitute for sending it to +@email{bug-cvs@@nongnu.org}. It is fine to discuss @sc{cvs} bugs on +whatever forum you prefer, but there are not +necessarily any maintainers reading bug reports sent +anywhere except @email{bug-cvs@@nongnu.org}. +@end itemize + +@cindex Known bugs in this manual or CVS +People often ask if there is a list of known bugs or +whether a particular bug is a known one. The file +@sc{bugs} in the @sc{cvs} source distribution is one +list of known bugs, but it doesn't necessarily try to +be comprehensive. Perhaps there will never be a +comprehensive, detailed list of known bugs. + +@c --------------------------------------------------------------------- +@node Index +@unnumbered Index +@cindex Index + +@printindex cp + +@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 0000000..b727a32 --- /dev/null +++ b/contrib/cvs/doc/cvsclient.texi @@ -0,0 +1,2080 @@ +\input texinfo @c -*- texinfo -*- + +@setfilename cvsclient.info +@include version-client.texi + +@dircategory Programming +@direntry +* cvsclient: (cvsclient). The CVS client/server protocol. +@end direntry + +@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{VERSION} 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. +* Connection and Authentication:: Various ways to connect to the server +* Password scrambling:: Scrambling used by pserver +* Protocol:: Complete description of the protocol +* Protocol Notes:: Possible enhancements, limitations, etc. 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{VERSION} 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 @ref{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. The protocol +expects a reliable transport that is transparent (that is, there is no +translation of characters, including characters such as +linefeeds or carriage returns), and can transmit all 256 octets (for +example for proper handling of binary files, compression, and +encryption). The encoding of characters specified by the protocol (the +names of requests and so on) is the invariant ISO 646 character set (a +subset of most popular character sets including ASCII and others). For +more details on running the protocol over the TCP reliable transport, +see @ref{Connection and Authentication}. + +@item +Security and authentication are handled outside this protocol (but see +below about @samp{cvs kserver} and @samp{cvs pserver}). + +@item +The protocol makes it possible for updates to be atomic with respect to +checkins; that is if someone commits changes to several files in one cvs +command, then an update by someone else would either get all the +changes, or none of them. The current @sc{cvs} server can't do this, +but that isn't the protocol's fault. + +@item +The protocol is, with a few exceptions, transaction-based. That is, the +client sends all its requests (without waiting for server responses), +and then waits for the server to send back all responses (without +waiting for further client requests). This has the advantage of +minimizing network turnarounds and the disadvantage of sometimes +transferring more data than would be necessary if there were a richer +interaction. Another, more subtle, advantage is that there is no need +for the protocol to provide locking for features such as making checkins +atomic with respect to updates. Any such locking can be handled +entirely by the server. A good server implementation (such as the +current @sc{cvs} server) will make sure that it does not have any such +locks in place whenever it is waiting for communication with the client; +this prevents one client on a slow or flaky network from interfering +with the work of others. + +@item +It is a general design goal to provide only one way to do a given +operation (where possible). For example, implementations have no choice +about whether to terminate lines with linefeeds or some other +character(s), and request and response names are case-sensitive. This +is to enhance interoperability. If a protocol allows more than one way +to do something, it is all too easy for some implementations to support +only some of them (perhaps accidentally). +@c I vaguely remember reading, probably in an RFC, about the problems +@c that were caused when some people decided that SMTP should accept +@c other line termination (in the message ("DATA")?) than CRLF. However, I +@c can't seem to track down the reference. +@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 server +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 GSS-API (see below) is recommended instead of kserver as a way +to support kerberos. + +@item pserver +The name @dfn{pserver} is somewhat confusing. It refers to both a +generic framework which allows the CVS protocol to support several +authentication mechanisms, and a name for a specific mechanism which +transfers a username and a cleartext password. Servers need not support +all mechanisms, and in fact servers will typically want to support only +those mechanisms which meet the relevant security needs. + +The pserver 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, and sends the following: + +@itemize @bullet +@item +the string @samp{BEGIN AUTH REQUEST}, a linefeed, +@item +the cvs root, a linefeed, +@item +the username, a linefeed, +@item +the password trivially encoded (see @ref{Password scrambling}), a +linefeed, +@item +the string @samp{END AUTH REQUEST}, and a linefeed. +@end itemize + +The client must send the +identical string for cvs root both here and later in the +@code{Root} request of the cvs +protocol itself. Servers are encouraged to enforce this restriction. +The possible server responses (each of which is followed by a linefeed) +are the following. Note that although there is a small similarity +between this authentication protocol and the cvs protocol, they are +separate. + +@table @code +@item I LOVE YOU +The authentication is successful. The client proceeds with the cvs +protocol itself. + +@item I HATE YOU +The authentication fails. After sending this response, the server may +close the connection. It is up to the server to decide whether to give +this response, which is generic, or a more specific response using +@samp{E} and/or @samp{error}. + +@item E @var{text} +Provide a message for the user. After this response, the authentication +protocol continues with another response. Typically the server will +provide a series of @samp{E} responses followed by @samp{error}. +Compatibility note: @sc{cvs} 1.9.10 and older clients will print +@code{unrecognized auth response} and @var{text}, and then exit, upon +receiving this response. + +@item error @var{code} @var{text} +The authentication fails. After sending this response, the server may +close the connection. The @var{code} is a code describing why it +failed, intended for computer consumption. The only code currently +defined is @samp{0} which is nonspecific, but clients must silently +treat any unrecognized codes as nonspecific. +The @var{text} should be supplied to the +user. Compatibility note: @sc{cvs} 1.9.10 and older clients will print +@code{unrecognized auth response} and @var{text}, and then exit, upon +receiving this response. +Note that @var{text} for this response, or the @var{text} in an @code{E} +response, is not designed for machine parsing. More vigorous use of +@var{code}, or future extensions, will be needed to prove a cleaner +machine-parseable indication of what the error was. +@end table + +@c If you are thinking of putting samp or code around BEGIN AUTH REQUEST +@c and friends, watch for overfull hboxes. +If the client wishes to merely authenticate without starting the cvs +protocol, the procedure is the same, except BEGIN AUTH REQUEST is +replaced with BEGIN VERIFICATION REQUEST, END AUTH REQUEST +is replaced with END VERIFICATION REQUEST, and upon receipt of +I LOVE YOU the connection is closed rather than continuing. + +Another mechanism is GSSAPI authentication. GSSAPI is a +generic interface to security services such as kerberos. GSSAPI is +specified in RFC2078 (GSSAPI version 2) and RFC1508 (GSSAPI version 1); +we are not aware of differences between the two which affect the +protocol in incompatible ways, so we make no attempt to specify one +version or the other. +The procedure here is to start with @samp{BEGIN +GSSAPI REQUEST}. GSSAPI authentication information is then exchanged +between the client and the server. Each packet of information consists +of a two byte big-endian length, followed by that many bytes of data. +After the GSSAPI authentication is complete, the server continues with +the responses described above (@samp{I LOVE YOU}, etc.). + +@item future possibilities +There are a nearly unlimited number of ways to connect and authenticate. +One might want to allow access based on IP address (similar to the usual +rsh protocol but with different/no restrictions on ports < 1024), to +adopt mechanisms such as Pluggable Authentication Modules (PAM), to +allow users to run their own servers under their own usernames without +root access, or any number of other possibilities. The way to add +future mechanisms, for the most part, should be to continue to use port +2401, but to use different strings in place of @samp{BEGIN AUTH +REQUEST}. +@end table + +@node Password scrambling +@chapter Password scrambling algorithm + +The pserver authentication protocol, as described in @ref{Connection and +Authentication}, trivially encodes the passwords. This is only to +prevent inadvertent compromise; it provides no protection against even a +relatively unsophisticated attacker. For comparison, HTTP Basic +Authentication (as described in RFC2068) uses BASE64 for a similar +purpose. CVS uses its own algorithm, described here. + +The scrambled password starts with @samp{A}, which serves to identify +the scrambling algorithm in use. After that follows a single octet for +each character in the password, according to a fixed encoding. The +values are shown here, with the encoded values in decimal. Control +characters, space, and characters outside the invariant ISO 646 +character set are not shown; such characters are not recommended for use +in passwords. There is a long discussion of character set issues in +@ref{Protocol Notes}. + +@example + 0 111 P 125 p 58 +! 120 1 52 A 57 Q 55 a 121 q 113 +" 53 2 75 B 83 R 54 b 117 r 32 + 3 119 C 43 S 66 c 104 s 90 + 4 49 D 46 T 124 d 101 t 44 +% 109 5 34 E 102 U 126 e 100 u 98 +& 72 6 82 F 40 V 59 f 69 v 60 +' 108 7 81 G 89 W 47 g 73 w 51 +( 70 8 95 H 38 X 92 h 99 x 33 +) 64 9 65 I 103 Y 71 i 63 y 97 +* 76 : 112 J 45 Z 115 j 94 z 62 ++ 67 ; 86 K 50 k 93 +, 116 < 118 L 42 l 39 +- 74 = 110 M 123 m 37 +. 68 > 122 N 91 n 61 +/ 87 ? 105 O 35 _ 56 o 48 +@end example + +@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; @dfn{requests} are what the client sends and +@dfn{responses} are what the server sends. In general, the connection is +governed by the client---the server does not send responses without +first receiving requests to do so; see @ref{Response intro} for more +details of this convention. + +It is typical, early in the connection, for the client to transmit a +@code{Valid-responses} request, containing all the responses it +supports, followed by a @code{valid-requests} request, which elicits +from the server a @code{Valid-requests} response containing all the +requests it understands. In this way, the client and server each find +out what the other supports before exchanging large amounts of data +(such as file contents). + +@c Hmm, having 3 sections in this menu makes a certain amount of sense +@c but that structure gets lost in the printed manual (not sure about +@c HTML). Perhaps there is a better way. +@menu + +General protocol conventions: + +* Entries Lines:: Transmitting RCS data +* File Modes:: Read, write, execute, and possibly more... +* Filenames:: Conventions regarding filenames +* File transmissions:: How file contents are transmitted +* Strings:: Strings in various requests and responses +* Dates:: Times and dates + +The protocol itself: + +* Request intro:: General conventions relating to requests +* Requests:: List of requests +* Response intro:: General conventions relating to responses +* Response pathnames:: The "pathname" in responses +* Responses:: List of responses +* Text tags:: More details about the MT response + +An example session, and some further observations: + +* Example:: A conversation between client and server +* Requirements:: Things not to omit from an implementation +* Obsolete:: Former protocol features +@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. + +@c FIXME: should distinguish sender and receiver behavior here; the +@c "anything else" and "does not start with" are intended for future +@c expansion, and we should specify a sender behavior. +@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. + +@var{options} signifies the keyword expansion options (for example +@samp{-ko}). In an @code{Entry} request, this indicates the options +that were specified with the file from the previous file updating +response (@pxref{Response intro}, for a list of file updating +responses); if the client is specifying the @samp{-k} or @samp{-A} +option to @code{update}, then it is the server which figures out what +overrides what. + +@node File Modes +@section File 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). + +Characters outside the invariant ISO 646 character set should be avoided +in filenames. This restriction may need to be relaxed to allow for +characters such as @samp{[} and @samp{]} (see above about non-unix +servers); this has not been carefully considered (and currently +implementations probably use whatever character sets that the operating +systems they are running on allow, and/or that users specify). Of +course the most portable practice is to restrict oneself further, to the +POSIX portable filename character set as specified in POSIX.1. + +@node File transmissions +@section File transmissions + +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 +linefeed, 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} (RFC1952/1951) compression. 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 linefeed iff that file (or its +compressed form) ends with a linefeed. + +The encoding of file contents depends on the value for the @samp{-k} +option. If the file is binary (as specified by the @samp{-kb} option in +the appropriate place), then it is just a certain number of octets, and +the protocol contributes nothing towards determining the encoding (using +the file name is one widespread, if not universally popular, mechanism). +If the file is text (not binary), then the file is sent as a series of +lines, separated by linefeeds. If the keyword expansion is set to +something other than @samp{-ko}, then it is expected that the file +conform to the RCS expectations regarding keyword expansion---in +particular, that it is in a character set such as ASCII in which 0x24 is +a dollar sign (@samp{$}). + +@node Strings +@section Strings + +In various contexts, for example the @code{Argument} request and the +@code{M} response, one transmits what is essentially an arbitrary +string. Often this will have been supplied by the user (for example, +the @samp{-m} option to the @code{ci} request). The protocol has no +mechanism to specify the character set of such strings; it would be +fairly safe to stick to the invariant ISO 646 character set but the +existing practice is probably to just transmit whatever the user +specifies, and hope that everyone involved agrees which character set is +in use, or sticks to a common subset. + +@node Dates +@section Dates + +The protocol contains times and dates in various places. + +For the @samp{-D} option to the @code{annotate}, @code{co}, @code{diff}, +@code{export}, @code{history}, @code{rannotate}, @code{rdiff}, +@code{rtag}, @code{tag}, +and @code{update} requests, the server should support two formats: + +@example +26 May 1997 13:01:40 -0000 ; @r{RFC 822 as modified by RFC 1123} +5/26/1997 13:01:40 GMT ; @r{traditional} +@end example + +The former format is preferred; the latter however is sent by the CVS +command line client (versions 1.5 through at least 1.9). + +For the @samp{-d} option to the @code{log} and @code{rlog} requests, +servers should at +least support RFC 822/1123 format. Clients are encouraged to use this +format too (the command line CVS client, version 1.10 and older, just passed +along the date format specified by the user, however). + +The @code{Mod-time} response and @code{Checkin-time} request use RFC +822/1123 format (see the descriptions of that response and request for +details). + +For @code{Notify}, see the description of that request. + +@node Request intro +@section Request intro + +By convention, requests which begin with a capital letter do not elicit +a response from the server, while all others do -- save one. The +exception is @samp{gzip-file-contents}. Unrecognized requests will +always elicit a response from the server, even if that request begins +with a capital letter. + +The term @dfn{command} means a request which expects a response (except +@code{valid-requests}). The general model is that the client transmits +a great number of requests, but nothing happens until the very end when +the client transmits a command. Although the intention is that +transmitting several commands in one connection should be legal, +existing servers probably have some bugs with some combinations of more +than one command, and so clients may find it necessary to make several +connections in some cases. This should be thought of as a workaround +rather than a desired attribute of the protocol. + +@node Requests +@section Requests + +Here are the requests: + +@table @code +@item Root @var{pathname} \n +Response expected: no. Tell the server which @code{CVSROOT} to use. +Note that @var{pathname} is @emph{not} a fully qualified @code{CVSROOT} +variable, but only the local directory part of it. @var{pathname} must +already exist on the server. Again, @var{pathname} @emph{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. + +The @code{Root} request must be sent only once, and it must be sent +before any requests other than @code{Valid-responses}, +@code{valid-requests}, @code{UseUnchanged}, @code{Set}, +@code{Global_option}, @code{noop}, or @code{version}. + +@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. +The @code{Root} request need not have been previously sent. + +@item valid-requests \n +Response expected: yes. +Ask the server to send back a @code{Valid-requests} response. +The @code{Root} request need not have been previously sent. + +@item Directory @var{local-directory} \n +Additional data: @var{repository} \n. Response expected: no. +Tell the server what directory to use. The @var{repository} 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 +@code{Directory} for each directory in which there will be an +@code{Entry} or @code{Modified}, and then a final @code{Directory} +for the original directory, then the command. +The @var{local-directory} is relative to +the top level at which the command is occurring (i.e., the last +@code{Directory} which is sent before the command); +to indicate that top level, @samp{.} should be sent for +@var{local-directory}. + +Here is an example of where a client gets @var{repository} and +@var{local-directory}. Suppose that there is a module defined by + +@example +moddir 1dir +@end example + +That is, one can check out @code{moddir} and it will take @code{1dir} in +the repository and check it out to @code{moddir} in the working +directory. Then an initial check out could proceed like this: + +@example +C: Root /home/kingdon/zwork/cvsroot +. . . +C: Argument moddir +C: Directory . +C: /home/kingdon/zwork/cvsroot +C: co +S: Clear-sticky moddir/ +S: /home/kingdon/zwork/cvsroot/1dir/ +. . . +S: ok +@end example + +In this example the response shown is @code{Clear-sticky}, but it could +be another response instead. Note that it returns two pathnames. +The first one, @file{moddir/}, indicates the working +directory to check out into. The second one, ending in @file{1dir/}, +indicates the directory to pass back to the server in a subsequent +@code{Directory} request. For example, a subsequent @code{update} +request might look like: + +@example +C: Directory moddir +C: /home/kingdon/zwork/cvsroot/1dir +. . . +C: update +@end example + +For a given @var{local-directory}, the repository will be the same for +each of the responses, so one can use the repository from whichever +response is most convenient. Typically a client will store the +repository along with the sources for each @var{local-directory}, use +that same setting whenever operating on that @var{local-directory}, and +not update the setting as long as the @var{local-directory} exists. + +A client is free to rename a @var{local-directory} at any time (for +example, in response to an explicit user request). While it is true +that the server supplies a @var{local-directory} to the client, as noted +above, this is only the default place to put the directory. Of course, +the various @code{Directory} requests for a single command (for example, +@code{update} or @code{ci} request) should name a particular directory +with the same @var{local-directory}. + +Each @code{Directory} request specifies a brand-new +@var{local-directory} and @var{repository}; that is, +@var{local-directory} and @var{repository} are never relative to paths +specified in any previous @code{Directory} request. + +Here's a more complex example, in which we request an update of a +working directory which has been checked out from multiple places in the +repository. + +@example +C: Argument dir1 +C: Directory dir1 +C: /home/foo/repos/mod1 +. . . +C: Argument dir2 +C: Directory dir2 +C: /home/foo/repos/mod2 +. . . +C: Argument dir3 +C: Directory dir3/subdir3 +C: /home/foo/repos/mod3 +. . . +C: update +@end example + +While directories @code{dir1} and @code{dir2} will be handled in similar +fashion to the other examples given above, @code{dir3} is slightly +different from the server's standpoint. Notice that module @code{mod3} +is actually checked out into @code{dir3/subdir3}, meaning that directory +@code{dir3} is either empty or does not contain data checked out from +this repository. + +The above example will work correctly in @sc{cvs} 1.10.1 and later. The +server will descend the tree starting from all directories mentioned in +@code{Argument} requests and update those directories specifically +mentioned in @code{Directory} requests. + +Previous versions of @sc{cvs} (1.10 and earlier) do not behave the same +way. While the descent of the tree begins at all directories mentioned +in @code{Argument} requests, descent into subdirectories only occurs if +a directory has been mentioned in a @code{Directory} request. +Therefore, the above example would succeed in updating @code{dir1} and +@code{dir2}, but would skip @code{dir3} because that directory was not +specifically mentioned in a @code{Directory} request. A functional +version of the above that would run on a 1.10 or earlier server is as +follows: + +@example +C: Argument dir1 +C: Directory dir1 +C: /home/foo/repos/mod1 +. . . +C: Argument dir2 +C: Directory dir2 +C: /home/foo/repos/mod2 +. . . +C: Argument dir3 +C: Directory dir3 +C: /home/foo/repos/. +. . . +C: Directory dir3/subdir3 +C: /home/foo/repos/mod3 +. . . +C: update +@end example + +Note the extra @code{Directory dir3} request. It might be better to use +@code{Emptydir} as the repository for the @code{dir3} directory, but the +above will certainly work. + +One more peculiarity of the 1.10 and earlier protocol is the ordering of +@code{Directory} arguments. In order for a subdirectory to be +registered correctly for descent by the recursion processor, its parent +must be sent first. For example, the following would not work to update +@code{dir3/subdir3}: + +@example +. . . +C: Argument dir3 +C: Directory dir3/subdir3 +C: /home/foo/repos/mod3 +. . . +C: Directory dir3 +C: /home/foo/repos/. +. . . +C: update +@end example + +The implementation of the server in 1.10 and earlier writes the +administration files for a given directory at the time of the +@code{Directory} request. It also tries to register the directory with +its parent to mark it for recursion. In the above example, at the time +@code{dir3/subdir3} is created, the physical directory for @code{dir3} +will be created on disk, but the administration files will not have been +created. Therefore, when the server tries to register +@code{dir3/subdir3} for recursion, the operation will silently fail +because the administration files do not yet exist for @code{dir3}. + +@item Max-dotdot @var{level} \n +Response expected: no. +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{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{Directory} has a sticky tag or date @var{tagspec}. +The first character of @var{tagspec} is @samp{T} for a tag, @samp{D} +for a date, or some other character supplied by a Set-sticky response +from a previous request to the server. The remainder of @var{tagspec} +contains the actual tag or date, again as supplied by Set-sticky. + +The server should remember @code{Static-directory} and @code{Sticky} +requests for a particular directory; the client need not resend them +each time it sends a @code{Directory} request for a given directory. +However, the server is not obliged to remember them beyond the context +of a single command. + +@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{Directory}. 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{Is-modified}, or @code{Unchanged}, +it means the file is +lost (does not exist in the working directory). If both @code{Entry} +and one of @code{Modified}, @code{Is-modified}, or @code{Unchanged} are +sent for the same file, @code{Entry} must be sent first. For a +given file, one can send @code{Modified}, @code{Is-modified}, or +@code{Unchanged}, but not more than one of these three. + +@item Kopt @var{option} \n +This indicates to the server which keyword expansion options to use for +the file specified by the next @code{Modified} or @code{Is-modified} +request (for example @samp{-kb} for a binary file). This is similar to +@code{Entry}, but is used for a file for which there is no entries line. +Typically this will be a file being added via an @code{add} or +@code{import} request. The client may not send both @code{Kopt} and +@code{Entry} for the same file. + +@item Checkin-time @var{time} \n +For the file specified by the next @code{Modified} request, use +@var{time} as the time of the checkin. The @var{time} is in the format +specified by RFC822 as modified by RFC1123. The client may specify any +timezone it chooses; servers will want to convert that to their own +timezone as appropriate. An example of this format is: + +@example +26 May 1997 13:01:40 -0400 +@end example + +There is no requirement that the client and server clocks be +synchronized. The client just sends its recommendation for a timestamp +(based on file timestamps or whatever), and the server should just believe +it (this means that the time might be in the future, for example). + +Note that this is not a general-purpose way to tell the server about the +timestamp of a file; that would be a separate request (if there are +servers which can maintain timestamp and time of checkin separately). + +This request should affect the @code{import} request, and may optionally +affect the @code{ci} request or other relevant requests if any. + +@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 +a file within the most recent directory sent with @code{Directory}; it +must not contain @samp{/}. 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 Is-modified @var{filename} \n +Response expected: no. Additional data: none. Like @code{Modified}, +but used if the server only needs +to know whether the file is modified, not the contents. + +The commands which can take @code{Is-modified} instead of +@code{Modified} with no known change in behavior are: @code{admin}, +@code{diff} (if and only if two @samp{-r} or @samp{-D} options are +specified), @code{watch-on}, @code{watch-off}, @code{watch-add}, +@code{watch-remove}, @code{watchers}, @code{editors}, +@code{log}, and @code{annotate}. + +For the @code{status} command, one can send @code{Is-modified} but if +the client is using imperfect mechanisms such as timestamps to determine +whether to consider a file modified, then the behavior will be +different. That is, if one sends @code{Modified}, then the server will +actually compare the contents of the file sent and the one it derives +from to determine whether the file is genuinely modified. But if one +sends @code{Is-modified}, then the server takes the client's word for +it. A similar situation exists for @code{tag}, if the @samp{-c} option +is specified. + +Commands for which @code{Modified} is necessary are @code{co}, +@code{ci}, @code{update}, and @code{import}. + +Commands which do not need to inform the server about a working +directory, and thus should not be sending either @code{Modified} or +@code{Is-modified}: @code{rdiff}, @code{rtag}, @code{history}, +and @code{release}. + +Commands for which further investigation is warranted are: +@code{remove}, @code{add}, and @code{export}. Pending such +investigation, the more conservative course of action is to stick to +@code{Modified}. + +@item Unchanged @var{filename} \n +Response expected: no. Tell the server that @var{filename} has not been +modified in the checked out directory. The @var{filename} is +a file within the most recent directory sent with @code{Directory}; it +must not contain @samp{/}. + +@item UseUnchanged \n +Response expected: no. To specify the version of the protocol described +in this document, servers must support this request (although it need +not do anything) and clients must issue it. +The @code{Root} request need not have been previously sent. + +@item Empty-conflicts \n +Response expected: yes. This request is an alias for @code{noop}. Its +presence in the list of @code{valid-requests} is intended to be used as a +placeholder to alert the client that the server does not require the contents +of files with conflicts that have not been modified since the merge, for +operations other than diff. It was a bug in pre 1.11.22 & pre 1.12.14 servers +that the contents of files with conflicts was required for the server to +acknowledge the existence of the conflicts. + +@item Notify @var{filename} \n +Response expected: no. +Tell the server that an @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. +The @var{filename} is a file within the most recent directory sent with +@code{Directory}; it must not contain @samp{/}. +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, @samp{U} for +unedit, undefined behavior if @samp{C}, and all other letters should be +silently ignored for future expansion. +@var{time} is the time at which the edit or unedit took place, in a +user-readable format of the client's choice (the server should treat the +time as an opaque string rather than interpreting it). +@c Might be useful to specify a format, but I don't know if we want to +@c specify the status quo (ISO C asctime() format plus timezone) without +@c offering the option of ISO8601 and/or RFC822/1123 (see cvs.texinfo +@c for much much more on date formats). +@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, zero or more of the following characters in the +following order: @samp{E} for edit, @samp{U} for unedit, @samp{C} for +commit, and all other letters should be silently ignored for future +expansion. If @var{notification-type} is @samp{E} the temporary watches +are set; if it is @samp{U} they are cleared. +If @var{watches} is followed by \t then the +\t and the rest of the line should be ignored, for future expansion. + +The @var{time}, @var{clienthost}, and @var{working-dir} fields may not +contain the characters @samp{+}, @samp{,}, @samp{>}, @samp{;}, or @samp{=}. + +Note that a client may be capable of performing an @code{edit} or +@code{unedit} operation without connecting to the server at that time, +and instead connecting to the server when it is convenient (for example, +when a laptop is on the net again) to send the @code{Notify} requests. +Even if a client is capable of deferring notifications, it should +attempt to send them immediately (one can send @code{Notify} requests +together with a @code{noop} request, for example), unless perhaps if +it can know that a connection would be impossible. + +@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. @var{filename} must not contain +@samp{/}; it needs to be a file in the directory named by the most +recent @code{Directory} request. +@c FIXME: the bit about not containing / is true of most of the +@c requests, but isn't documented and should be. + +@item Case \n +Response expected: no. Tell the server that filenames should be matched +in a case-insensitive fashion. Note that this is not the primary +mechanism for achieving case-insensitivity; for the most part the client +keeps track of the case which the server wants to use and takes care to +always use that case regardless of what the user specifies. 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. The latter mechanism is more general (it could also be +used for 8.3 filenames, VMS filenames with more than one @samp{.}, and +any other situation in which there is a predictable mapping between +filenames in the working directory and filenames in the protocol), but +there are some situations it cannot handle (ignore patterns, or +situations where the user specifies a filename and the client does not +know about that file). + +Though this request will be supported into the foreseeable future, it has been +the source of numerous bug reports in the past due to the complexity of testing +this functionality via the test suite and client developers are encouraged not +to use it. Instead, please consider munging conflicting names and maintaining +a map for communicating with the server. For example, suppose the server sends +files @file{case}, @file{CASE}, and @file{CaSe}. The client could write all +three files to names such as, @file{case}, @file{case_prefix_case}, and +@file{case_prefix_2_case} and maintain a mapping between the file names in, for +instance a new @file{CVS/Map} file. + +@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 +Response expected: no. +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. +The @code{Root} request need not have been previously sent. + +@item Gzip-stream @var{level} \n +Response expected: no. +Use zlib (RFC 1950/1951) compression to compress all further communication +between the client and the server. After this request is sent, all +further communication must be compressed. All further data received +from the server will also be compressed. The @var{level} argument +suggests to the server the level of compression that it should apply; it +should be an integer between 1 and 9, inclusive, where a higher number +indicates more compression. + +@item Kerberos-encrypt \n +Response expected: no. +Use Kerberos encryption to encrypt all further communication between the +client and the server. This will only work if the connection was made +over Kerberos in the first place. If both the @code{Gzip-stream} and +the @code{Kerberos-encrypt} requests are used, the +@code{Kerberos-encrypt} request should be used first. This will make +the client and server encrypt the compressed data, as opposed to +compressing the encrypted data. Encrypted data is generally +incompressible. + +Note that this request does not fully prevent an attacker from hijacking +the connection, in the sense that it does not prevent hijacking the +connection between the initial authentication and the +@code{Kerberos-encrypt} request. + +@item Gssapi-encrypt \n +Response expected: no. +Use GSSAPI encryption to encrypt all further communication between the +client and the server. This will only work if the connection was made +over GSSAPI in the first place. See @code{Kerberos-encrypt}, above, for +the relation between @code{Gssapi-encrypt} and @code{Gzip-stream}. + +Note that this request does not fully prevent an attacker from hijacking +the connection, in the sense that it does not prevent hijacking the +connection between the initial authentication and the +@code{Gssapi-encrypt} request. + +@item Gssapi-authenticate \n +Response expected: no. +Use GSSAPI authentication to authenticate all further communication +between the client and the server. This will only work if the +connection was made over GSSAPI in the first place. Encrypted data is +automatically authenticated, so using both @code{Gssapi-authenticate} +and @code{Gssapi-encrypt} has no effect beyond that of +@code{Gssapi-encrypt}. Unlike encrypted data, it is reasonable to +compress authenticated data. + +Note that this request does not fully prevent an attacker from hijacking +the connection, in the sense that it does not prevent hijacking the +connection between the initial authentication and the +@code{Gssapi-authenticate} request. + +@item Set @var{variable}=@var{value} \n +Response expected: no. +Set a user variable @var{variable} to @var{value}. +The @code{Root} request need not have been previously sent. + +@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. + +Expand may not be the best word for what this request does. It does not +necessarily tell you all the files contained in a module, for example. +Basically it is a way of telling you which working directories the +server needs to know about in order to handle a checkout of the +specified modules. + +For example, suppose that the server has a module defined by + +@example +aliasmodule -a 1dir +@end example + +That is, one can check out @code{aliasmodule} and it will take +@code{1dir} in the repository and check it out to @code{1dir} in the +working directory. Now suppose the client already has this module +checked out and is planning on using the @code{co} request to update it. +Without using @code{expand-modules}, the client would have two bad +choices: it could either send information about @emph{all} working +directories under the current directory, which could be unnecessarily +slow, or it could be ignorant of the fact that @code{aliasmodule} stands +for @code{1dir}, and neglect to send information for @code{1dir}, which +would lead to incorrect operation. +@c Those don't really seem like the only two options. I mean, what +@c about keeping track of the correspondence from when we first checked +@c out a fresh directory? Not that the CVS client does this, or that +@c I've really thought about whether it would be a good idea... + +With @code{expand-modules}, the client would first ask for the module to +be expanded: + +@example +C: Root /home/kingdon/zwork/cvsroot +. . . +C: Argument aliasmodule +C: Directory . +C: /home/kingdon/zwork/cvsroot +C: expand-modules +S: Module-expansion 1dir +S: ok +@end example + +and then it knows to check the @file{1dir} directory and send +requests such as @code{Entry} and @code{Modified} for the files in that +directory. + +@item ci \n +@itemx diff \n +@itemx tag \n +@itemx status \n +@itemx admin \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{Directory}, @code{Entry}, or +@code{Modified} requests, if they have been sent. The +last @code{Directory} 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. + +@item log \n +Response expected: yes. Show information for past revisions. This uses +any previous @code{Directory}, @code{Entry}, or @code{Modified} +requests, if they have been sent. The last @code{Directory} sent +specifies the working directory at the time of the operation. Also uses +previous @code{Argument}'s of which the canonical forms are the +following (@sc{cvs} 1.10 and older clients sent what the user specified, +but clients are encouraged to use the canonical forms and other forms +are deprecated): + +@table @code +@item -b, -h, -l, -N, -R, -t +These options go by themselves, one option per @code{Argument} request. + +@item -d @var{date1}<@var{date2} +Select revisions between @var{date1} and @var{date2}. Either date +may be omitted in which case there is no date limit at that end of the +range (clients may specify dates such as 1 Jan 1970 or 1 Jan 2038 for +similar purposes but this is problematic as it makes assumptions about +what dates the server supports). Dates are in RFC822/1123 format. The +@samp{-d} is one @code{Argument} request and the date range is a second +one. + +@item -d @var{date1}<=@var{date2} +Likewise but compare dates for equality. + +@item -d @var{singledate} +Select the single, latest revision dated @var{singledate} or earlier. + +To include several date ranges and/or singledates, repeat the @samp{-d} +option as many times as necessary. + +@item -r@var{rev1}:@var{rev2} +@itemx -r@var{branch} +@itemx -r@var{branch}. +@itemx -r +Specify revisions (note that @var{rev1} or @var{rev2} can be omitted, or +can refer to branches). Send both the @samp{-r} and the revision +information in a single @code{Argument} request. To include several +revision selections, repeat the @samp{-r} option. + +@item -s @var{state} +@itemx -w +@itemx -w@var{login} +Select on states or users. To include more than one state or user, +repeat the option. Send the @samp{-s} option as a separate argument +from the state being selected. Send the @samp{-w} option as part of the +same argument as the user being selected. +@end table + +@item co \n +Response expected: yes. Get files from the repository. This uses any +previous @code{Argument}, @code{Directory}, @code{Entry}, or +@code{Modified} requests, if they have been sent. Arguments to this +command are module names; the client cannot know what directories they +correspond to except by (1) just sending the @code{co} request, and then +seeing what directory names the server sends back in its responses, and +(2) the @code{expand-modules} request. + +@item export \n +Response expected: yes. Get files from the repository. This uses any +previous @code{Argument}, @code{Directory}, @code{Entry}, or +@code{Modified} requests, if they have been sent. Arguments to this +command are module names, as described for the @code{co} request. The +intention behind this command is that a client can get sources from a +server without storing CVS information about those sources. That is, a +client probably should not count on being able to take the entries line +returned in the @code{Created} response from an @code{export} request +and send it in a future @code{Entry} request. Note that the entries +line in the @code{Created} response must indicate whether the file is +binary or text, so the client can create it correctly. + +@item rannotate \n +@itemx rdiff \n +@itemx rlog \n +@itemx rtag \n +Response expected: yes. Actually do a cvs command. This uses any +previous @code{Argument} requests, if they have been sent. The client +should not send @code{Directory}, @code{Entry}, or @code{Modified} +requests for these commands; they are not used. Arguments to these +commands are module names, as described for @code{co}. + +@item update \n +Response expected: yes. Actually do a @code{cvs update} command. This +uses any previous @code{Argument}, @code{Directory}, @code{Entry}, +or @code{Modified} requests, if they have been sent. The +last @code{Directory} 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{Directory}, @code{Entry}, or +@code{Modified} requests, if they have been sent. The +last @code{Directory} sent specifies the working directory at the time +of the operation - unlike most commands, the repository field of each +@code{Directory} request is ignored (it merely must point somewhere +within the root). 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 add \n +Response expected: yes. Add a file or directory. This uses any +previous @code{Argument}, @code{Directory}, @code{Entry}, or +@code{Modified} requests, if they have been sent. The +last @code{Directory} sent specifies the working directory at the time +of the operation. + +To add a directory, send the directory to be added using +@code{Directory} and @code{Argument} requests. For example: + +@example +C: Root /u/cvsroot +. . . +C: Argument nsdir +C: Directory nsdir +C: /u/cvsroot/1dir/nsdir +C: Directory . +C: /u/cvsroot/1dir +C: add +S: M Directory /u/cvsroot/1dir/nsdir added to the repository +S: ok +@end example + +You will notice that the server does not signal to the client in any +particular way that the directory has been successfully added. The +client is supposed to just assume that the directory has been added and +update its records accordingly. Note also that adding a directory is +immediate; it does not wait until a @code{ci} request as files do. + +To add a file, send the file to be added using a @code{Modified} +request. For example: + +@example +C: Argument nfile +C: Directory . +C: /u/cvsroot/1dir +C: Modified nfile +C: u=rw,g=r,o=r +C: 6 +C: hello +C: add +S: E cvs server: scheduling file `nfile' for addition +S: Mode u=rw,g=r,o=r +S: Checked-in ./ +S: /u/cvsroot/1dir/nfile +S: /nfile/0/// +S: E cvs server: use 'cvs commit' to add this file permanently +S: ok +@end example + +Note that the file has not been added to the repository; the only effect +of a successful @code{add} request, for a file, is to supply the client +with a new entries line containing @samp{0} to indicate an added file. +In fact, the client probably could perform this operation without +contacting the server, although using @code{add} does cause the server +to perform a few more checks. + +The client sends a subsequent @code{ci} to actually add the file to the +repository. + +Another quirk of the @code{add} request is that with CVS 1.9 and older, +a pathname specified in +an @code{Argument} request cannot contain @samp{/}. There is no good +reason for this restriction, and in fact more recent CVS servers don't +have it. +But the way to interoperate with the older servers is to ensure that +all @code{Directory} requests for @code{add} (except those used to add +directories, as described above), use @samp{.} for +@var{local-directory}. Specifying another string for +@var{local-directory} may not get an error, but it will get you strange +@code{Checked-in} responses from the buggy servers. + +@item remove \n +Response expected: yes. Remove a file. This uses any +previous @code{Argument}, @code{Directory}, @code{Entry}, or +@code{Modified} requests, if they have been sent. The +last @code{Directory} sent specifies the working directory at the time +of the operation. + +Note that this request does not actually do anything to the repository; +the only effect of a successful @code{remove} request is to supply the +client with a new entries line containing @samp{-} to indicate a removed +file. In fact, the client probably could perform this operation without +contacting the server, although using @code{remove} may cause the server +to perform a few more checks. + +The client sends a subsequent @code{ci} request to actually record the +removal in the repository. + +@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{Directory}, @code{Entry}, or @code{Modified} +requests, if they have been sent. The last @code{Directory} 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. +The @code{Root} request need not have been previously sent. + +@item update-patches \n +Response expected: yes. +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 +Response expected: no. Note that this request does not follow the +response convention stated above. @code{Gzip-stream} is suggested +instead of @code{gzip-file-contents} as it gives better compression; the +only reason to implement the latter is to provide compression with +@sc{cvs} 1.8 and earlier. The @code{gzip-file-contents} request asks +the server to compress files it sends to the client using @code{gzip} +(RFC1952/1951) compression, using the specified level of compression. +If this request is not made, the server must not compress files. + +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 wrapper-sendme-rcsOptions \n +Response expected: yes. +Request that the server transmit mappings from filenames to keyword +expansion modes in @code{Wrapper-rcsOption} responses. + +@item version \n +Response expected: yes. +Request that the server transmit its version message. +The @code{Root} request need not have been previously sent. + +@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 request which doesn't expect a response produced an error. +@end table + +When the client is done, it drops the connection. + +@node Response intro +@section Introduction to Responses + +After a command which expects a response, the server sends however many +of the following responses are appropriate. The server should not send +data at other times (the current implementation may violate this +principle in a few minor places, where the server is printing an error +message and exiting---this should be investigated further). + +Any set of responses always ends with @samp{error} or @samp{ok}. This +indicates that the response is over. + +@c "file updating response" and "file update modifying response" are +@c lame terms (mostly because they are so awkward). Any better ideas? +The responses @code{Checked-in}, @code{New-entry}, @code{Updated}, +@code{Created}, @code{Update-existing}, @code{Merged}, and +@code{Patched} are referred to as @dfn{file updating} responses, because +they change the status of a file in the working directory in some way. +The responses @code{Mode}, @code{Mod-time}, and @code{Checksum} are +referred to as @dfn{file update modifying} responses because they modify +the next file updating response. In no case shall a file update +modifying response apply to a file updating response other than the next +one. Nor can the same file update modifying response occur twice for +a given file updating response (if servers diagnose this problem, it may +aid in detecting the case where clients send an update modifying +response without following it by a file updating response). + +@node Response pathnames +@section The "pathname" in responses + +Many of the responses contain something called @var{pathname}. +@c FIXME: should better document when the specified repository needs to +@c end in "/.". +The name is somewhat misleading; it actually indicates a pair of +pathnames. First, 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 linefeed and a repository +name. Then +a slash and the filename (without a @samp{,v} ending). +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 + +If the server wants to tell the client to create a directory, then it +merely uses the directory in any response, as described above, and the +client should create the directory if it does not exist. Note that this +should only be done one directory at a time, in order to permit the +client to correctly store the repository for each directory. Servers +can use requests such as @code{Clear-sticky}, +@code{Clear-static-directory}, or any other requests, to create +directories. +@c FIXME: Need example here of how "repository" needs to be sent for +@c each directory, and cannot be correctly deduced from, say, the most +@c deeply nested directory. + +Some server +implementations may poorly distinguish between a directory which should +not exist and a directory which contains no files; in order to refrain +from creating empty directories a client should both send the @samp{-P} +option to @code{update} or @code{co}, and should also detect the case in +which the server asks to create a directory but not any files within it +(in that case the client should remove the directory or refrain from +creating it in the first place). Note that servers could clean this up +greatly by only telling the client to create directories if the +directory in question should exist, but until servers do this, clients +will need to offer the @samp{-P} behavior described above. + +@node Responses +@section Responses + +Here are the responses: + +@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.). The 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. This response is not used if @code{Created} and +@code{Update-existing} are supported. + +@item Created @var{pathname} \n +This is just like @code{Updated} and takes the same additional data, but +is used only if no @code{Entry}, @code{Modified}, or +@code{Unchanged} request has been sent for the file in question. The +distinction between @code{Created} and @code{Update-existing} is so +that the client can give an error message in several cases: (1) there is +a file in the working directory, but not one for which @code{Entry}, +@code{Modified}, or @code{Unchanged} was sent (for example, a file which +was ignored, or a file for which @code{Questionable} was sent), (2) +there is a file in the working directory whose name differs from the one +mentioned in @code{Created} in ways that the client is unable to use to +distinguish files. For example, the client is case-insensitive and the +names differ only in case. + +@item Update-existing @var{pathname} \n +This is just like @code{Updated} and takes the same additional data, but +is used only if a @code{Entry}, @code{Modified}, or @code{Unchanged} +request has been sent for the file in question. + +This response, or @code{Merged}, indicates that the server has +determined that it is OK to overwrite the previous contents of the file +specified by @var{pathname}. Provided that the client has correctly +sent @code{Modified} or @code{Is-modified} requests for a modified file, +and the file was not modified while CVS was running, the server can +ensure that a user's modifications are not lost. + +@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. + +It is useful to preserve an copy of what the file looked like before the +merge. This is basically handled by the server; before sending +@code{Merged} it will send a @code{Copy-file} response. For example, if +the file is @file{aa} and it derives from revision 1.3, the +@code{Copy-file} response will tell the client to copy @file{aa} to +@file{.#aa.1.3}. It is up to the client to decide how long to keep this +file around; traditionally clients have left it around forever, thus +letting the user clean it up as desired. But another answer, such as +until the next commit, might be preferable. + +@item Rcs-diff @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 an RCS change text. This change text is produced by +@samp{diff -n} (the GNU diff @samp{-a} option may also be used). The +client must apply this change text 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 Patched @var{pathname} \n +This is just like @code{Rcs-diff} and takes the same additional data, +except that it sends a standard patch rather than an RCS change text. +The patch is produced by @samp{diff -c} for @sc{cvs} 1.6 and later (see +POSIX.2 for a description of this format), or @samp{diff -u} for +previous versions of @sc{cvs}; clients are encouraged to accept either +format. Like @code{Rcs-diff}, this response is only used if the +@code{update} command is given the @samp{-u} argument. + +The @code{Patched} response is deprecated in favor of the +@code{Rcs-diff} response. However, older clients (CVS 1.9 and earlier) +only support @code{Patched}. + +@item Mode @var{mode} \n +This @var{mode} applies to the next file mentioned in +@code{Checked-in}. @code{Mode} is a file update modifying response +as described in @ref{Response intro}. + +@item Mod-time @var{time} \n +Set the modification time of the next file sent to @var{time}. +@code{Mod-time} is a file update modifying response +as described in @ref{Response intro}. +The +@var{time} is in the format specified by RFC822 as modified by RFC1123. +The server may specify any timezone it chooses; clients will want to +convert that to their own timezone as appropriate. An example of this +format is: + +@example +26 May 1997 13:01:40 -0400 +@end example + +There is no requirement that the client and server clocks be +synchronized. The server just sends its recommendation for a timestamp +(based on its own clock, presumably), and the client should just believe +it (this means that the time might be in the future, for example). + +If the server does not send @code{Mod-time} for a given file, the client +should pick a modification time in the usual way (usually, just let the +operating system set the modification time to the time that the CVS +command is running). + +@item Checksum @var{checksum}\n +The @var{checksum} applies to the next file sent (that is, +@code{Checksum} is a file update modifying response +as described in @ref{Response intro}). +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 (MD5 is described in RFC1321). +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}. + +This can optionally be implemented as a rename instead of a copy. The +only use for it which currently has been identified is prior to a +@code{Merged} response as described under @code{Merged}. Clients can +probably assume that is how it is being used, if they want to worry +about things like how long to keep the @var{newname} file around. + +@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 client should +store @var{tagspec} and pass it back to the server as-is, to allow for +future expansion. The first character of @var{tagspec} is @samp{T} for +a tag, @samp{D} for a date, or something else for future expansion. 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 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 Wrapper-rcsOption @var{pattern} -k '@var{option}' \n +Transmit to the client a filename pattern which implies a certain +keyword expansion mode. The @var{pattern} is a wildcard pattern (for +example, @samp{*.exe}. The @var{option} is @samp{b} for binary, and so +on. Note that although the syntax happens to resemble the syntax in +certain CVS configuration files, it is more constrained; there must be +exactly one space between @var{pattern} and @samp{-k} and exactly one +space between @samp{-k} and @samp{'}, and no string is permitted in +place of @samp{-k} (extensions should be done with new responses, not by +extending this one, for graceful handling of @code{Valid-responses}). + +@item M @var{text} \n +A one-line message for the user. +Note that the format of @var{text} is not designed for machine parsing. +Although sometimes scripts and clients will have little choice, the +exact text which is output is subject to vary at the discretion of the +server and the example output given in this document is just that, +example output. Servers are encouraged to use the @samp{MT} response, +and future versions of this document will hopefully standardize more of +the @samp{MT} tags; see @ref{Text tags}. + +@item Mbinary \n +Additional data: file transmission (note: compressed file transmissions +are not supported). This is like @samp{M}, except the contents of the +file transmission are binary and should be copied to standard output +without translation to local text file conventions. To transmit a text +file to standard output, servers should use a series of @samp{M} requests. + +@item E @var{text} \n +Same as @code{M} but send to stderr not stdout. + +@item F \n +@c FIXME: The second sentence, defining "flush", is somewhat off the top +@c of my head. Is there some text we can steal from ANSI C or someplace +@c which is more carefully thought out? +Flush stderr. That is, make it possible for the user to see what has +been written to stderr (it is up to the implementation to decide exactly +how far it should go to ensure this). + +@item MT @var{tagname} @var{data} \n + +This response provides for tagged text. It is similar to +SGML/HTML/XML in that the data is structured and a naive application +can also make some sense of it without understanding the structure. +The syntax is not SGML-like, however, in order to fit into the CVS +protocol better and (more importantly) to make it easier to parse, +especially in a language like perl or awk. + +The @var{tagname} can have several forms. If it starts with @samp{a} +to @samp{z} or @samp{A} to @samp{Z}, then it represents tagged text. +If the implementation recognizes @var{tagname}, then it may interpret +@var{data} in some particular fashion. If the implementation does not +recognize @var{tagname}, then it should simply treat @var{data} as +text to be sent to the user (similar to an @samp{M} response). There +are two tags which are general purpose. The @samp{text} tag is +similar to an unrecognized tag in that it provides text which will +ordinarily be sent to the user. The @samp{newline} tag is used +without @var{data} and indicates that a newline will ordinarily be +sent to the user (there is no provision for embedding newlines in the +@var{data} of other tagged text responses). + +If @var{tagname} starts with @samp{+} it indicates a start tag and if +it starts with @samp{-} it indicates an end tag. The remainder of +@var{tagname} should be the same for matching start and end tags, and +tags should be nested (for example one could have tags in the +following order @code{+bold} @code{+italic} @code{text} @code{-italic} +@code{-bold} but not @code{+bold} @code{+italic} @code{text} +@code{-bold} @code{-italic}). A particular start and end tag may be +documented to constrain the tagged text responses which are valid +between them. + +Note that if @var{data} is present there will always be exactly one +space between @var{tagname} and @var{data}; if there is more than one +space, then the spaces beyond the first are part of @var{data}. + +Here is an example of some tagged text responses. Note that there is +a trailing space after @samp{Checking in} and @samp{initial revision:} +and there are two trailing spaces after @samp{<--}. Such trailing +spaces are, of course, part of @var{data}. + +@example +MT +checking-in +MT text Checking in +MT fname gz.tst +MT text ; +MT newline +MT rcsfile /home/kingdon/zwork/cvsroot/foo/gz.tst,v +MT text <-- +MT fname gz.tst +MT newline +MT text initial revision: +MT init-rev 1.1 +MT newline +MT text done +MT newline +MT -checking-in +@end example + +If the client does not support the @samp{MT} response, the same +responses might be sent as: + +@example +M Checking in gz.tst; +M /home/kingdon/zwork/cvsroot/foo/gz.tst,v <-- gz.tst +M initial revision: 1.1 +M done +@end example + +For a list of specific tags, see @ref{Text tags}. + +@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. +The @var{text} is like the @code{M} response, in the sense that it is +not particularly intended to be machine-parsed; servers may wish to +print an error message with @code{MT} responses, and then issue a +@code{error} response without @var{text} (although it should be noted +that @code{MT} currently has no way of flagging the output as intended +for standard error, the way that the @code{E} response does). + +@item ok \n +The command completed successfully. +@end table + +@node Text tags +@section Tags for the MT tagged text response + +The @code{MT} response, as described in @ref{Responses}, offers a +way for the server to send tagged text to the client. This section +describes specific tags. The intention is to update this section as +servers add new tags. + +In the following descriptions, @code{text} and @code{newline} tags are +omitted. Such tags contain information which is intended for users (or +to be discarded), and are subject to change at the whim of the server. +To avoid being vulnerable to such whim, clients should look for the tags +listed here, not @code{text}, @code{newline}, or other tags. + +The following tag means to indicate to the user that a file has been +updated. It is more or less redundant with the @code{Created} and +@code{Update-existing} responses, but we don't try to specify here +whether it occurs in exactly the same circumstances as @code{Created} +and @code{Update-existing}. The @var{name} is the pathname of the file +being updated relative to the directory in which the command is +occurring (that is, the last @code{Directory} request which is sent +before the command). + +@example +MT +updated +MT fname @var{name} +MT -updated +@end example + +The @code{importmergecmd} tag is used when doing an import which has +conflicts. The client can use it to report how to merge in the newly +imported changes. The @var{count} is the number of conflicts. The +newly imported changes can be merged by running the following command: +@smallexample +cvs checkout -j @var{tag1} -j @var{tag2} @var{repository} +@end smallexample + +@example +MT +importmergecmd +MT conflicts @var{count} +MT mergetag1 @var{tag1} +MT mergetag2 @var{tag2} +MT repository @var{repository} +MT -importmergecmd +@end example + +@node Example +@section Example + +@c The C:/S: convention is in imitation of RFC1869 (and presumably +@c other RFC's). In other formatting concerns, we might want to think +@c about whether there is an easy way to provide RFC1543 formatting +@c (without negating the advantages of texinfo), and whether we should +@c use RFC2234 BNF (I fear that would be less clear than +@c what we do now, however). Plus what about RFC2119 terminology (MUST, +@c SHOULD, &c) or ISO terminology (shall, should, or whatever they are)? +Here is an example; lines are prefixed by @samp{C: } to indicate the +client sends them or @samp{S: } to indicate the server sends them. + +The client starts by connecting, sending the root, and completing the +protocol negotiation. In actual practice the lists of valid responses +and requests would be longer. +@c The reason that we artificially shorten the lists is to avoid phony +@c line breaks. Any better solutions? +@c Other than that, this exchange is taken verbatim from the data +@c exchanged by CVS (as of Nov 1996). That is why some of the requests and +@c responses are not quite what you would pick for pedagogical purposes. + +@example +C: Root /u/cvsroot +C: Valid-responses ok error Checked-in M E +C: valid-requests +S: Valid-requests Root Directory Entry Modified Argument Argumentx ci co +S: ok +C: UseUnchanged +@end example + +The client wants to check out the @code{supermunger} module into a fresh +working directory. Therefore it first expands the @code{supermunger} +module; this step would be omitted if the client was operating on a +directory rather than a module. +@c Why does it send Directory here? The description of expand-modules +@c doesn't really say much of anything about what use, if any, it makes of +@c Directory and similar requests sent previously. + +@example +C: Argument supermunger +C: Directory . +C: /u/cvsroot +C: expand-modules +@end example + +The server replies that the @code{supermunger} module expands to the +directory @code{supermunger} (the simplest case): + +@example +S: Module-expansion supermunger +S: ok +@end example + +The client then proceeds to check out the directory. The fact that it +sends only a single @code{Directory} request which specifies @samp{.} +for the working directory means that there is not already a +@code{supermunger} directory on the client. +@c What is -N doing here? + +@example +C: Argument -N +C: Argument supermunger +C: Directory . +C: /u/cvsroot +C: co +@end example + +The server replies with the requested files. In this example, there is +only one file, @file{mungeall.c}. The @code{Clear-sticky} and +@code{Clear-static-directory} requests are sent by the current +implementation but they have no effect because the default is for those +settings to be clear when a directory is newly created. + +@example +S: Clear-sticky supermunger/ +S: /u/cvsroot/supermunger/ +S: Clear-static-directory supermunger/ +S: /u/cvsroot/supermunger/ +S: E cvs server: Updating supermunger +S: M U supermunger/mungeall.c +S: Created supermunger/ +S: /u/cvsroot/supermunger/mungeall.c +S: /mungeall.c/1.1/// +S: u=rw,g=r,o=r +S: 26 +S: int mein () @{ abort (); @} +S: ok +@end example + +The current client implementation would break the connection here and make a +new connection for the next command. However, the protocol allows it +to keep the connection open and continue, which is what we show here. + +After the user modifies the file and instructs the client to check it +back in. The client sends arguments to specify the log message and file +to check in: + +@example +C: Argument -m +C: Argument Well, you see, it took me hours and hours to find +C: Argumentx this typo and I searched and searched and eventually +C: Argumentx had to ask John for help. +C: Argument mungeall.c +@end example + +It also sends information about the contents of the working directory, +including the new contents of the modified file. Note that the user has +changed into the @file{supermunger} directory before executing this +command; the top level directory is a user-visible concept because the +server should print filenames in @code{M} and @code{E} responses +relative to that directory. +@c We are waving our hands about the order of the requests. "Directory" +@c and "Argument" can be in any order, but this probably isn't specified +@c very well. + +@example +C: Directory . +C: /u/cvsroot/supermunger +C: Entry /mungeall.c/1.1/// +C: Modified mungeall.c +C: u=rw,g=r,o=r +C: 26 +C: int main () @{ abort (); @} +@end example + +And finally, the client issues the checkin command (which makes use of +the data just sent): + +@example +C: ci +@end example + +And the server tells the client that the checkin succeeded: + +@example +S: M Checking in mungeall.c; +S: E /u/cvsroot/supermunger/mungeall.c,v <-- mungeall.c +S: E new revision: 1.2; previous revision: 1.1 +S: E done +S: Mode u=rw,g=r,o=r +S: Checked-in ./ +S: /u/cvsroot/supermunger/mungeall.c +S: /mungeall.c/1.2/// +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 +(except obsolete, pre-1.5, versions of CVS) 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: +@code{Root}, @code{Valid-responses}, @code{valid-requests}, +@code{Directory}, @code{Entry}, @code{Modified}, @code{Unchanged}, +@code{Argument}, @code{Argumentx}, @code{ci}, @code{co}, @code{update}. +Responses: @code{ok}, @code{error}, @code{Valid-requests}, +@code{Checked-in}, @code{Updated}, @code{Merged}, @code{Removed}, +@code{M}, @code{E}. + +A server need not implement @code{Repository}, but in order to interoperate +with CVS 1.5 through 1.9 it must claim to implement it (in +@code{Valid-requests}). The client will not actually send the request. + +@node Obsolete +@section Obsolete protocol elements + +This section briefly describes protocol elements which are obsolete. +There is no attempt to document them in full detail. + +There was a @code{Repository} request which was like @code{Directory} +except it only provided @var{repository}, and the local directory was +assumed to be similarly named. + +If the @code{UseUnchanged} request was not sent, there was a @code{Lost} +request which was sent to indicate that a file did not exist in the +working directory, and the meaning of sending @code{Entries} without +@code{Lost} or @code{Modified} was different. All current clients (CVS +1.5 and later) will send @code{UseUnchanged} if it is supported. + +@node Protocol Notes +@chapter Notes on the Protocol + +A number of enhancements are possible. Also see the file @sc{todo} in +the @sc{cvs} source distribution, which has further ideas concerning +various aspects of @sc{cvs}, some of which impact the protocol. +Similarly, the @code{http://cvs.nongnu.org} site, in particular the +@cite{Development} pages. + +@itemize @bullet +@item +The @code{Modified} request could be sped 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; probably requiring the use +of "cvs edit" in this case is the most sensible course (the "cvs edit" +could be handled by a package like VC for emacs). This would also allow +local operation of @code{cvs diff} without arguments. + +@item +The fact that @code{pserver} requires an extra network turnaround in +order to perform authentication would be nice to avoid. This relates to +the issue of reporting errors; probably the clean solution is to defer +the error until the client has issued a request which expects a +response. To some extent this might relate to the next item (in terms +of how easy it is to skip a whole bunch of requests until we get to one +that expects a response). I know that the kerberos code doesn't wait in +this fashion, but that probably can cause network deadlocks and perhaps +future problems running over a transport which is more transaction +oriented than TCP. On the other hand I'm not sure it is wise to make +the client conduct a lengthy upload only to find there is an +authentication failure. + +@item +The protocol uses an extra network turnaround for protocol negotiation +(@code{valid-requests}). It might be nice to avoid this by having the +client be able to send requests and tell the server to ignore them if +they are unrecognized (different requests could produce a fatal error if +unrecognized). To do this there should be a standard syntax for +requests. For example, perhaps all future requests should be a single +line, with mechanisms analogous to @code{Argumentx}, or several requests +working together, to provide greater amounts of information. Or there +might be a standard mechanism for counted data (analogous to that used +by @code{Modified}) or continuation lines (like a generalized +@code{Argumentx}). It would be useful to compare what HTTP is planning +in this area; last I looked they were contemplating something called +Protocol Extension Protocol but I haven't looked at the relevant IETF +documents in any detail. Obviously, we want something as simple as +possible (but no simpler). + +@item +The scrambling algorithm in the CVS client and server actually support +more characters than those documented in @ref{Password scrambling}. +Someday we are going to either have to document them all (but this is +not as easy as it may look, see below), or (gradually and with adequate +process) phase out the support for other characters in the CVS +implementation. This business of having the feature partly undocumented +isn't a desirable state long-term. + +The problem with documenting other characters is that unless we know +what character set is in use, there is no way to make a password +portable from one system to another. For example, a with a circle on +top might have different encodings in different character sets. + +It @emph{almost} works to say that the client picks an arbitrary, +unknown character set (indeed, having the CVS client know what character +set the user has in mind is a hard problem otherwise), and scrambles +according to a certain octet<->octet mapping. There are two problems +with this. One is that the protocol has no way to transmit character 10 +decimal (linefeed), and the current server and clients have no way to +handle 0 decimal (NUL). This may cause problems with certain multibyte +character sets, in which octets 10 and 0 will appear in the middle of +other characters. The other problem, which is more minor and possibly +not worth worrying about, is that someone can type a password on one +system and then go to another system which uses a different encoding for +the same characters, and have their password not work. + +The restriction to the ISO646 invariant subset is the best approach for +strings which are not particularly significant to users. Passwords are +visible enough that this is somewhat doubtful as applied here. ISO646 +does, however, have the virtue (!?) of offending everyone. It is easy +to say "But the $ is right on people's keyboards! Surely we can't +forbid that". From a human factors point of view, that makes quite a +bit of sense. The contrary argument, of course, is that a with a circle +on top, or some of the characters poorly handled by Unicode, are on +@emph{someone}'s keyboard. + +@end itemize + +@bye diff --git a/contrib/cvs/doc/mdate-sh b/contrib/cvs/doc/mdate-sh new file mode 100755 index 0000000..cd916c0 --- /dev/null +++ b/contrib/cvs/doc/mdate-sh @@ -0,0 +1,201 @@ +#!/bin/sh +# Get modification time of a file or directory and pretty-print it. + +scriptversion=2005-06-29.22 + +# Copyright (C) 1995, 1996, 1997, 2003, 2004, 2005 Free Software +# Foundation, Inc. +# written by Ulrich Drepper <drepper@gnu.ai.mit.edu>, June 1995 +# +# 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +# As a special exception to the GNU General Public License, if you +# distribute this file as part of a program that contains a +# configuration script generated by Autoconf, you may include it under +# the same distribution terms that you use for the rest of that program. + +# This file is maintained in Automake, please report +# bugs to <bug-automake@gnu.org> or send patches to +# <automake-patches@gnu.org>. + +case $1 in + '') + echo "$0: No file. Try \`$0 --help' for more information." 1>&2 + exit 1; + ;; + -h | --h*) + cat <<\EOF +Usage: mdate-sh [--help] [--version] FILE + +Pretty-print the modification time of FILE. + +Report bugs to <bug-automake@gnu.org>. +EOF + exit $? + ;; + -v | --v*) + echo "mdate-sh $scriptversion" + exit $? + ;; +esac + +# Prevent date giving response in another language. +LANG=C +export LANG +LC_ALL=C +export LC_ALL +LC_TIME=C +export LC_TIME + +# GNU ls changes its time format in response to the TIME_STYLE +# variable. Since we cannot assume `unset' works, revert this +# variable to its documented default. +if test "${TIME_STYLE+set}" = set; then + TIME_STYLE=posix-long-iso + export TIME_STYLE +fi + +save_arg1=$1 + +# Find out how to get the extended ls output of a file or directory. +if ls -L /dev/null 1>/dev/null 2>&1; then + ls_command='ls -L -l -d' +else + ls_command='ls -l -d' +fi + +# A `ls -l' line looks as follows on OS/2. +# drwxrwx--- 0 Aug 11 2001 foo +# This differs from Unix, which adds ownership information. +# drwxrwx--- 2 root root 4096 Aug 11 2001 foo +# +# To find the date, we split the line on spaces and iterate on words +# until we find a month. This cannot work with files whose owner is a +# user named `Jan', or `Feb', etc. However, it's unlikely that `/' +# will be owned by a user whose name is a month. So we first look at +# the extended ls output of the root directory to decide how many +# words should be skipped to get the date. + +# On HPUX /bin/sh, "set" interprets "-rw-r--r--" as options, so the "x" below. +set x`ls -l -d /` + +# Find which argument is the month. +month= +command= +until test $month +do + shift + # Add another shift to the command. + command="$command shift;" + case $1 in + Jan) month=January; nummonth=1;; + Feb) month=February; nummonth=2;; + Mar) month=March; nummonth=3;; + Apr) month=April; nummonth=4;; + May) month=May; nummonth=5;; + Jun) month=June; nummonth=6;; + Jul) month=July; nummonth=7;; + Aug) month=August; nummonth=8;; + Sep) month=September; nummonth=9;; + Oct) month=October; nummonth=10;; + Nov) month=November; nummonth=11;; + Dec) month=December; nummonth=12;; + esac +done + +# Get the extended ls output of the file or directory. +set dummy x`eval "$ls_command \"\$save_arg1\""` + +# Remove all preceding arguments +eval $command + +# Because of the dummy argument above, month is in $2. +# +# On a POSIX system, we should have +# +# $# = 5 +# $1 = file size +# $2 = month +# $3 = day +# $4 = year or time +# $5 = filename +# +# On Darwin 7.7.0 and 7.6.0, we have +# +# $# = 4 +# $1 = day +# $2 = month +# $3 = year or time +# $4 = filename + +# Get the month. +case $2 in + Jan) month=January; nummonth=1;; + Feb) month=February; nummonth=2;; + Mar) month=March; nummonth=3;; + Apr) month=April; nummonth=4;; + May) month=May; nummonth=5;; + Jun) month=June; nummonth=6;; + Jul) month=July; nummonth=7;; + Aug) month=August; nummonth=8;; + Sep) month=September; nummonth=9;; + Oct) month=October; nummonth=10;; + Nov) month=November; nummonth=11;; + Dec) month=December; nummonth=12;; +esac + +case $3 in + ???*) day=$1;; + *) day=$3; shift;; +esac + +# Here we have to deal with the problem that the ls output gives either +# the time of day or the year. +case $3 in + *:*) set `date`; eval year=\$$# + case $2 in + Jan) nummonthtod=1;; + Feb) nummonthtod=2;; + Mar) nummonthtod=3;; + Apr) nummonthtod=4;; + May) nummonthtod=5;; + Jun) nummonthtod=6;; + Jul) nummonthtod=7;; + Aug) nummonthtod=8;; + Sep) nummonthtod=9;; + Oct) nummonthtod=10;; + Nov) nummonthtod=11;; + Dec) nummonthtod=12;; + esac + # For the first six month of the year the time notation can also + # be used for files modified in the last year. + if (expr $nummonth \> $nummonthtod) > /dev/null; + then + year=`expr $year - 1` + fi;; + *) year=$3;; +esac + +# The result. +echo $day $month $year + +# Local Variables: +# mode: shell-script +# sh-indentation: 2 +# eval: (add-hook 'write-file-hooks 'time-stamp) +# time-stamp-start: "scriptversion=" +# time-stamp-format: "%:y-%02m-%02d.%02H" +# time-stamp-end: "$" +# End: diff --git a/contrib/cvs/doc/mkman.pl b/contrib/cvs/doc/mkman.pl new file mode 100644 index 0000000..de0d298 --- /dev/null +++ b/contrib/cvs/doc/mkman.pl @@ -0,0 +1,372 @@ +#! @PERL@ +# +# Generate a man page from sections of a Texinfo manual. +# +# Copyright 2004, 2006 +# The Free Software Foundation, +# Derek R. Price, +# & Ximbiot <http://ximbiot.com> +# +# 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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + + + +# Need Perl 5.005 or greater for re 'eval'. +require 5.005; + +# The usual. +use strict; +use IO::File; + + + +### +### GLOBALS +### +my $texi_num = 0; # Keep track of how many texinfo files have been encountered. +my @parent; # This needs to be global to be used inside of a regex later. +my $nk; # Ditto. +my $ret; # The RE match Type, used in debug prints. +my $debug = 0; # Debug mode? + + + +### +### FUNCTIONS +### +sub debug_print +{ + print @_ if $debug; +} + + + +sub keyword_mode +{ + my ($keyword, $file) = @_; + + return "\\fR" + if $keyword =~ /^(|r|t)$/; + return "\\fB" + if $keyword =~ /^(strong|sc|code|file|samp)$/; + return "\\fI" + if $keyword =~ /^(emph|var|dfn)$/; + die "no handler for keyword \`$keyword', found at line $. of file \`$file'\n"; +} + + + +# Return replacement for \@$keyword{$content}. +sub do_keyword +{ + my ($file, $parent, $keyword, $content) = @_; + + return "`$content\\(aq in the CVS manual" + if $keyword eq "ref"; + return "see node `$content\\(aq in the CVS manual" + if $keyword =~ /^p?xref$/; + return "\\fP\\fP$content" + if $keyword =~ /^splitrcskeyword$/; + + my $endmode = keyword_mode $parent; + my $startmode = keyword_mode $keyword, $file; + + return "$startmode$content$endmode"; +} + + + +### +### MAIN +### +for my $file (@ARGV) +{ + my $fh = new IO::File "< $file" + or die "Failed to open file \`$file': $!"; + + if ($file !~ /\.(texinfo|texi|txi)$/) + { + print stderr "Passing \`$file' through unprocessed.\n"; + # Just cat any file that doesn't look like a Texinfo source. + while (my $line = $fh->getline) + { + print $line; + } + next; + } + + print stderr "Processing \`$file'.\n"; + $texi_num++; + my $gotone = 0; + my $inblank = 0; + my $indent = 0; + my $inexample = 0; + my $inmenu = 0; + my $intable = 0; + my $last_header = ""; + my @table_headers; + my @table_footers; + my $table_header = ""; + my $table_footer = ""; + my $last; + while ($_ = $fh->getline) + { + if (!$gotone && /^\@c ----- START MAN $texi_num -----$/) + { + $gotone = 1; + next; + } + + # Skip ahead until our man section. + next unless $gotone; + + # If we find the end tag we are done. + last if /^\@c ----- END MAN $texi_num -----$/; + + # Need to do this everywhere. i.e., before we print example + # lines, since literal back slashes can appear there too. + s/\\/\\\\/g; + s/^\./\\&./; + s/([\s])\./$1\\&./; + s/'/\\(aq/g; + s/`/\\`/g; + s/(?<!-)---(?!-)/\\(em/g; + s/\@bullet({}|\b)/\\(bu/g; + s/\@dots({}|\b)/\\&.../g; + + # Examples should be indented and otherwise untouched + if (/^\@example$/) + { + $indent += 2; + print qq{.SP\n.PD 0\n}; + $inexample = 1; + next; + } + if ($inexample) + { + if (/^\@end example$/) + { + $indent -= 2; + print qq{\n.PD\n.IP "" $indent\n}; + $inexample = 0; + next; + } + if (/^[ ]*$/) + { + print ".SP\n"; + next; + } + + # Preserve the newline. + $_ = qq{.IP "" $indent\n} . $_; + } + + # Compress blank lines into a single line. This and its + # corresponding skip purposely bracket the @menu and comment + # removal so that blanks on either side of a menu are + # compressed after the menu is removed. + if (/^[ ]*$/) + { + $inblank = 1; + next; + } + + # Not used + if (/^\@(ignore|menu)$/) + { + $inmenu++; + next; + } + # Delete menu contents. + if ($inmenu) + { + next unless /^\@end (ignore|menu)$/; + $inmenu--; + next; + } + + # Remove comments + next if /^\@c(omment)?\b/; + + # Ignore includes. + next if /^\@include\b/; + + # It's okay to ignore this keyword - we're not using any + # first-line indent commands at all. + next if s/^\@noindent\s*$//; + + # @need is only significant in printed manuals. + next if s/^\@need\s+.*$//; + + # If we didn't hit the previous check and $inblank is set, then + # we just finished with some number of blanks. Print the man + # page blank symbol before continuing processing of this line. + if ($inblank) + { + print ".SP\n"; + $inblank = 0; + } + + # Chapter headers. + $last_header = $1 if s/^\@node\s+(.*)$/.SH "$1"/; + if (/^\@appendix\w*\s+(.*)$/) + { + my $content = $1; + $content =~ s/^$last_header(\\\(em|\s+)?//; + next if $content =~ /^\s*$/; + s/^\@appendix\w*\s+.*$/.SS "$content"/; + } + + # Tables are similar to examples, except we need to handle the + # keywords. + if (/^\@(itemize|table)(\s+(.*))?$/) + { + $indent += 2; + push @table_headers, $table_header; + push @table_footers, $table_footer; + my $content = $3; + if (/^\@itemize/) + { + my $bullet = $content; + $table_header = qq{.IP "$bullet" $indent\n}; + $table_footer = ""; + } + else + { + my $hi = $indent - 2; + $table_header = qq{.IP "" $hi\n}; + $table_footer = qq{\n.IP "" $indent}; + if ($content) + { + $table_header .= "$content\{"; + $table_footer = "\}$table_footer"; + } + } + $intable++; + next; + } + + if ($intable) + { + if (/^\@end (itemize|table)$/) + { + $table_header = pop @table_headers; + $table_footer = pop @table_footers; + $indent -= 2; + $intable--; + next; + } + s/^\@itemx?(\s+(.*))?$/$table_header$2$table_footer/; + # Fall through so the rest of the table lines are + # processed normally. + } + + # Index entries. + s/^\@cindex\s+(.*)$/.IX "$1"/; + + $_ = "$last$_" if $last; + undef $last; + + # Trap keywords + $nk = qr/ + \@(\w+)\{ + (?{ debug_print "$ret MATCHED $&\nPUSHING $1\n"; + push @parent, $1; }) # Keep track of the last keyword + # keyword we encountered. + ((?> + [^{}]|(?<=\@)[{}] # Non-braces... + | # ...or... + (??{ $nk }) # ...nested keywords... + )*) # ...without backtracking. + \} + (?{ debug_print "$ret MATCHED $&\nPOPPING ", + pop (@parent), "\n"; }) # Lose track of the current keyword. + /x; + + $ret = "m//"; + if (/\@\w+\{(?:[^{}]|(?<=\@)[{}]|(??{ $nk }))*$/) + { + # If there is an opening keyword on this line without a + # close bracket, we need to find the close bracket + # before processing the line. Set $last to append the + # next line in the next pass. + $last = $_; + next; + } + + # Okay, the following works somewhat counter-intuitively. $nk + # processes the whole line, so @parent gets loaded properly, + # then, since no closing brackets have been found for the + # outermost matches, the innermost matches match and get + # replaced first. + # + # For example: + # + # Processing the line: + # + # yadda yadda @code{yadda @var{foo} yadda @var{bar} yadda} + # + # Happens something like this: + # + # 1. Ignores "yadda yadda " + # 2. Sees "@code{" and pushes "code" onto @parent. + # 3. Ignores "yadda " (backtracks and ignores "yadda yadda + # @code{yadda "?) + # 4. Sees "@var{" and pushes "var" onto @parent. + # 5. Sees "foo}", pops "var", and realizes that "@var{foo}" + # matches the overall pattern ($nk). + # 6. Replaces "@var{foo}" with the result of: + # + # do_keyword $file, $parent[$#parent], $1, $2; + # + # which would be "\Ifoo\B", in this case, because "var" + # signals a request for italics, or "\I", and "code" is + # still on the stack, which means the previous style was + # bold, or "\B". + # + # Then the while loop restarts and a similar series of events + # replaces "@var{bar}" with "\Ibar\B". + # + # Then the while loop restarts and a similar series of events + # replaces "@code{yadda \Ifoo\B yadda \Ibar\B yadda}" with + # "\Byadda \Ifoo\B yadda \Ibar\B yadda\R". + # + $ret = "s///"; + @parent = (""); + while (s/$nk/do_keyword $file, $parent[$#parent], $1, $2/e) + { + # Do nothing except reset our last-replacement + # tracker - the replacement regex above is handling + # everything else. + debug_print "FINAL MATCH $&\n"; + @parent = (""); + } + + # Finally, unprotect texinfo special characters. + s/\@://g; + s/\@([{}])/$1/g; + + # Verify we haven't left commands unprocessed. + die "Unprocessed command at line $. of file \`$file': " + . ($1 ? "$1\n" : "<EOL>\n") + if /^(?>(?:[^\@]|\@\@)*)\@(\w+|.|$)/; + + # Unprotect @@. + s/\@\@/\@/g; + + # And print whatever's left. + print $_; + } +} diff --git a/contrib/cvs/doc/stamp-1 b/contrib/cvs/doc/stamp-1 new file mode 100644 index 0000000..b17c01c --- /dev/null +++ b/contrib/cvs/doc/stamp-1 @@ -0,0 +1,4 @@ +@set UPDATED 7 May 2007 +@set UPDATED-MONTH May 2007 +@set EDITION 1.11.22.1 +@set VERSION 1.11.22.1 diff --git a/contrib/cvs/doc/stamp-vti b/contrib/cvs/doc/stamp-vti new file mode 100644 index 0000000..05bc349 --- /dev/null +++ b/contrib/cvs/doc/stamp-vti @@ -0,0 +1,4 @@ +@set UPDATED 27 January 2008 +@set UPDATED-MONTH January 2008 +@set EDITION 1.11.22.1 +@set VERSION 1.11.22.1 diff --git a/contrib/cvs/doc/version-client.texi b/contrib/cvs/doc/version-client.texi new file mode 100644 index 0000000..b17c01c --- /dev/null +++ b/contrib/cvs/doc/version-client.texi @@ -0,0 +1,4 @@ +@set UPDATED 7 May 2007 +@set UPDATED-MONTH May 2007 +@set EDITION 1.11.22.1 +@set VERSION 1.11.22.1 diff --git a/contrib/cvs/doc/version.texi b/contrib/cvs/doc/version.texi new file mode 100644 index 0000000..05bc349 --- /dev/null +++ b/contrib/cvs/doc/version.texi @@ -0,0 +1,4 @@ +@set UPDATED 27 January 2008 +@set UPDATED-MONTH January 2008 +@set EDITION 1.11.22.1 +@set VERSION 1.11.22.1 |
