diff options
| author | peter <peter@FreeBSD.org> | 1997-05-15 22:46:24 +0000 |
|---|---|---|
| committer | peter <peter@FreeBSD.org> | 1997-05-15 22:46:24 +0000 |
| commit | 4f40fe8334ad5f056e1d9105f23fe7ac859c39ba (patch) | |
| tree | 3b2f0092fa216d9f61059ba94b7f10b5bacf9496 /contrib/cvs/doc | |
| parent | 8982e501c77217c860f79bba431f46a62b607a21 (diff) | |
| download | FreeBSD-src-4f40fe8334ad5f056e1d9105f23fe7ac859c39ba.zip FreeBSD-src-4f40fe8334ad5f056e1d9105f23fe7ac859c39ba.tar.gz | |
Import of cvs-1.9.9-970515 onto vendor branch.
Obtained from: cyclic.com
Diffstat (limited to 'contrib/cvs/doc')
| -rw-r--r-- | contrib/cvs/doc/ChangeLog | 1296 | ||||
| -rw-r--r-- | contrib/cvs/doc/DIFFUTILS-2.7-BUG | 263 | ||||
| -rw-r--r-- | contrib/cvs/doc/Makefile.in | 22 | ||||
| -rw-r--r-- | contrib/cvs/doc/RCSFILES | 165 | ||||
| -rw-r--r-- | contrib/cvs/doc/cvs.texinfo | 6125 | ||||
| -rw-r--r-- | contrib/cvs/doc/cvsclient.texi | 1008 |
6 files changed, 7490 insertions, 1389 deletions
diff --git a/contrib/cvs/doc/ChangeLog b/contrib/cvs/doc/ChangeLog index 01efb1a..1ef10f4 100644 --- a/contrib/cvs/doc/ChangeLog +++ b/contrib/cvs/doc/ChangeLog @@ -1,3 +1,1299 @@ +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 diff --git a/contrib/cvs/doc/DIFFUTILS-2.7-BUG b/contrib/cvs/doc/DIFFUTILS-2.7-BUG new file mode 100644 index 0000000..f258ee7 --- /dev/null +++ b/contrib/cvs/doc/DIFFUTILS-2.7-BUG @@ -0,0 +1,263 @@ +The enclosed two messages describe a bug in GNU diff 2.6 and 2.7 which +may cause CVS to perform an erroneous merge. You may wish to use GNU +diff 2.5 or apply the patch supplied by Loren James Rittle below. It +would be nice to add this to the CVS testsuite, but I haven't done so +because probably a lot of people who would like to run the testsuite +are using the buggy diff. + +From: friedman@splode.com (Noah Friedman) +To: bug-gnu-utils@prep.ai.mit.edu +Cc: info-cvs@prep.ai.mit.edu +Subject: diffutils 2.7 -- diff3 merge bug +Date: Tue, 29 Oct 96 17:02:54 CST + +I believe a change first introduced in GNU diff 2.6 causes diff3 sometimes +to produce incorrect merges. + +Since this is a not a bug in CVS itself but can cause commits to CVS +repositories to be incorrect, am warning info-cvs@prep.ai.mit.edu as +well as reporting the bug to bug-gnu-utils@prep.ai.mit.edu. + +I am including a simple test case as well as some sample outputs from +different versions of `diff' and `diff3' in the enclosed shar archive. +In addition, the file DESCRIPTION in that archive describes the problem +more fully. + +If anyone has any advice for how to fix or to work around this bug, I would +appreciate it. Using diff 2.5 seems like the most immediately obvious +solution, but I don't know if it will introduce other problems. +I do not understand the algorithms used by GNU diff well enough to suggest +any patches. + +Unshar and enjoy. ;-) + +begin 666 merge-testcase.shar.gz +M'XL(",&,=C("`VUE<F=E+71E<W1C87-E+G-H87(`[5Q[;]M&$O_[^"FF;E#9 +M@41)?C!GYX&V;MPS<$F+V+FZP.&:%;F26)-<E;NTHC[NL]_,+%^29;USUP-L +M&)9$[CQW]C?#W;$^_ZS="Y.V'CJ?P_4PU("_`O101A&(U!^&=Q+V1ZD*,E\& +MT)O`MV_?XVV19B:,-!R[W0.72!7(CR85O@$SE-`/(ZFAGZH8/Q)'RZD)6B"_ +M$`<IT"J6<''Y]]=-2&6L[B2RD7<RG2!%,H">[*M4,K</A8X-B,)$@N@IXH6W +M$C"3$0[00^;40%60RQL12%`)=$]/O5:WTSH\A:YW=G(,YU?79,*+?AK*(!;) +MEWH4J4"ZOHI?D157*DM]"4&82M^H=`)CH>%#.]-I.U*^B-HZ]=N#)&L'8;_/ +M#FC',AW(EI':^$++7('7'T-MR`CKAW&(SGR:*/,4K0+4/1VGH3&H?9;@?131 +M\AOD>#V2?MA'W2P;G@_R-?@J,2),]!E>C60R,$.(47&P/XF(R7DM_LE?9MXN +M^T%R_#DZ]:"5CO-?F+:M7;QI3=!-VE(\ZQRM0A'CM%D"[_1X%0(5!3*U%,<G +MAPLHWHA;25[FL8?=PV<+QG[S^NK\W>7WUY??O<U9=Q;92Y-\Z)Y87>I&>R>K +MD)'-=:I5A'ESA!T_6X'LOK"3%52LYH?N!ZM,:2%P'FFW>[1HJJ[>OWGSU;L? +M,;2-ROPAM$0,W<,C_#TY/3V%)T]<>_U5.Y!W[23#17/XZHNN$_:!>,!GT.K7 +M";[XPE['JP7M<P8%!WC5_,277O)?1T9:3E\_PX_2'ZK\!1H_?/7N[>7;;\\` +M5RI"DD8$H#5LPAC?BWBD78!SE>@09P@&TO`*%TG0*#CLX0HU(HKH.L'D/S^P +MI$83$46;-.QE!C$T3/CF!08MO$<,"4THM>NZ>X4^_=!)XQE;"P,9%U[6?Q:O +MTNFQ+^N^#*`Q`UZE]ZP_/D(+_%0*MK/"Q!DB'![?XMU[W,B.0AP:TUBH9Z.< +MS9N])]T]^.PEOFGY>W-4TK?A:$0J+39\GU`!1(0&!!-,3C@#^J!1Q$'%+D]; +M*S`T./2`[-4XBPW=_M=-N]V`%R^@<?6WK][]]/J[BP:\6L%.I]V&KS-C5.+^ +M+.Z$<^.,A'\K!A)2C"85NV(TBD(?_:Z2YW@WC$<J-<5-2CON4[H^RGHX#/Q( +M8`JQ#)W?G!N`]E.XI$A,3"A0/.9S>Q<3$28.C.H!QN!^IPF=`XI?^%6F"N\% +M>),^#F4X&!J7.,%3^%%E$&<X,9C_L"1(,'XQ8D44(A5ZS`Q50-D<2X213*-) +M[3;G[MQ0RZQ-+[G:N4K[!W2-U4;'9L@#+Y%U?.$G$YI(GJM(I?`2^-7M1>BM +MY_E]7%BB%\G@^OZX02HFS^ML+C")XEUZ<0/9%UED^!++`_C#^<,I)A(G^4D% +M%1:I.H>GW9-##U/D"E,,X`\Q0T/'\Y:/__WW,B(M[&"1T%\2C7V!X<W0PWKZ +M*DO,R[T/8Q]:/KQ8)O(#@0TO-T[Y\A?8>U+QV;,:%:BVD-59'D\B`DUSCOR: +MX&=I*M&S?*7.F#!A5?RBE/80?"W"$Z+;)9RP'CM$$\MO2S`IC'S$DI6Q!#VU +M#$YHR&J(4C);"BHWN1>Q<KB322@3?,#`<A[K@8SR*>!3#H2EA[FDJ+LX]UP/ +MET^@X6,3)DWKWF;=OP"O?\G".Q'1JC,J)Z*?OE*H7B+'E9.>3]]VR<NP/\7: +MLBU&SG-UB(*0A%XF]B4GI;<Y>6TV^"FP$`U+)*Z&Q,\6(7&Y/E8#8CM\/1SF +M=;PI#+/`"H6YYMX,A8G3+`@CNQV!,#^.;(+"3+A+&+::[!"'<X9;`G%IYR,2 +M_TFKND<`_D0`O+`4KM;%:@B<CU\/@NT2WA2#K<@*A'EK:C,09E:S*(S\MD/A +M8F]K#?PM2':`O*7T[3&W8K49VM:M<KZYO+@XPB5%.U%'_"G_@"N=Z<Z<F[^T +MGNSSN`-HO>:8G4[;,Q$TL[-YPWNO:'(ZR&*</,T8@8[32#E68/"&Q*MCB>$9 +M2"-38LJ[X[CX9.K+$7D!N;".#6U1%@.9/C-L(.",I/65F9*$ZW*$R,];P*3$ +MQ.X>WXET@J)&,@F(!@&`R,)DE!G>9'8=8EW?/20O6">@#P2T6D.,SE]5TJ(M +M=/VRV\%+B_V`L9)F$KW!K*L=QII_Y[/N3K&>=GB=\S*(\;K=.1`S%0P+P:4: +MN1*LE%&Z)J"48BHHX3WKM:"D8#(+(LAI.Q"I;7JO@2,UJAU`25V'[=%DBMMF +M@#)CGF-/6J2AJ+!G-KCHL#Q*\TJ+S2=*&`]YT=.Z9KU(O_QX3#MAXJN4]DEI +M^Q@+$4W#$\ATL2-<GAO!H>OA3%-=(%.L'E@!7V0:N?@JCD.DQ?KK_!]7R&JD +M=$B;T9*O]6C=YW*:H!5<`BZ81)FP/R$YYQ,?ZP3G2O7-6-A`)ZQ`);&DBD$0 +M;E'-IZ&7#5J#)&NQ1E^.4)`K0A=ENS+(L+ASD+/)]ZVG>*`6?,JGHDB-<06* +M9$">"7'Q8I4K42IO<S/:H:%-A[`-ZU["2#2CSP4ELWC[^H<KL(N.(5:8:J\< +M"<Z*DG'/==WO16J04M"$6/\V2Z<BQJK,$!JB'VG_7G[$X,'1)$2+&"-.6T[V +M7-&%]SI#4)X0X/*19P_?Z!@OR;2)GC%\/LE[_U-#(L+^U-TCQ9PWDUIDU".F +M\@[-B/9E(M)0Y=9\90W.S_1X`!V%^G2@1U$PE/XM>@KMH8Q""6<DU8@P_@8X +M+_7#%(5B4:TQ#P0RDC9(^UGBD],XP11!Q'%E)\C.&C$I0VI2\M02]0D*ID3- +MZ8B4&*'?*8H$^G5(]59=#@:(C$<<K<3*BJU)I4.3K\D2R=%MHQ'O<FQ@`/(Q +MKEWA$"C)DV=5I"/A/.KD7:@R'4U:UMB@4B$_8I[1OU%))UY7J@BW/@.KKT9E +M`%:NL)K<DS"DA2(1Z%@ISAVT-*[+4^ZI1-><2:G-F<Q'9]UHC^;'!)R,6;6) +MI56D3`/V$OG:S,Q],=Y!AEQ-W,EH4E<.'CCHXW!.\J<>GR=%0`%==B[L0V7? +M(9EFF$H)=R@3'8(FE.T`/*B.:2=N$:'H&>?^22B;,>=<==HK/`)#-TMNZ8X( +M$%AI*5C4I<=2F>(BCLO0P34TQVQOKMEV]G-0K`";1U2F.?=,\W+3[!HH)#S- +M@X"`5N!LJ0$&:K[2PK3P`'"VEBFM)`I)AQZ_N:XCV/9MF-]*:R'F%YJ3/#ZM +M$V1,_0)<81;^H6'&R2>EK"T)12LF%+EF+*E-8JH:XV":BDM&>RN1P:S@A\H_ +ML"Z$G2HL2`MGLNNI@R1Q"'G4.&'M65H!Q[$PB&^ZOF1Y3"ZO5-A94>$RQ5C5 +M[:(GSJ1C/BWH9G2F`,K"D?5H,\]6ER@O"N6==&*LORS2QP@(.NSE*:F,.4-) +MTU+Q-#)O*S!@_?B>4]W#B,+E6#C.75[M'I[.J79G*Y6%!>_4X)5JWGHMM6;9 +M6Q=65;ZV!6.MTK?&:+;Z)6[;E;_SP&;U,G@.]0[*X7DZ;5\6S^6Z67G\@-G. +MC>M6K4\M',&?-GR\=`X[S:-.T#UU7@#^;K5'1^3K;]+E5`_NTDW?7[A-9X>V +M^763C3JB^\URJ;;J[,=E8I=OU7F=><CRT"0O1)BY1"LAS;SP7!-QY@FO/7-W +MUCW)GL/OWN-WQ]L-_M1JH/7AIR+>(?K4--H=^-29;H<]TS:O`SU+MY^<KM?L +M_M7GO_DB6WPX7(U9>C(QPV[1Z02U7;Z")0<B^8"E<NN,%@E]!-T_!>C.1/=* +MF%NG60MR:XMR0\2MB:Z=EYQL"KBUO>39,Y.3G>"MMU6]YWV2>L_[)/6>M[MZ +MSUM:[WF/]=[_!?1T.P]"C[=)O>=M7.]YV]=[WH[K/>^_4.]YV]1[WJ>H][Q/ +M4>]Y.ZOWO&7UGK=EO7=X^C^O]^SB?02_3<'O?U(O;X>UZY=YWJ9EGK=UF><] +M4.8=/]L09Q>4><<[VM:;W>%?_]EZAL,.'[!G==O=4_8]SML]:L]QP6,WXY^] +MKWR5,O!PP1/HO$E?Z3'T'N%:SZ*SH;OA`^FL$O6R\&3#I](9GO=+PY/=E(;; +M8I;WR3#+^V28Y>T6L[Q'S'K\7YC'5NP5@-[;%.B]K8#>VPW0>PN`?OW_F7F` +MY\[_>R;_1_<U@#VGV`&0%[*W!^Z2TV9`73/)N;E(57P&<[YV`_;?*C&$B_S. +M@7.MSA;W)3KG_ADNFKYJ^7?W;UYEO9^E;\ZF6G>>T09!U;(I28#S3HZB28O$ +MS5'+^08!_@RN,]F$PU/XSC?\92+\-2)'9]UC:'6\3@?VSZ^N#YP+'S7Z=UL: +MOQUCD+>1NZ[V+O"QE1R8MP-JN_IIYP*?9LOV$VI+LDUZMK\+@:/HL<J_+J!H +M=,F;1'-SRAY%QZ8*(IEM:N)6F:LPX3:CX@M>J$52D!^(/W69AD;+J,^-CSXF +M(]NL-]V)ZBSN1$4T&HN4^QD?FAYJPBR:3XE96C;`DR;$<86.U)B$1EE@TX/& +M+![)6AMFK;^5VRJUX`&V.]1^)XU3]D^536T$9!^XD913R0?;N%\T86&BBA1% +M/W\92_YE-B[U'XD@"*F>:%8=4/66&J87IOPFG4!J/PU[>0-4WD[KQ(2D_2RR +MS7N7U&DY48GDUD-\BT+NJ$F,LN-0C<E/_?`C=0_CN[%*;Y$]I40[O=Q3>8G7 +MLRAPL.+!R:%J!2<8,^-[;;_+P79VX8*6,07CK:TI8D6A%\<R(`JL.52/&R\= +MK:+,6DGQ<0F!2AH&;A-4!D$M-+:7K0S:O$<N-P_CCR@XY%!+=+@IFAE%-,!@ +M,D-4(M/5UPNQ?CR),E'98,C?%I0-,)2-0_X8V28R<M;[Q$X)M9@E/ZL)VOB\ +M=;`\8YX<S<F8=<A:F"'+@2MEQ`)(U\R`A9`JX]GO5UDKY>5,9E,<<5J2XS!E +-&.@X_P&I*Y$W($H``"'+ +` +end + +Date: Wed, 30 Oct 96 14:54:13 CST +From: Loren James Rittle <rittle@comm.mot.com> +To: friedman@splode.com +Cc: bug-gnu-utils@prep.ai.mit.edu, info-cvs@prep.ai.mit.edu +Subject: Re: diffutils 2.7 -- diff3 merge bug + +Noah, + +I have seen the problem you discuss in your e-mail, however I fail to +see how this situation is as critical as might be implied since it can +never arise without at least some user involvement (an update that +caused a merge is never automatically followed by a commit --- the +user has a chance to inspect the merged file). However, I will agree +that I don't always look very closely at non-conflicted merges before +checking them back in. + +You didn't give the exact CVS commands used to create a lossage, +but I added the following to your Makefile, to help me see the problem +in a CVS usage context: + +t-older: testcase-older + cp testcase-older t-older + +t-yours: testcase-yours + cp testcase-yours t-yours + +t-mine: testcase-mine + cp testcase-mine t-mine + +# Assume cvs-1.9 +cvs-test: t-older t-yours t-mine + rm -rf /tmp/cvs-test-root x x2 + cvs -d /tmp/cvs-test-root init + mkdir x + cp t-older x/testcase + cd x; cvs -d /tmp/cvs-test-root import -m '' x X X1 + rm -rf x + cvs -d /tmp/cvs-test-root co x + cvs -d /tmp/cvs-test-root co -d x2 x + cp t-yours x/testcase + cp t-mine x2/testcase + cd x; cvs ci -m '' + -cd x2; cvs ci -m '' + cd x2; cvs update + cat x2/testcase # at this point, user may commit blindly + +It looks like whomever added shift_boundaries() in analyze.c, which +seems to be the source of the diff3 induced mischief, already provided +a means to disable the boundary shifting optimization (at least with +a recompile). + +Here is the patch I applied to diff to disable this (currently) +overaggressive optimization: + +[ rittle@supra ]; diff -c analyze.c-old analyze.c +*** analyze.c-old Wed Oct 30 14:10:27 1996 +--- analyze.c Wed Oct 30 13:48:57 1996 +*************** +*** 616,622 **** + but usually it is cleaner to consider the following identical line + to be the "change". */ + +! int inhibit; + + static void + shift_boundaries (filevec) +--- 616,622 ---- + but usually it is cleaner to consider the following identical line + to be the "change". */ + +! int inhibit = 1; + + static void + shift_boundaries (filevec) + +Now, diff-2.7 with the above patch produces: + +[ rittle@supra ]; make diff-mine-yours 'DIFF=/usr/src/diffutils-2.7/diff' +/usr/src/diffutils-2.7/diff -a --horizon-lines=11 -- testcase-mine testcase-yours; true +16,18c16,18 +< // _titleColor = Color.black; +< // _disabledTitleColor = Color.gray; +< // _titleFont = Font.defaultFont (); +--- +> _titleColor = Color.black; +> _disabledTitleColor = Color.gray; +> _titleFont = Font.defaultFont (); +20,30d19 +< +< /* Convenience constructor for instantiating a Button with +< * bounds x, y, width, and height. Equivalent to +< * foo = new Button (); +< * foo.init (x, y, width, height); +< */ +< public Button (int x, int y, int width, int height) +< { +< this (); +< init (x, y, width, height); +< } + +Whereas, stock diff-2.7 produces: + +[ rittle@supra ]; make diff-mine-yours +diff -a --horizon-lines=11 -- testcase-mine testcase-yours; true +16,29c16,18 +< // _titleColor = Color.black; +< // _disabledTitleColor = Color.gray; +< // _titleFont = Font.defaultFont (); +< } +< +< /* Convenience constructor for instantiating a Button with +< * bounds x, y, width, and height. Equivalent to +< * foo = new Button (); +< * foo.init (x, y, width, height); +< */ +< public Button (int x, int y, int width, int height) +< { +< this (); +< init (x, y, width, height); +--- +> _titleColor = Color.black; +> _disabledTitleColor = Color.gray; +> _titleFont = Font.defaultFont (); + +A better solution might be to disable the boundary shifting code +unless explicitly turned on via command line argument. That way +programs, like diff3, expecting unoptimized diff regions will work +correctly, yet users can get smaller diffs, if desired. The problem +is that diff3 doesn't properly track changes once they have been +optimized. + +BTW, I never did like the look of the `optimized diff regions', so I +consider this a good change for other reasons... :-) + +Enjoy! + +Regards, +Loren +-- +Loren J. Rittle (rittle@comm.mot.com) PGP KeyIDs: 1024/B98B3249 2048/ADCE34A5 +Systems Technology Research (IL02/2240) FP1024:6810D8AB3029874DD7065BC52067EAFD +Motorola, Inc. FP2048:FDC0292446937F2A240BC07D42763672 +(847) 576-7794 Call for verification of fingerprints. diff --git a/contrib/cvs/doc/Makefile.in b/contrib/cvs/doc/Makefile.in index 11c7051..29eb565 100644 --- a/contrib/cvs/doc/Makefile.in +++ b/contrib/cvs/doc/Makefile.in @@ -12,12 +12,6 @@ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - -# $CVSid: @(#)Makefile.in 1.8 94/10/22 $ - SHELL = /bin/sh srcdir = @srcdir@ @@ -34,6 +28,7 @@ INSTALL_DATA = @INSTALL_DATA@ DISTFILES = \ .cvsignore ChangeLog ChangeLog.fsf Makefile.in \ + RCSFILES \ cvs-paper.ms cvs-paper.ps \ cvs.texinfo \ cvsclient.texi @@ -99,10 +94,12 @@ cvsclient.txt: cvsclient.texi CVSvn.texi # it, and builds it in a seperate build dir, then *.info* are in srcdir. # If the user builds *.info (e.g. after editing *.texi), then *.info* are # in the build dir. -install-info: info - test -f cvs.info || cd $(srcdir); \ - for i in *.info* ; do \ - $(INSTALL_DATA) $$i $(infodir)/$$i ; \ +# (Note: don't solve this problem with "cd"; INSTALL_DATA might be a +# relative path to install-sh). +install-info: info installdirs + if test -f cvs.info ; then docdir=.; else docdir=$(srcdir);fi; \ + for i in $$docdir/*.info* ; do \ + $(INSTALL_DATA) $$i $(infodir)/`basename $$i` ; \ done installdirs: @@ -130,10 +127,7 @@ cvsclient.dvi cvsclient.aux: cvsclient.texi CVSvn.texi ln -s $(srcdir)/CVSvn.texi . || \ ln $(srcdir)/CVSvn.texi . || \ cp $(srcdir)/CVSvn.texi . ; else true; fi - $(SET_TEXINPUTS) $(TEX) cvsclient.texi - $(SET_TEXINPUTS) $(TEX) cvsclient.texi - $(TEXINDEX) cvsclient.?? - $(SET_TEXINPUTS) $(TEX) cvsclient.texi + $(TEXI2DVI) $(srcdir)/cvsclient.texi rm -f cvsclient.?? cvsclient.log cvsclient.toc cvsclient.??s cvs.ps: cvs.dvi diff --git a/contrib/cvs/doc/RCSFILES b/contrib/cvs/doc/RCSFILES new file mode 100644 index 0000000..41d131b --- /dev/null +++ b/contrib/cvs/doc/RCSFILES @@ -0,0 +1,165 @@ +It would be nice for 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 first time I read rcsfile.5 I didn't really notice the part about +the order of the revisions. This order _is_ important and CVS relies +on it. It is documented but it would be clearer if the example in +rcsfile.5 also showed the order of the revisions (and the "next" and +"branch" fields and anything else where it would be useful to have an +example of how a revision tree is represented in an RCS file). + +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 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 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. + +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.texinfo b/contrib/cvs/doc/cvs.texinfo index 29bc5f3..6330984 100644 --- a/contrib/cvs/doc/cvs.texinfo +++ b/contrib/cvs/doc/cvs.texinfo @@ -16,11 +16,29 @@ @comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @comment GNU General Public License for more details. -@comment You should have received a copy of the GNU General Public License -@comment along with CVS; see the file COPYING. If not, write to -@comment the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. +@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 (according to +@c an internet draft by Jacob Palme). + +@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 -@afourpaper @setfilename cvs.info @include CVSvn.texi @settitle CVS---Concurrent Versions System @@ -120,27 +138,36 @@ This info manual describes how to use and administer @sc{cvs} version @value{CVSVN}. @end ifinfo +@c This menu is pretty long. Not sure how easily that +@c can be fixed; seems like "Adding files", "Removing +@c files", "Removing directories", "Moving files", +@c and "Moving directories" all go together (into +@c "Adding, removing, and renaming"?). Other than that +@c no brilliant ideas for a fix... @menu * Preface:: About this manual * What is CVS?:: What is CVS? -* Basic concepts:: Basic concepts of revision management * A sample session:: A tour of basic CVS usage * Repository:: Where all your sources are stored * Starting a new project:: Starting a project with CVS * Multiple developers:: How CVS helps a group of developers -* Branches:: Parallel development explained +* Revisions and branches:: Numeric, symbolic, and branch revisions * Merging:: How to move changes between branches * Recursive behavior:: CVS descends directories -* Adding files:: Adding files to a module -* Removing files:: Removing files from a module +* Adding files:: Adding files +* Removing files:: Removing files +* Removing directories:: Removing directories * Tracking sources:: Tracking third-party sources * Moving files:: Moving and renaming files * Moving directories:: Moving and renaming directories * History browsing:: Viewing the history of files in various ways * Keyword substitution:: CVS can include the revision inside the file * Binary files:: CVS can handle binary files +* Builds:: Issues related to CVS and builds +* Compatibility:: Upgrading CVS versions * Revision management:: Policy questions for revision management -* Invoking CVS:: Reference manual for CVS commands +* 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 * Troubleshooting:: Some tips when nothing works @@ -187,34 +214,6 @@ every @sc{cvs} command is gathered together. There is also an extensive index, and a lot of cross references. @end itemize -@cindex Signum Support -@cindex Support, getting CVS support -This manual was contributed by Signum Support AB in -Sweden. Signum is yet another in the growing list of -companies that support free software. You are free to -copy both this manual and the @sc{cvs} program. -@xref{Copying}, for the details. Signum Support offers -@c -- Check this reference! It has been bogus in the past. -support contracts and binary distribution for many -programs, such as @sc{cvs}, @sc{gnu} Emacs, the -@sc{gnu} C compiler and others. Write to us for -more information. - -@example -Signum Support AB -Box 2044 -S-580 02 Linkoping -Sweden - -Email: info@@signum.se -Phone: +46 (0)13 - 21 46 00 -Fax: +46 (0)13 - 21 47 00 -@end example - -Another company selling support for @sc{cvs} is Cyclic -Software, web: @code{http://www.cyclic.com/}, email: -@code{info@@cyclic.com}. - @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @menu * Checklist:: @@ -243,12 +242,12 @@ flag (release 1.15 and later are OK). You must also configure both @sc{rcs} and @sc{cvs} to handle binary files when you install them. -Keword substitution can be a source of trouble with +Keyword substitution can be a source of trouble with binary files. @xref{Keyword substitution}, for solutions. @item The @code{admin} command -Uncareful use of the @code{admin} command can cause +Careless use of the @code{admin} command can cause @sc{cvs} to cease working. @xref{admin}, before trying to use it. @end table @@ -259,10 +258,10 @@ to use it. @cindex Contributors (manual) @cindex Credits (manual) -Roland Pesch, Cygnus Support <@t{pesch@@cygnus.com}> +Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}> wrote the manual pages which were distributed with -@sc{cvs} 1.3. Appendix A and B contain much text that -was extracted from them. He also read an early draft +@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. @@ -274,15 +273,16 @@ David G. Grubbs <@t{dgg@@think.com}>. Some text has been extracted from the man pages for @sc{rcs}. -The @sc{cvs} @sc{faq} (@pxref{What is CVS?}) by David -G. Grubbs has been used as a check-list to make sure -that this manual is as complete as possible. (This -manual does however not include all of the material in -the @sc{faq}). The @sc{faq} contains a lot of useful -information. +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}>, @@ -290,52 +290,122 @@ 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 @unnumberedsec BUGS -@cindex Bugs, known in this manual -@cindex Known bugs in this manual -This manual is known to have room for improvement. -Here is a list of known deficiencies: - +@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 -In the examples, the output from @sc{cvs} is sometimes -displayed, sometimes not. +If you want someone to help you and fix bugs that you +report, there are companies which will do that for a +fee. Two such companies are: -@item -The input that you are supposed to type in the examples -should have a different font than the output from the -computer. +@cindex Signum Support +@cindex Cyclic Software +@cindex Support, getting CVS support +@example +Signum Support AB +Box 2044 +S-580 02 Linkoping +Sweden +Email: info@@signum.se +Phone: +46 (0)13 - 21 46 00 +Fax: +46 (0)13 - 21 47 00 +http://www.signum.se/ + +Cyclic Software +United States of America +http://www.cyclic.com/ +info@@cyclic.com +@end example @item -This manual should be clearer about what file -permissions you should set up in the repository, and -about setuid/setgid. +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 -Some of the chapters are not yet complete. They are -noted by comments in the @file{cvs.texinfo} file. +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 -@cindex Reporting bugs (manual) -@cindex Bugs, reporting (manual) -@cindex Errors, reporting (manual) -This list is not complete. If you notice any error, -omission, or something that is unclear, please send -mail to @t{bug-cvs@@prep.ai.mit.edu}. -@end itemize +There may be resources on the net which can help. Two +good places to start are: + +@example +http://www.cyclic.com + @r{particularly the Unsupported Resources page} +http://www.loria.fr/~molli/cvs-index.html +@end example -I hope that you will find this manual useful, despite -the above-mentioned shortcomings. +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. -@flushright +@item +It is also possible to report bugs to @code{bug-cvs}. +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 @code{bug-cvs@@prep.ai.mit.edu}. Note +that submissions to @code{bug-cvs} 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 +@code{bug-cvs}; those maintainers who want to hear +about such bug reports read @code{bug-cvs}. Also note +that sending a bug report to other mailing lists or +newsgroups is @emph{not} a substitute for sending it to +@code{bug-cvs}. 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 @code{bug-cvs}. +@end itemize -Linkoping, October 1993 -Per Cederqvist -@end flushright +@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 What is CVS? @@ -383,7 +453,8 @@ the work when each developer is done. @cindex Credits (CVS program) @cindex Contributors (CVS program) @sc{cvs} started out as a bunch of shell scripts written by -Dick Grune, posted to @code{comp.sources.unix} in the volume 6 +Dick Grune, posted to the newsgroup +@code{comp.sources.unix} in the volume 6 release of December, 1986. While no actual code from these shell scripts is present in the current version of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms @@ -394,21 +465,56 @@ Jeff Polk later helped Brian with the design of the @sc{cvs} module and vendor branch support. @cindex Source, getting CVS source -You can get @sc{cvs} via anonymous ftp from a number of -sites, for instance @t{prep.ai.mit.edu} in -@file{pub/gnu}. +You can get @sc{cvs} via anonymous @sc{ftp} from a +number of sites; for example see +@example +http://www.gnu.ai.mit.edu/order/ftp.html +@end example +for a list of the @sc{gnu} @sc{ftp} sites. +@c We could also be pointing to other resources like +@c the cyclic getting.html, Pascal Molli's page, etc., +@c and probably should, when someone gets around to +@c figuring out which pages are stable enough that we +@c should cite them, which ones are best to point +@c people to (supported? binary? source? zero-cost? +@c buying CD-ROMs? etc.), etc. @cindex Mailing list @cindex List, mailing list -There is a mailing list for @sc{cvs} where bug reports -can be sent, questions can be asked, an FAQ is posted, -and discussion about future enhancements to @sc{cvs} -take place. To submit a message to the list, write to -<@t{info-cvs@@prep.ai.mit.edu}>. To subscribe or -unsubscribe, write to -<@t{info-cvs-request@@prep.ai.mit.edu}>. Please be -specific about your email address. - +@cindex Newsgroups +@c Be careful in editing this--it is worded so that +@c the long -request address is in the middle of a +@c line, thus avoiding overfull hboxes. +There is a mailing list, known as @w{@code{info-cvs}}, +devoted to @sc{cvs}. To subscribe or +unsubscribe +@c could add "to the mailing list," +send a message to +@c or "write to" +@w{@code{info-cvs-request@@prep.ai.mit.edu}}. Please +be specific about your email address. As of May 1996, +subscription requests are handled by a busy human +being, so you cannot expect to be added or removed +immediately. If you prefer a usenet group, the right +group is @code{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 +@code{comp.software.config-mgmt}. +@c Other random data is that past attempts to create a +@c gnu.* group have failed (the relevant authorities +@c say they'll do it, but don't), and that 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 bug-cvs mailing list, +described in more detail in @ref{BUGS}. To subscribe +send mail to bug-cvs-request@@prep.ai.mit.edu. @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @unnumberedsec CVS is not@dots{} @@ -433,7 +539,7 @@ checked out working directories. If you write your @file{Makefile}s or scripts in every directory so they have to know the relative positions of everything else, you wind up requiring the entire repository to be -checked out. That's simply bad planning. +checked out. If you modularize your work, and construct a build system that will share files (via links, mounts, @@ -442,14 +548,22 @@ arrange your disk usage however you like. But you have to remember that @emph{any} such system is a lot of work to construct and maintain. @sc{cvs} does -not address the issues involved. You must use your -brain and a collection of other tools to provide a -build scheme to match your plans. +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 @@ -489,175 +603,64 @@ Acquire the habit of reading specs and talking to your peers. -@item @sc{cvs} is not a configuration management system. - -@sc{cvs} is a source control system. The phrase -``configuration management'' is a marketing term, not -an industry-recognized set of functions. - -A true ``configuration management system'' would contain -elements of the following: - -@itemize @bullet -@item Source control. -@item Dependency tracking. -@item Build systems (i.e. What to build and how to find -things during a build. What is shared? What is local?) -@item Bug tracking. -@item Automated Testing procedures. -@item Release Engineering documentation and procedures. -@item Tape Construction. -@item Customer Installation. -@item A way for users to run different versions of the same -software on the same host at the same time. -@end itemize - -@sc{cvs} provides only the first. +@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 +testsuite 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 builtin 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 -This section is taken from release 2.3 of the @sc{cvs} -@sc{faq}. - -@c --------------------------------------------------------------------- -@node Basic concepts -@chapter Basic concepts -@cindex Modules (intro) -@cindex Repository (intro) - -@sc{cvs} stores all files in a centralized -@dfn{repository}: a directory (such as -@file{/usr/local/cvsroot} or -@file{user@@remotehost:/usr/local/cvsroot}) which is -populated with a hierarchy of files and directories. -(@pxref{Remote repositories} for information about -keeping the repository on a remote machine.) - -Normally, you never access any of the files in the -repository directly. Instead, you use @sc{cvs} -commands to get your own copy of the files, and then -work on that copy. When you've finished a set of -changes, you check (or @dfn{commit}) them back into the -repository. - -The files in the repository are organized in -@dfn{modules}. Each module is made up of one or more -files, and can include files from several directories. -A typical usage is to define one module per project. - -@menu -* Revision numbers:: The meaning of a revision number -* Versions revisions releases:: Terminology used in this manual -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Revision numbers -@section Revision numbers -@cindex Revision numbers -@cindex Revision tree -@cindex Linear development -@cindex Number, revision- -@cindex Decimal revision number -@cindex Main trunk (intro) -@cindex Branch number -@cindex Number, branch - -Each version of a file has a unique @dfn{revision -number}. Revision numbers look like @samp{1.1}, -@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}. -A revision number always has an even number of -period-separated decimal integers. By default revision -1.1 is the first revision of a file. Each successive -revision is given a new number by increasing the -rightmost number by one. The following figure displays -a few revisions, with newer revisions to the right. - -@example - +-----+ +-----+ +-----+ +-----+ +-----+ - ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! - +-----+ +-----+ +-----+ +-----+ +-----+ -@end example - -@sc{cvs} is not limited to linear development. The -@dfn{revision tree} can be split into @dfn{branches}, -where each branch is a self-maintained line of -development. Changes made on one branch can easily be -moved back to the main trunk. - -Each branch has a @dfn{branch number}, consisting of an -odd number of period-separated decimal integers. The -branch number is created by appending an integer to the -revision number where the corresponding branch forked -off. Having branch numbers allows more than one branch -to be forked off from a certain revision. - -@need 3500 -All revisions on a branch have revision numbers formed -by appending an ordinal number to the branch number. -The following figure illustrates branching with an -example. - -@example -@group - +-------------+ - Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! - / +-------------+ - / - / - +---------+ +---------+ +---------+ +---------+ -Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !----! 1.2.2.4 ! - / +---------+ +---------+ +---------+ +---------+ - / - / -+-----+ +-----+ +-----+ +-----+ +-----+ -! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk -+-----+ +-----+ +-----+ +-----+ +-----+ - ! - ! - ! +---------+ +---------+ +---------+ -Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! - +---------+ +---------+ +---------+ - -@end group -@end example - -@c -- However, at least for me the figure is not enough. I suggest more -@c -- text to accompany it. "A picture is worth a thousand words", so you -@c -- have to make sure the reader notices the couple of hundred words -@c -- *you* had in mind more than the others! - -@c -- Why an even number of segments? This section implies that this is -@c -- how the main trunk is distinguished from branch roots, but you never -@c -- explicitly say that this is the purpose of the [by itself rather -@c -- surprising] restriction to an even number of segments. - -The exact details of how the branch number is -constructed is not something you normally need to be -concerned about, but here is how it works: When -@sc{cvs} creates a branch number it picks the first -unused even integer, starting with 2. So when you want -to create a branch from revision 6.4 it will be -numbered 6.4.2. All branch numbers ending in a zero -(such as 6.4.0) are used internally by @sc{cvs} -(@pxref{Magic branch numbers}). The branch 1.1.1 has a -special meaning. @xref{Tracking sources}. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Versions revisions releases -@section Versions, revisions and releases -@cindex Revisions, versions and releases -@cindex Versions, revisions and releases -@cindex Releases, revisions and versions - -A file can have several versions, as described above. -Likewise, a software product can have several versions. -A software product is often given a version number such -as @samp{4.1.1}. - -Versions in the first sense are called @dfn{revisions} -in this document, and versions in the second sense are -called @dfn{releases}. To avoid confusion, the word -@dfn{version} is almost never used in this document. - @c --------------------------------------------------------------------- @node A sample session @chapter A sample session @@ -668,9 +671,39 @@ called @dfn{releases}. To avoid confusion, the word @cindex tc, Trivial Compiler (example) @cindex Trivial Compiler (example) -This section describes a typical work-session using -@sc{cvs}. It assumes that a repository is set up -(@pxref{Repository}). +@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}. @@ -707,7 +740,7 @@ the source files. @example $ cd tc -$ ls tc +$ ls CVS Makefile backend.c driver.c frontend.c parser.c @end example @@ -718,7 +751,7 @@ 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. +you want to edit. @xref{Multiple developers}, for an explanation. @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @node Committing your changes @@ -729,7 +762,10 @@ you want to edit. @xref{Multiple developers} for an explanation. @cindex EDITOR, environment variable When you have checked that the compiler is still compilable you decide -to make a new version of @file{backend.c}. +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 @@ -744,8 +780,34 @@ The environment variable @code{$CVSEDITOR} determines which editor is started. If @code{$CVSEDITOR} is not set, then if the environment variable @code{$EDITOR} is set, it will be used. If both @code{$CVSEDITOR} and -@code{$EDITOR} are not set then the editor defaults to -@code{vi}. If you want to avoid the overhead of +@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. + +@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. + +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: @@ -829,6 +891,7 @@ 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 @@ -846,52 +909,84 @@ Are you sure you want to release (and delete) module `tc': y @c --------------------------------------------------------------------- @node Repository @chapter The Repository +@cindex Repository (intro) @cindex Repository, example @cindex Layout of repository @cindex Typical repository -@cindex CVSROOT, environment variable -@cindex .profile -@cindex .cshrc -@cindex .tcshrc -@cindex .bashrc -@cindex /usr/local/cvsroot +@cindex /usr/local/cvsroot, as example repository @cindex cvsroot -Figure 3 below shows a typical setup of a repository. -Only directories are shown below. +The @sc{cvs} @dfn{repository} stores a complete copy of +all the files and directories which are under version +control. -@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 +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: +@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 +does not contain @samp{:}, then @code{:local:} is +assumed. If it does contain @samp{:} than 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 +* 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 a couple of different ways to tell @sc{cvs} where to find the repository. You can name the @@ -902,6 +997,11 @@ repository on the command line explicitly, with the 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. @@ -922,6 +1022,8 @@ 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 @@ -929,35 +1031,93 @@ repository, it will remember where its repository is (the information is recorded in the @file{CVS/Root} file in the working copy). -The @code{-d} option and the @file{CVS/Root} file -both override the @code{$CVSROOT} environment variable; -however, @sc{CVS} will complain if the @file{-d} -argument and the @file{CVS/Root} file disagree. - -There is nothing magical about the name -@file{/usr/local/cvsroot}. You can choose to place the -repository anywhere you like. -@xref{Remote repositories} to learn how the repository can be on a -different machine than your working copy of the sources. +The @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 (and specifying @code{-d} will cause +@file{CVS/Root} to be updated). Of course, for proper +operation they should be two ways of referring to the +same repository. -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. +@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 -* User modules:: The structure of the repository -* Intro administrative files:: Defining modules -* Multiple repositories:: Multiple repositories -* Creating a repository:: Creating a repository -* Remote repositories:: Accessing repositories on remote machines +* Repository files:: What files are stored in the repository +* File permissions:: File permissions +* Attic:: Some files are stored in the Attic @end menu -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node User modules -@section User modules -@cindex User modules -@cindex Repository, user parts +@node Repository files +@subsection Where files are stored within the repository + +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} | @@ -982,32 +1142,43 @@ user-defined modules. @cindex History files @cindex RCS history files -@cindex RCS, CVS uses RCS -The figure above shows the contents of the @samp{tc} -module inside the repository. As you can see all file -names end in @samp{,v}. The files are @dfn{history -files}. They contain, among other things, enough +@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. @sc{cvs} uses the -facilities of @sc{rcs}, a simpler version control -system, to maintain these files. For a full +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)}. -@c -- Use this format for all references to man pages, -@c -- or use something better! - -@menu -* File permissions:: File permissions -@end menu +@cite{rcsfile(5)}, distributed with @sc{rcs}. 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 Setting up +@c -- Move this to @node Creating a repository or similar @cindex Security @cindex File permissions @cindex Group +@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 @@ -1017,15 +1188,62 @@ 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. +@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}). + +@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? +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, though). + +@cindex CVSUMASK +@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. +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 CVSREAD, @ref{Environment variables}). + +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 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 interact? +@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"). @cindex setuid @cindex setgid @@ -1033,6 +1251,285 @@ Since @sc{cvs} was not written to be run setuid, it is unsafe to try to run it setuid. You cannot use the setuid features of @sc{rcs} together with @sc{cvs}. +@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 + +but if it goes in the attic, it would be in + +@example +/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v +@end example + +@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 Working directory storage +@section How data is stored in the 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. + +@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. For +historical reasons it is an absolute pathname, although +it would make more sense for it to be relative to the +root. For example, after the command + +@example +cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc +@end example + +@file{Root} will contain + +@example +:local:/usr/local/cvsroot +@end example + +and @file{Repository} will contain + +@example +/usr/local/cvsroot/yoydyne/tc +@end example + +@cindex Entries file, in CVS directory +@cindex CVS/Entries file +@item Entries +This file lists the files and directories in the +working directory. It is a text file according to the +conventions appropriate for the operating system in +question. +@c That seems like a lose, it makes it impossible (it +@c would seem) to share a working directory via a +@c networked file system between systems with diverse +@c text file conventions. But it seems to be how CVS +@c currently works. +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 + +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 in Universal Time (UT), 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}. +@var{conflict} indicates that there was +a conflict; if it is 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). + +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 + +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. + +@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). + +@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}. + +@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 Checkin.prog file, in CVS directory +@cindex CVS/Checkin.prog file +@cindex Update.prog file, in CVS directory +@cindex CVS/Update.prog file +@item Checkin.prog +@itemx Update.prog +These files store the programs specified by the +@samp{-i} and @samp{-u} options in the modules file, +respectively. + +@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 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 @@ -1041,6 +1538,15 @@ setuid features of @sc{rcs} together with @sc{cvs}. @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 @@ -1062,10 +1568,11 @@ diff gnu/diff tc yoyodyne/tc @end example -The @file{modules} file is line oriented. In its simplest form each -line contains the name of the module, whitespace, and the directory -where the module resides. The directory is a path relative to -@code{$CVSROOT}. The last for lines in the example +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 @@ -1076,6 +1583,7 @@ 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 @@ -1110,12 +1618,25 @@ without sharing any code. All you have to do to have several repositories is to specify the appropriate repository, using the @code{CVSROOT} environment variable, the @samp{-d} option to @sc{cvs}, or (once -you have checked out a working directories) by -simply allowing @sc{cvs} to use the repository that was -used to check out the working directory (@pxref{Repository}). - -Notwithstanding, it can be confusing to have two or -more repositories. +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. The big +disadvantage is that you cannot have a single @sc{cvs} +command recurse into directories which comes from +different repositories. Generally speaking, if you are +thinking of setting up several repositories on the same +machine, you might want to consider using several +directories within the same repository. +@c FIXCVS: the thing about recursing into diverse roots +@c would be nice to fix. But it gets hairy if they are +@c on diverse servers--it isn't clear this is really +@c all that useful. +@c FIXME: Does the FAQ have more about this? I have a +@c dim recollection, but I'm too lazy to check right now. None of the examples in this manual show multiple repositories. @@ -1123,10 +1644,117 @@ repositories. @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @node Creating a repository @section Creating a repository -@c -- Well, how do you do? -See the instructions in the @file{INSTALL} file in the -@sc{cvs} distribution. +@cindex Repository, setting up +@cindex Creating a repository +@cindex Setting up a repository + +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---a server with 32M of memory +or even less can handle a fairly large source tree with +a fair amount of activity. 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 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). Don't worry about CPU +and memory requirements for the clients---any machine +with enough capacity to run the operating system in +question should have little trouble. +@c Stuff about memory duplicates Server requirements +@c to some extent. I'm not sure this is a bad thing, +@c though (one is aimed at people who are looking into +@c this carefully, the other is aimed at people who +@c want a rule of thumb). + +The repository should be accessable +(directly or via a networked file system) from all +machines which want to use @sc{cvs} in server or local +mode; the client machines need not have any access to +it other than via the @sc{cvs} protocol. 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. + +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 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @node Remote repositories @@ -1134,25 +1762,103 @@ See the instructions in the @file{INSTALL} file in the @cindex Repositories, remote @cindex Remote repositories @cindex Client/Server Operation +@cindex server, CVS Your working copy of the sources can be on a -different machine than the repository. Generally, -using a remote repository is just like using a local -one, except that the format of the repository name is: +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 - user@@hostname:/path/to/repository +:@var{method}:@var{user}@@@var{hostname}:/path/to/repository @end example The details of exactly what needs to be set up depend on how you are connecting to the server. +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:. @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 * Kerberos authenticated:: Direct connections with kerberos @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. The +@sc{cvs} 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. + +Resource consumption for the client or the +non-client/server @sc{cvs} is even more modest---any +machine with enough capacity to run the operating system +in question should have little trouble. +@c Probably we could be saying more about this. +@c I would guess for non-client/server CVS in an NFS +@c environment the biggest issues is the network and +@c the NFS server. + @node Connecting via rsh @subsection Connecting with rsh @@ -1163,19 +1869,19 @@ operations, so the remote user host needs to have a user. For example, suppose you are the user @file{mozart} on -the local machine @file{anklet.grunge.com}, and the -server machine is @file{chainsaw.brickyard.com}. On +the local machine @file{toe.grunge.com}, and the +server machine is @file{chainsaw.yard.com}. On chainsaw, put the following line into the file @file{.rhosts} in @file{bach}'s home directory: @example -anklet.grunge.com mozart +toe.grunge.com mozart @end example Then test that @code{rsh} is working with @example -rsh -l bach chainsaw.brickyard.com echo $PATH +rsh -l bach chainsaw.yard.com 'echo $PATH' @end example @cindex CVS_SERVER @@ -1189,22 +1895,63 @@ 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 @code{inetd.conf} or start a @sc{cvs} server daemon. +@cindex :server: +@cindex :ext: +There are two access methods that you use in CVSROOT +for rsh. @code{:server:} specifies an internal rsh +client, which is supported only by some CVS ports. +@code{:ext:} specifies an external rsh program. By +default this is @code{rsh} 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 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. ":ext;rsh=remsh:" +@c 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{chainsaw.brickyard.com}, you are ready to go: +@file{chainsaw.yard.com}, you are ready to go: @example -cvs -d bach@@chainsaw.brickyard.com:/user/local/cvsroot checkout foo +cvs -d :ext:bach@@chainsaw.yard.com:/usr/local/cvsroot checkout foo @end example (The @file{bach@@} can be omitted if the username is the same on both the local and remote hosts.) +@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 @@ -1229,6 +1976,9 @@ some adjustments on both the server and client sides. @cindex Pserver (subcommand) @cindex password server, setting up @cindex authenticating server, setting up +@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 @@ -1247,7 +1997,8 @@ cvs -b /usr/local/bin pserver @end example The @samp{-b} option specifies the directory which contains -the @sc{rcs} binaries on the server. +the @sc{rcs} binaries on the server. You could also use the +@samp{-T} option to specify a temporary directory. If your @code{inetd} wants a symbolic service name instead of a raw port number, then put this in @@ -1264,11 +2015,20 @@ cvspserver 2401/tcp @code{inetd}, or do whatever is necessary to force it to reread its initialization files. +@c FIXME: should be documenting how to troubleshoot +@c this. One strange situation I ran into recently +@c was that if inetd.conf specifies a non-existent +@c cvs (e.g. /usr/local/bin/cvs doesn't exist in +@c the above example), the client says +@c cvs-1.8 [login aborted]: unrecognized auth response from harvey: +@c which is a very unhelpful response (can it be +@c improved? does inetd log somewhere?) + @cindex CVS passwd file -@cindex 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 +security}, for details), a separate @sc{cvs} password file may be used, so people don't compromise their regular passwords when they access the repository. This file is @file{$CVSROOT/CVSROOT/passwd} @@ -1302,16 +2062,59 @@ indicates corresponding valid system usernames). In any case, @sc{cvs} will have no privileges which the (valid) user would not have. +@cindex user aliases + It is possible to ``map'' cvs-specific +usernames onto system usernames (i.e., onto system +login names) in the @file{$CVSROOT/CVSROOT/passwd} file +by appending a colon and the system username after the +password. For example: + +@example +cvs:ULtgRLXo7NRxs:kfogel +generic:1sOp854gDF3DY:spwang +anyone:1sOp854gDF3DY:spwang +@end example + + Thus, someone remotely accessing the repository +on @file{chainsaw.yard.com} with the following +command: + +@example +cvs -d :pserver:cvs@@chainsaw.yard.com:/usr/local/cvsroot checkout foo +@end example + + would end up running the server under the +system identity kfogel, assuming successful +authentication. However, the remote user would not +necessarily need to know kfogel's system password, as +the @file{$CVSROOT/CVSROOT/passwd} file might contain a +different password, used only for @sc{cvs}. And as the +example above indicates, it is permissible to map +multiple cvs usernames onto a single system username. + + This feature is designed to allow people +repository access without full system access (in +particular, see @xref{Read-only access}); however, also +@xref{Password authentication security}. Any sort of +repository access very likely implies a degree of +general system access as well. + 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. +@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?" @node Password authentication client @subsubsection Using the client with password authentication @cindex Login (subcommand) @cindex password client, using @cindex authenticated client, using +@cindex :pserver: Before connecting to the server, the client must @dfn{log in} with the command @code{cvs login}. Logging in verifies a password with the server, and also records @@ -1325,7 +2128,7 @@ argument or the @code{CVSROOT} environment variable. password: @example -cvs -d bach@@chainsaw.brickyard.com:/usr/local/cvsroot login +cvs -d :pserver:bach@@chainsaw.yard.com:/usr/local/cvsroot login CVS password: @end example @@ -1335,11 +2138,10 @@ complaining that the password was incorrect. Once you have logged in, you can force @sc{cvs} to connect directly to the server and authenticate with -the stored password by prefixing the repository with -@samp{:pserver:}: +the stored password: @example -cvs -d :pserver:bach@@chainsaw.brickyard.com:/usr/local/cvsroot checkout foo +cvs -d :pserver:bach@@chainsaw.yard.com:/usr/local/cvsroot checkout foo @end example The @samp{:pserver:} is necessary because without it, @@ -1360,6 +2162,13 @@ trivially encoded to protect them from "innocent" compromise (i.e., inadvertently being seen by a system administrator who happens to look at that file). +@c FIXME: seems to me this needs somewhat more +@c explanation. +@cindex Logout (subcommand) +The password for the currently choosen remote repository +can be removed from the CVS_PASSFILE by using the +@code{cvs logout} command. + The @code{CVS_PASSFILE} environment variable overrides this default. If you use this variable, make sure you set it @emph{before} @code{cvs login} is run. If you @@ -1367,12 +2176,6 @@ were to set it after running @code{cvs login}, then later @sc{cvs} commands would be unable to look up the password for transmission to the server. -@cindex CVS_PASSWORD, environment variable -The @code{CVS_PASSWORD} environment variable overrides -@emph{all} stored passwords. If it is set, @sc{cvs} -will use it for all password-authenticated -connections. - @node Password authentication security @subsubsection Security considerations with password authentication @@ -1384,6 +2187,11 @@ 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 @@ -1393,6 +2201,13 @@ 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). Furthermore, there may be other ways in which having access to @sc{cvs} allows people to gain more general access to the system; noone has done a careful audit. @@ -1408,25 +2223,31 @@ security, get Kerberos. @subsection Direct connection with kerberos @cindex kerberos +@cindex :kserver: The main disadvantage of using rsh is that all the data needs to pass through additional programs, so it may be slower. So if you have kerberos installed you can connect via a direct @sc{tcp} connection, -authenticating with kerberos (note that the data -transmitted is @emph{not} encrypted). +authenticating with kerberos. 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 @code{inetd.conf} on the server machine to run @code{cvs kserver}. The client uses port 1999 by default; if you want to use another port specify it in the @code{CVS_CLIENT_PORT} environment -variable on the client. Set @code{CVS_CLIENT_PORT} to -@samp{-1} to force an rsh connection. +variable on the client. @cindex kinit When you want to use @sc{cvs}, get a ticket in the @@ -1435,11 +2256,139 @@ which allows you to log into the server machine. Then you are ready to go: @example -cvs -d chainsaw.brickyard.com:/user/local/cvsroot checkout foo +cvs -d :kserver:chainsaw.yard.com:/user/local/cvsroot checkout foo @end example -If @sc{cvs} fails to connect, it will fall back to -trying rsh. +Previous versions of @sc{cvs} would fall back to a +connection via rsh; this version will not do so. + +@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}). +However, note that read-only access does not repeal the +existing security considerations in @xref{Password +authentication 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 + + (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{TMPDIR} environment variable +(@pxref{Environment variables}), the @samp{-T} global +option (@pxref{Global options}), 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 @@ -1448,12 +2397,14 @@ trying rsh. @cindex Creating a project @comment --moduledb-- -Since @sc{cvs} 1.x is bad at renaming files and moving -them between directories, the first thing you do when -you start a new project should be to think through your -file organization. It is not impossible---just -awkward---to rename or move files. -@xref{Moving files}. +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. @@ -1476,12 +2427,12 @@ be done in a couple of different ways. where files already exists. * From other version control systems:: Old projects where you want to preserve history from another system. -* From scratch:: Creating a module from scratch. +* From scratch:: Creating a directory tree from scratch. @end menu @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . @node From files -@subsection Creating a module from a number of 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 @@ -1489,12 +2440,12 @@ projects that can be put under @sc{cvs} control. In these cases the easiest way is to use the @code{import} command. An example is probably the easiest way to explain how to use it. If the files you want to install in -@sc{cvs} reside in @file{@var{dir}}, and you want them to appear in the -repository as @file{$CVSROOT/yoyodyne/@var{dir}}, you can do this: +@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{dir} -$ cvs import -m "Imported sources" yoyodyne/@var{dir} yoyo start +$ 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} @@ -1507,12 +2458,15 @@ 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 .. $ mv @var{dir} @var{dir}.orig $ cvs checkout yoyodyne/@var{dir} # @r{Explanation below} -$ ls -R yoyodyne +$ diff -r @var{dir}.orig yoyodyne/@var{dir} $ rm -r @var{dir}.orig @end example @@ -1532,6 +2486,10 @@ It is a good idea to check that the permissions 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 @@ -1567,6 +2525,16 @@ working directory. @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 @@ -1584,11 +2552,33 @@ Note: you must run it on a machine which has both else in contrib it is unsupported (your mileage may vary). @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 module 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: @@ -1633,8 +2623,8 @@ In simple cases these steps are sufficient to define a module. Get a working copy of the modules file. @example -$ cvs checkout modules -$ cd modules +$ cvs checkout CVSROOT/modules +$ cd CVSROOT @end example @item @@ -1659,7 +2649,7 @@ Release the modules module. @example $ cd .. -$ cvs release -d modules +$ cvs release -d CVSROOT @end example @end enumerate @@ -1671,36 +2661,128 @@ $ cvs release -d modules @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. Some other version -control systems (including @sc{rcs} and @sc{sccs}) -try to solve that particular problem by introducing -@dfn{file locking}, so that only one person can edit -each file at a time. Unfortunately, file locking can -be very counter-productive. If two persons want -to edit different parts of a file, there may be no -reason to prevent either of them from doing so. - -@sc{cvs} does not use file locking. Instead, it allows many -people to edit their own @dfn{working copy} of a file +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, and explained in this chapter. - -There are many ways to organize a team of developers. -@sc{cvs} does not try to enforce a certain -organization. It is a tool that can be used in several -ways. It is often useful to inform the group of -commits you have done. @sc{cvs} has several ways of -automating that process. @xref{Informing others}. -@xref{Revision management}, for more tips on how to use -@sc{cvs}. +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 communcation, 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 reimplement 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 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). + + +@end ignore @menu * File status:: A file can be in several states @@ -1709,6 +2791,7 @@ automating that process. @xref{Informing others}. * 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 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -1716,35 +2799,151 @@ automating that process. @xref{Informing others}. @section File status @cindex File status @cindex Status of a file -@cindex Four states of a file - -After you have checked out a file out from @sc{cvs}, it is in -one of these four states: +@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. -@c -- The above is not always true if branching is used. - -@item Locally modified -@cindex Locally modified +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 Needing update -@cindex Needing update -Someone else has committed a newer revision to the repository. - -@item Needing merge -@cindex Needing merge -Someone else have committed a newer revision to the repository, and you +@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. -@c -- What about "added" "removed" and so on? + +@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 -You can use the @code{status} command to find out the status of a given -file. @xref{status}. +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 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 @@ -1889,11 +3088,11 @@ int main(int argc, gencode(); else fprintf(stderr, "No code generated.\n"); -<<<<<<< driver.c +@asis{}<<<<<<< driver.c exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); -======= +@asis{}======= exit(!!nerr); ->>>>>>> 1.6 +@asis{}>>>>>>> 1.6 @} @end example @@ -1947,6 +3146,23 @@ 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, and must also +insure that the file contains no conflict markers. If +your file legitimately contains conflict markers (that +is, occurrences of @samp{>>>>>>> } at the start of a +line that don't mark a conflict), then @sc{cvs} has +trouble handling this and you need to start hacking on +the @code{CVS/Entries} file or other such workarounds. +@c FIXME: 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 @@ -1974,6 +3190,8 @@ newsgroup. @section Several developers simultaneously attempting to run CVS @cindex locks, cvs +@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: @@ -1987,15 +3205,16 @@ if it still needs to wait. If a lock seems to stick around for an undue amount of time, find the person holding the lock and ask them about the cvs command they are running. If they aren't running a cvs -command, look for and remove files starting with -@file{#cvs.tfl}, @file{#cvs.rfl}, or @file{#cvs.wfl} -from the repository. +command, look in the repository directory mentioned in +the message and remove files which they own whose names +start with @file{#cvs.tfl}, @file{#cvs.rfl}, or +@file{#cvs.wfl}. Note that these locks are to protect @sc{cvs}'s internal data structures and have no relationship to -the word @dfn{lock} in the sense used by @sc{rcs}--a -way to prevent other developers from working on a -particular file. +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 @@ -2003,6 +3222,17 @@ 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 @example @@ -2049,6 +3279,19 @@ 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 @@ -2078,8 +3321,9 @@ To enable the watch features, you first specify that certain files are to be watched. @cindex watch on (subcommand) -@deffn Command {cvs watch on} [@code{-l}] files @dots{} +@deffn Command {cvs watch on} [@code{-lR}] files @dots{} +@cindex read-only files, and watches Specify that developers should run @code{cvs edit} before editing @var{files}. CVS will create working copies of @var{files} read-only, to remind developers @@ -2093,18 +3337,20 @@ 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{-l}] files @dots{} +@deffn Command {cvs watch off} [@code{-lR}] files @dots{} Do not provide notification about work on @var{files}. CVS will create working copies of @var{files} read-write. -The @var{files} and @code{-l} arguments are processed as for @code{cvs +The @var{files} and options are processed as for @code{cvs watch on}. @end deffn @@ -2120,7 +3366,7 @@ watch on}, so that developers use the @code{cvs edit} command. @cindex watch add (subcommand) -@deffn Command {cvs watch add} [@code{-a} action] [@code{-l}] files @dots{} +@deffn Command {cvs watch add} [@code{-a} action] [@code{-lR}] files @dots{} Add the current user to the list of people to receive notification of work done on @var{files}. @@ -2154,14 +3400,14 @@ described below.) The @code{-a} option may appear more than once, or not at all. If omitted, the action defaults to @code{all}. -The @var{files} and @code{-l} option are processed as for the +The @var{files} and options are processed as for the @code{cvs watch} commands. @end deffn @cindex watch remove (subcommand) -@deffn Command {cvs watch remove} [@code{-a} action] [@code{-l}] files @dots{} +@deffn Command {cvs watch remove} [@code{-a} action] [@code{-lR}] 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 @@ -2169,11 +3415,32 @@ 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, passing it -the user to receive the notification and the user who -is taking the action which results in notification. -Normally @file{notify} will just send an email message. +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 ocurrence 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 + +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 @@ -2188,13 +3455,49 @@ 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. +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} [options] files @dots{} @@ -2209,7 +3512,7 @@ user on @var{files}; CVS will remove the watch when @var{files} are @code{unedit}ed or @code{commit}ted. If the user does not wish to receive notifications, she should specify @code{-a none}. -The @var{files} and @code{-l} option are processed as for the @code{cvs +The @var{files} and options are processed as for the @code{cvs watch} commands. @end deffn @@ -2222,7 +3525,9 @@ your changes, or not to make any changes, you can use the @code{cvs unedit} command. @cindex unedit (subcommand) -@deffn Command {cvs unedit} [@code{-l}] files @dots{} +@cindex abandoning work +@cindex reverting to repository version +@deffn Command {cvs unedit} [@code{-lR}] files @dots{} Abandon work on the working files @var{files}, and revert them to the repository versions on which they are based. CVS makes those @@ -2230,9 +3535,18 @@ repository versions on which they are based. CVS makes those @code{cvs watch on}. CVS notifies users who have requested @code{unedit} notification for any of @var{files}. -The @var{files} and @code{-l} option are processed as for the +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 to remove the file and then use +@code{cvs update} to get a new copy. The meaning is +not precisely the same; removing and updating 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 @@ -2245,26 +3559,26 @@ successful @sc{cvs} command. @subsection Information about who is watching and editing @cindex watchers (subcommand) -@deffn Command {cvs watchers} [@code{-l}] files @dots{} +@deffn Command {cvs watchers} [@code{-lR}] files @dots{} List the users currently watching changes to @var{files}. The report includes the files being watched, and the mail address of each watcher. -The @var{files} and @code{-l} arguments are processed as for the +The @var{files} and options are processed as for the @code{cvs watch} commands. @end deffn @cindex editors (subcommand) -@deffn Command {cvs editors} [@code{-l}] files @dots{} +@deffn Command {cvs editors} [@code{-lR}] files @dots{} List the users currently working on @var{files}. The report includes the mail address of each user, the time when the user began working with the file, and the host and path of the working directory containing the file. -The @var{files} and @code{-l} arguments are processed as for the +The @var{files} and options are processed as for the @code{cvs watch} commands. @end deffn @@ -2277,10 +3591,12 @@ 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 +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 +cvs update: cannot open CVS/Entries for reading: +No such file or directory @end example and your operation will likely be aborted. To use the @@ -2291,31 +3607,264 @@ you cannot upgrade, use the @code{watch off} 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 Branches -@chapter Branches +@node Revisions and branches +@chapter Revisions and branches @cindex Branches @cindex Main trunk and branches @cindex Revision tree, making branches -So far, all revisions shown in this manual have been on -the @dfn{main trunk} -of the revision tree, i.e., all revision numbers -have been of the form @var{x}.@var{y}. One useful -feature, especially when maintaining several releases -of a software product at once, is the ability to make -branches on the revision tree. @dfn{Tags}, symbolic -names for revisions, will also be -introduced in this chapter. +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. + +Another useful feature, especially when maintaining +several releases of a software product at once, is the +ability to make branches on the revision tree. +@c FIXME: probably want another sentence or two, very +@c briefly motivating branches. @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 * Branches motivation:: What branches are good for * Creating a branch:: Creating a branch * Sticky tags:: Sticky tags +* Magic branch numbers:: Magic branch numbers @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 + +@c Probably should move the following down a few +@c sections, until after "branch motivation". +@sc{cvs} is not limited to linear development. The +@dfn{revision tree} can be split into @dfn{branches}, +where each branch is a self-maintained line of +development. Changes made on one branch can easily be +moved back to the main trunk. + +Each branch has a @dfn{branch number}, consisting of an +odd number of period-separated decimal integers. The +branch number is created by appending an integer to the +revision number where the corresponding branch forked +off. Having branch numbers allows more than one branch +to be forked off from a certain revision. + +@need 3500 +All revisions on a branch have revision numbers formed +by appending an ordinal number to the branch number. +The following figure illustrates branching with an +example. + +@example +@group + +-------------+ + Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! + / +-------------+ + / + / + +---------+ +---------+ +---------+ +Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! + / +---------+ +---------+ +---------+ + / + / ++-----+ +-----+ +-----+ +-----+ +-----+ +! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk ++-----+ +-----+ +-----+ +-----+ +-----+ + ! + ! + ! +---------+ +---------+ +---------+ +Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! + +---------+ +---------+ +---------+ + +@end group +@end example + +@c -- However, at least for me the figure is not enough. I suggest more +@c -- text to accompany it. "A picture is worth a thousand words", so you +@c -- have to make sure the reader notices the couple of hundred words +@c -- *you* had in mind more than the others! + +@c -- Why an even number of segments? This section implies that this is +@c -- how the main trunk is distinguished from branch roots, but you never +@c -- explicitly say that this is the purpose of the [by itself rather +@c -- surprising] restriction to an even number of segments. + +The exact details of how the branch number is +constructed is not something you normally need to be +concerned about, but here is how it works: When +@sc{cvs} creates a branch number it picks the first +unused even integer, starting with 2. So when you want +to create a branch from revision 6.4 it will be +numbered 6.4.2. All branch numbers ending in a zero +(such as 6.4.0) are used internally by @sc{cvs} +(@pxref{Magic branch numbers}). The branch 1.1.1 has a +special meaning. @xref{Tracking sources}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Versions revisions releases +@section Versions, revisions and releases +@cindex Revisions, versions and releases +@cindex Versions, revisions and releases +@cindex Releases, revisions and versions + +A file can have several versions, as described above. +Likewise, a software product can have several versions. +A software product is often given a version number such +as @samp{4.1.1}. + +Versions in the first sense are called @dfn{revisions} +in this document, and versions in the second sense are +called @dfn{releases}. To avoid confusion, the word +@dfn{version} is almost never used in this document. + +@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}. + +@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{Revisions and branches}). + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @node Tags @section Tags--Symbolic revisions @cindex Tags @@ -2351,17 +3900,47 @@ rcsutil.c 5.10 You can use the @code{tag} command to give a symbolic name to a certain revision of a file. You can use the @samp{-v} flag to the @code{status} command to see all tags that a file has, and -which revision numbers they represent. Tag names can +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 contain characters such as @samp{%} or -@samp{=}, rather than being named analogously 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 FIXME: is the above list of valid characters in tag -@c names complete? +@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 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 +taginfo file (@pxref{user-defined logging}). +@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 @@ -2379,7 +3958,7 @@ $ cvs status -v backend.c File: backend.c Status: Up-to-date Version: 1.4 Tue Dec 1 14:39:01 1992 - RCS Version: 1.4 /usr/local/cvsroot/yoyodyne/tc/backend.c,v + RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v Sticky Tag: (none) Sticky Date: (none) Sticky Options: (none) @@ -2506,6 +4085,13 @@ does not require that you have a working copy of the module. @xref{rtag}. (You can also use the @code{tag} command; @pxref{tag}). +@c Why does this example use -r? That seems like a +@c confusing thing to do in an example where we are +@c introducing branches. One user thought it was +@c a mandatory part of creating a branch for example. +@c And we are not sufficiently +@c "step by step" in terms of explaining +@c what argument one should give to -r. @example $ cvs rtag -b -r release-1-0 release-1-0-patches tc @end example @@ -2529,7 +4115,7 @@ $ cvs status -v driver.c backend.c File: driver.c Status: Up-to-date Version: 1.7 Sat Dec 5 18:25:54 1992 - RCS Version: 1.7 /usr/local/cvsroot/yoyodyne/tc/driver.c,v + RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v Sticky Tag: release-1-0-patches (branch: 1.7.2) Sticky Date: (none) Sticky Options: (none) @@ -2542,7 +4128,7 @@ File: driver.c Status: Up-to-date File: backend.c Status: Up-to-date Version: 1.4 Tue Dec 1 14:39:01 1992 - RCS Version: 1.4 /usr/local/cvsroot/yoyodyne/tc/backend.c,v + RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v Sticky Tag: release-1-0-patches (branch: 1.4.2) Sticky Date: (none) Sticky Options: (none) @@ -2560,7 +4146,7 @@ number is created by adding a digit at the tail of the revision number it is based on. (If @samp{release-1-0} corresponds to revision 1.4, the branch's revision number will be 1.4.2. For obscure reasons @sc{cvs} always gives branches even numbers, starting at 2. -@xref{Revision numbers}). +@xref{Revision numbers}.). @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @node Sticky tags @@ -2596,7 +4182,7 @@ $ cvs status -v driver.c File: driver.c Status: Up-to-date Version: 1.7.2.1 Sat Dec 5 19:35:03 1992 - RCS Version: 1.7.2.1 /usr/local/cvsroot/yoyodyne/tc/driver.c,v + RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v Sticky Tag: release-1-0-patches (branch: 1.7.2) Sticky Date: (none) Sticky Options: (none) @@ -2616,14 +4202,18 @@ you delete them with @samp{cvs update -A}. The the head of the trunk, and forgets any sticky tags, dates, or options. -@c Is the fact that CVS works this way a bug or a -@c feature? If a feature, describe how you would use -@c it to do something useful. -Sticky tags are not just for branches. If you check -out a certain revision (such as 1.4) it will also -become sticky. Subsequent @samp{cvs update} will not -retrieve the latest revision until you reset the tag -with @samp{cvs update -A}. Likewise, use of the +@cindex sticky date +Sticky tags are not just for branches. 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} 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. @@ -2648,7 +4238,7 @@ RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v VERS: 1.1 *************** $ cvs add file1 -cvs add: version 1.2 of `file1' will be resurrected +cvs add: re-adding file file1 (in place of dead revision 1.2) cvs add: use 'cvs commit' to add this file permanently $ cvs commit -m test Checking in file1; @@ -2658,6 +4248,73 @@ done $ @end example +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Magic branch numbers +@section Magic branch numbers + +@c Want xref to here from "log" and "admin"? + +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.3 becomes +1.2.0.3, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so +on). + +@sc{cvs} does a pretty good job at hiding these so +called magic branches, but in 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 @chapter Merging @@ -2676,6 +4333,7 @@ copy the changes onto another branch. * 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? @end menu @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -2745,7 +4403,7 @@ like this: @example +-----+ +-----+ +-----+ +-----+ +-----+ -! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk +! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk +-----+ +-----+ +-----+ +-----+ +-----+ ! * ! * @@ -2763,7 +4421,7 @@ Now suppose that development continues on the @example +-----+ +-----+ +-----+ +-----+ +-----+ -! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk +! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk +-----+ +-----+ +-----+ +-----+ +-----+ ! * ! * @@ -2833,6 +4491,31 @@ that make up a module. You almost always use symbolic tags rather than revision numbers when operating on multiple files. +@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 + @c --------------------------------------------------------------------- @node Recursive behavior @chapter Recursive behavior @@ -2878,8 +4561,11 @@ following is true: @itemize @bullet @item -@samp{cvs update testing} is equivalent to @samp{cvs -update testing/testpgm.t testing/test2.t} +@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 @@ -2899,6 +4585,8 @@ for most of the @sc{cvs} subcommands, not only the 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} @@ -2906,63 +4594,138 @@ $ cvs update -l # @r{Don't update files in subdirectories} @c --------------------------------------------------------------------- @node Adding files -@chapter Adding files to a module +@chapter Adding files to a directory @cindex Adding files -To add a new file to a module, follow these steps. +To add a new file to a directory, follow these steps. @itemize @bullet @item -You must have a working copy of the module. +You must have a working copy of the directory. @xref{Getting the source}. @item -Create the new file inside your working copy of the module. +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. +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. - -@item -If the file contains binary data it might be necessary -to change the default keyword substitution. -@xref{Keyword substitution}. @xref{admin examples}. @end itemize You can also use the @code{add} command to add a new -directory inside a module. +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 cannot even type @samp{cvs add foo/bar}! Instead, you have to +@c FIXCVS: This is, of course, not a feature. It is +@c just that noone has gotten around to fixing "cvs add +@c foo/bar". @example $ cd foo $ cvs add bar @end example -@xref{add}, for a more complete description of the @code{add} -command. +@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{Revisions and branches}). 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 -@chapter Removing files from a module +@chapter Removing files @cindex Removing files @cindex Deleting files +@c FIXME: this node wants to be split into several +@c smaller nodes. Probably would fit well with merging +@c this chapter with "adding files" and the others, as +@c suggested at the top-level menu (death support could +@c be its own section, for example, as could the +@c various bits about undoing mistakes in adding and +@c removing). Modules change. New files are added, and old files disappear. Still, you want to be able to retrieve an -exact copy of old releases of the module. +exact copy of old releases. -Here is what you can do to remove a file from a module, +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}, @@ -2973,7 +4736,7 @@ course not be able to retrieve the file as it was immediately before you deleted it. @item -Remove the file from your working copy of the module. +Remove the file from your working copy of the directory. You can for instance use @code{rm}. @item @@ -2985,6 +4748,15 @@ 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 @@ -2993,23 +4765,24 @@ name later. CVS will correctly create or not create the file, based on the @samp{-r} and @samp{-D} options specified to @code{checkout} or @code{update}. +@c FIXME: This style seems to clash with how we +@c document things in general. @cindex Remove (subcommand) -@deffn Command {cvs remove} [@code{-lR}] files @dots{} +@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. The @samp{-R} option -(the default) specifies that it will recurse into -subdirectories; @samp{-l} specifies that it will not. +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 +$ rm *.c $ cvs remove cvs remove: Removing . cvs remove: scheduling a.c for removal @@ -3020,9 +4793,40 @@ cvs commit: Examining . cvs commit: Committing . @end example -If you change your mind you can easily resurrect the -file before you commit it, using the @code{add} -command. +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 @@ -3047,12 +4851,51 @@ 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{Revisions and branches}). You can +later merge the removals to another branch if you want +(@pxref{Merging adds and removals}). + +@node Removing directories +@chapter 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. Then specify the @samp{-P} option to +@code{cvs update}, @code{cvs checkout}, or @code{cvs +export}, which will cause @sc{cvs} to remove empty +directories from working 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} and @code{export}. 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 Tracking sources @chapter Tracking third-party sources @cindex Third-party sources @cindex Tracking sources +@c FIXME: Need discussion of added and removed files. 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 @@ -3083,6 +4926,8 @@ revision. @menu * First import:: Importing a module for the first time * Update imports:: Updating a module with the import command +* Reverting local changes:: Reverting a module to the latest vendor release +* Binary files in imports:: Binary files require special handling @end menu @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -3090,26 +4935,37 @@ revision. @section Importing a module 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---@xref{import options}). The +@var{branch}} flag---@xref{import options}.). 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 use @code{wdiff} (a variant of @code{diff} -that ignores changes that only involve whitespace), and -are going to make private modifications that you want -to be able to use even when new releases are made in -the future. You start by importing the source to your -repository: +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 -$ tar xfz wdiff-0.04.tar.gz $ cd wdiff-0.04 $ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04 @end example @@ -3117,6 +4973,7 @@ $ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04 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 @@ -3138,6 +4995,10 @@ 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 @@ -3161,6 +5022,32 @@ $ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff @noindent In this case, the two above commands are equivalent. +@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 -bWDIFF . +@end example + +@noindent +You must specify the @samp{-bWDIFF} 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}. + @c --------------------------------------------------------------------- @node Moving files @chapter Moving and renaming files @@ -3171,7 +5058,7 @@ In this case, the two above commands are equivalent. 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}). +directory is even harder. @xref{Moving directories}.). The examples below assume that the file @var{old} is renamed to @var{new}. @@ -3186,11 +5073,27 @@ The examples below assume that the file @var{old} is renamed to @node Outside @section 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. (Both @var{old} and @var{new} could -contain relative paths, for example @file{foo/bar.c}). +@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} @@ -3208,8 +5111,9 @@ portion of the history you are accessing. For example, time of the rename. When @var{new} is committed its revision numbers will -start at 1.0 again, so if that bothers you, use the -@samp{-r rev} option to commit (@pxref{commit options}) +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 @@ -3271,9 +5175,9 @@ $ cvs remove @var{old} $ cvs commit @var{old} # @r{Remove all tags from @var{new}} $ cvs update @var{new} -$ cvs log @var{new} # @r{Remember the tag names} -$ cvs tag -d @var{tag1} -$ cvs tag -d @var{tag2} +$ 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 @@ -3305,10 +5209,18 @@ Disadvantages: @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 --------------------------------------------------------------------- @@ -3318,16 +5230,14 @@ numbers will start at 1.0 again. @cindex Renaming directories @cindex Directories, moving -If you want to be able to retrieve old versions of the -module, you must move each file in the directory -with the @sc{cvs} commands. @xref{Outside}. The old, empty -directory will remain inside the repository, but it -will not appear in your workspace when you check out -the module in the future. -@c -- rephrase +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 rename or delete a directory, you -can do it like this: +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 @@ -3430,6 +5340,8 @@ 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 @@ -3463,6 +5375,63 @@ You can use the history file (@pxref{history file}) to log various @sc{cvs} actions. To retrieve the information from the history file, use the @code{cvs history} command (@pxref{history}). +@c +@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 @@ -3517,13 +5486,11 @@ aborted. @section Annotate command @cindex annotate (subcommand) -@deffn Command {cvs annotate} [@code{-l}] files @dots{} +@deffn Command {cvs annotate} [@code{-flR}] [@code{-r rev}|@code{-D date}] files @dots{} For each file in @var{files}, print the head revision of the trunk, together with information on the last -modification for each line. The @code{-l} option means -to process the local directory only, not to recurse -(@pxref{Common options}). For example: +modification for each line. For example: @example $ cvs annotate ssfile @@ -3544,6 +5511,16 @@ or replaced; you need to use @code{cvs diff} for that @end deffn +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 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 Keyword substitution @chapter Keyword substitution @@ -3609,6 +5586,14 @@ will normally never be locked when you use @sc{cvs}. Same as @code{$@asis{Header}$}, except that the @sc{rcs} filename is without a path. +@cindex Name keyword +@item $@asis{Name}$ +Tag name used to check out this file. +@c FIXME: should supply an example (e.g. "if you use +@c "cvs update -r foo" then Name expands to "foo"). Also +@c should add Name to testsuite (best way to ensure +@c that the example is correct!) + @cindex Locker keyword @item $@asis{Locker}$ The login name of the user who locked the revision @@ -3856,6 +5841,10 @@ 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. If you are using @@ -3885,6 +5874,7 @@ $ cvs add -m"A test file" kotest $ cvs ci -m"First checkin; contains a keyword" kotest $ cvs admin -kb kotest $ cvs update -A kotest +$ cvs commit -m "make it binary" kotest # @r{For non-unix systems} @end example When you check in the file @file{kotest} the keywords @@ -3894,7 +5884,213 @@ admin -kb} command sets the default keyword substitution method for this file, but it does not alter the working copy of the file that you have. The easiest way to get the unexpanded version of -@file{kotest} is @code{cvs update -A}. +@file{kotest} is @code{cvs update -A}. If you need to +cope with line endings (that is, you are using a +@sc{cvs} client 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. +@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" + +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 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 are 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 gtornblo@senet.abb.se (spicm and related tools), +@c but as far as I know +@c noone 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.io.org/~pzi/heading.html; +@c ftp://ftp.interlog.com/pub/unix/mk is out of date). But I'm not sure +@c there is any point in mentioning them here unless they +@c can work with CVS. + +@node Compatibility +@chapter 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 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 bugfixes, 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 Revision management @@ -3949,35 +6145,35 @@ too regimented and thus counter-productive to the real goal, which is to get software written. @c --------------------------------------------------------------------- -@node Invoking CVS -@appendix Reference manual for CVS commands -@cindex Command reference -@cindex Reference, commands -@cindex Invoking CVS - -This appendix describes how to invoke @sc{cvs}, and -describes in detail those subcommands of @sc{cvs} which -are not fully described elsewhere. To look up a -particular subcommand, see @ref{Index}. +@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. @menu * Structure:: Overall structure of CVS commands * ~/.cvsrc:: Default options with the ~/.csvrc file * Global options:: Options you give to the left of cvs_command * Common options:: Options you give to the right of cvs_command -* add:: Add a new file/directory to the repository * admin:: Administration front end for rcs * checkout:: Checkout sources for editing * commit:: Check files into the repository -* diff:: Run diffs between revisions +* 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:: Print out 'rlog' information for files +* log:: Show log messages for files * rdiff:: 'patch' format diffs between releases * release:: Indicate that a Module is no longer in use * rtag:: Add a tag to a module -* status:: Status info on the revisions * tag:: Add a tag to checked out version * update:: Bring work tree in sync with repository @end menu @@ -3990,10 +6186,7 @@ particular subcommand, see @ref{Index}. @cindex Command structure @cindex Format of CVS commands -The first release of @sc{cvs} consisted of a number of shell-scripts. -Today @sc{cvs} is implemented as a single program that is a front-end -to @sc{rcs} and @code{diff}. The overall format of all -@sc{cvs} commands is: +The overall format of all @sc{cvs} commands is: @example cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] @@ -4001,7 +6194,7 @@ cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] @table @code @item cvs -The program that is a front-end to @sc{rcs}. +The name of the @sc{cvs} program. @item cvs_options Some options that affect all sub-commands of @sc{cvs}. These are @@ -4113,6 +6306,14 @@ located. Overrides the setting of the @code{$RCSBIN} environment variable and any precompiled directory. This parameter should be specified as an absolute pathname. +@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. + @cindex CVSROOT, overriding @cindex Overriding CVSROOT @item -d @var{cvs_root_directory} @@ -4124,7 +6325,9 @@ the @code{$CVSROOT} environment variable. @xref{Repository}. @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. +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 @@ -4133,16 +6336,19 @@ non-orthogonality of the @sc{cvs} option set. For example, the @samp{cvs log} option @samp{-N} (turn off display of tag names) does not have a corresponding option to turn the display on. So if you have -@samp{-N} in the @file{~/.cvsrc} entry for @samp{diff}, +@samp{-N} in the @file{~/.cvsrc} entry for @samp{log}, you may need to use @samp{-f} to show the tag names. -@footnote{Yes, this really should be fixed, and it's -being worked on} @item -H +@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 a summary of all the -commands available. +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... @item -l Do not log the cvs_command in the command history (but execute it @@ -4163,7 +6369,7 @@ Cause the command to be somewhat quiet; informational messages, such as reports of recursion through subdirectories, are suppressed. -@cindex Read-only files +@cindex read-only files, and -r @item -r Make new working files files read-only. Same effect as if the @code{$CVSREAD} environment variable is set @@ -4181,6 +6387,7 @@ Trace program execution; display messages showing the steps of potential impact of an unfamiliar command. @item -v +@item --version Display version and copyright information for @sc{cvs}. @cindex CVSREAD, overriding @@ -4191,6 +6398,15 @@ setting of the @code{$CVSREAD} environment variable. Files are created read-write by default, unless @code{$CVSREAD} is set or @samp{-r} is given. +@item -x +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 +Kerberos connection (@pxref{Kerberos 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} Set the compression level. Only has an effect on the @sc{cvs} client. @@ -4233,30 +6449,152 @@ file using @samp{-D}, @sc{cvs} records the date you specified, so that further updates in the same directory will use the same date (for more information on sticky tags/dates, @pxref{Sticky tags}). -A wide variety of date formats are supported by the underlying -@sc{rcs} facilities, similar to those described in co(1), but not -exactly the same. The @var{date_spec} is interpreted as being -in the local timezone, unless a specific timezone is specified. -Examples of valid date specifications include: - -@example - 1 month ago - 2 hours ago - 400000 seconds ago - last year - last Monday - yesterday - a fortnight ago - 3/31/92 10:00:07 PST - January 23, 1987 10:05pm - 22:00 GMT -@end example - @samp{-D} is available with the @code{checkout}, @code{diff}, @code{export}, @code{history}, @code{rdiff}, @code{rtag}, and @code{update} commands. (The @code{history} command uses this option in a -slightly different way; @pxref{history options}). +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. + +For more details about ISO8601 dates, see: + +@example +http://www.ft.uni-erlangen.de/~mskuhn/iso-time.html +@end example +@c Perhaps we want to also cite other sources in +@c case that page goes away. For example: +@c http://www.saqqara.demon.co.uk/datefmt.htm + +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 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 @@ -4277,17 +6615,14 @@ tag or date. (The most recent revision of the file will be used). @need 800 -@samp{-f} is available with these commands: @code{checkout}, -@code{export}, @code{rdiff}, @code{rtag}, and @code{update}. +@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} command also has a @samp{-f} option, but it has a different behavior for that command. @xref{commit options}. -@item -H -Help; describe the options available for this command. This is -the only option supported for all @sc{cvs} commands. - @item -k @var{kflag} Alter the default @sc{rcs} processing of keywords. @xref{Keyword substitution}, for the meaning of @@ -4300,7 +6635,7 @@ file, and continues to use it with future update commands on the same file until you specify otherwise. The @samp{-k} option is available with the @code{add}, -@code{checkout}, @code{diff} and +@code{checkout}, @code{diff}, @code{import} and @code{update} commands. @item -l @@ -4311,10 +6646,11 @@ recursing through subdirectories. as the overall @samp{cvs -l} option, which you can specify to the left of a cvs command! -Available with the following commands: @code{checkout}, -@code{commit}, @code{diff}, @code{export}, @code{log}, -@code{remove}, @code{rdiff}, @code{rtag}, -@code{status}, @code{tag}, and @code{update}. +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 @@ -4337,28 +6673,21 @@ Available with the @code{checkout}, @code{commit}, @code{export}, and @code{rtag} commands. @item -P -Prune (remove) directories that are empty after being updated, on -@code{checkout}, or @code{update}. Normally, an empty directory -(one that is void of revision-controlled files) is left alone. -Specifying @samp{-P} will cause these directories to be silently -removed from your checked-out sources. This does not remove the -directory from the repository, only from your checked out copy. -Note that this option is implied by the @samp{-r} or @samp{-D} -options of @code{checkout} and @code{export}. -@c -- implied-- +Prune empty directories. See @xref{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 -W -Specify file names that should be filtered. You can -use this option repeatedly. The spec can be a file -name pattern of the same type that you can specify in -the @file{.cvswrappers} file. -Avaliable with the following commands: @code{import}, -and @code{update}. +@item -R +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} Use the revision specified by the @var{tag} argument instead of the @@ -4368,7 +6697,28 @@ always available: @samp{HEAD} refers to the most recent version available in the repository, and @samp{BASE} refers to the revision you last checked out into the current working directory. -The tag specification is sticky when you use this option +@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 if there is a branch sticky tag, and (c) the +@c same as BASE if there is a non-branch sticky tag. (c) +@c would appear to be strange, maybe accidental, and so there would +@c presumably be +@c little problem changing it. (b) is ugly as it differs +@c from what HEAD means for other commands, but people +@c might be used to it (note a change in NEWS? Or provide +@c advance warning of it changing?) and possible useful +@c (could be fixed by a new tag ".bhead" which would mean +@c the head of the appropriate branch). This +@c should be investigated, test cases written, and +@c documented (but HEAD should mean the same thing for all +@c CVS commands, so I don't know if we should be +@c documenting the current "cvs diff" behavior). + +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 @@ -4388,128 +6738,16 @@ which you can specify to the left of a cvs command! @code{diff}, @code{history}, @code{export}, @code{rdiff}, @code{rtag}, and @code{update} commands. -@end table - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node add -@appendixsec add---Add a new file/directory to the repository -@cindex Add (subcommand) - -@itemize @bullet -@item -Synopsis: add [-k kflag] [-m 'message'] files@dots{} -@item -Requires: repository, working directory. -@item -Changes: working directory. -@item -Synonym: new -@end itemize - -Use the @code{add} command to create a new file or directory in the -source repository. The files or directories specified with @code{add} -must already exist in the current directory (which must have been -created with the @code{checkout} command). To add a whole new directory -hierarchy to the source repository (for example, files received -from a third-party vendor), use the @code{import} command -instead. @xref{import}. - -If the argument to @code{add} refers to an immediate -sub-directory, the directory is created at the correct place in -the source repository, and the necessary @sc{cvs} administration -files are created in your working directory. If the directory -already exists in the source repository, @code{add} still creates -the administration files in your version of the directory. -This allows you to use @code{add} to add a particular directory -to your private sources even if someone else created that -directory after your checkout of the sources. You can do the -following: - -@example -$ mkdir new_directory -$ cvs add new_directory -$ cvs update new_directory -@end example - -An alternate approach using @code{update} might be: - -@example -$ cvs update -d new_directory -@end example - -(To add any available new directories to your working directory, -it's probably simpler to use @code{checkout} (@pxref{checkout}) -or @samp{update -d} (@pxref{update})). - -The added files are not placed in the source repository until you -use @code{commit} to make the change permanent. Doing an -@code{add} on a file that was removed with the @code{remove} -command will resurrect the file, unless a @code{commit} command -intervened. -@xref{Removing files}, for an example. - - -Unlike most other commands @code{add} never recurses down -directories. It cannot yet handle relative paths. Instead of - -@example -$ cvs add foo/bar.c -@end example - -you have to do - -@example -$ cd foo -$ cvs add bar.c -@end example - -@menu -* add options:: add options -* add examples:: add examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node add options -@appendixsubsec add options -@cindex Add options - -There are only two options you can give to @samp{add}: +@item -W +Specify file names that should be filtered. You can +use this option repeatedly. The spec can be a file +name pattern of the same type that you can specify in +the @file{.cvswrappers} file. +Avaliable with the following commands: @code{import}, +and @code{update}. -@table @code -@item -k @var{kflag} -This option specifies the default way that this file -will be checked out. The @var{kflag} argument -(@pxref{Substitution modes}) is stored in the @sc{rcs} -file and can be changed with @code{admin -k} -(@pxref{admin options}). See @ref{Binary files}, for -information on using this option for binary files. - -@item -m @var{description} -Using this option, you can give a description for the file. This -description appears in the history log (if it is enabled, -@pxref{history file}). It will also be saved in the @sc{rcs} history -file inside the repository when the file is committed. The -@code{log} command displays this description. - -The description can be changed using @samp{admin -t}. -@xref{admin}. - -If you omit the @samp{-m @var{description}} flag, an empty string will be -used. You will not be prompted for a description. @end table -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node add examples -@appendixsubsec add examples - -To add the file @file{backend.c} to the repository, with a -description, the following can be used. - -@example -$ cvs add -m "Optimizer and code generation passes." backend.c -$ cvs commit -m "Early version. Not yet compilable." backend.c -@end example - @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @node admin @appendixsec admin---Administration front end for rcs @@ -4530,6 +6768,9 @@ all its options and arguments to the @code{rcs} command; it does no filtering or other processing. This command @emph{does} work recursively, however, so extreme care should be used. +@c "group" should probably read "unix group" (but what +@c does NT local do?). "compiled in value" is +@c unclear--compiled in to what? If there is a group whose name matches a compiled in value which defaults to @code{cvsadmin}, only members of that group can use @code{cvs admin}. To disallow @@ -4551,7 +6792,7 @@ with @sc{cvs}. Some even makes it impossible to use This description of the available options is based on the @samp{rcs(1)} man page, but modified to suit -readers that are more interrested in @sc{cvs} than +readers that are more interested in @sc{cvs} than @sc{rcs}. @table @code @@ -4569,12 +6810,10 @@ login names appearing in the comma-separated list When used with bare @sc{rcs}, this option sets the default branch to @var{rev}; in @sc{cvs} sticky tags (@pxref{Sticky tags}) are a better -way to decide which branch you want to work on. With -@sc{cvs}, this option can be used to control behavior -with respect to the vendor branch. -@c FIXME: document how you use it with the vendor -@c branch (or fix cvs so that there is a more graceful -@c way to handle the case). +way to decide which branch you want to work on. There +is one use with @sc{cvs}: to revert to the vendor's +version when using vendor branches (@pxref{Reverting +local changes}). @item -c@var{string} Useful with @sc{cvs}. Sets the comment leader to @@ -4592,6 +6831,8 @@ 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. +@c FIXME: Doesn't work with client/server CVS; we +@c should probably just not accept the option. @item -I Run interactively, even if the standard input is not a terminal. @@ -4608,8 +6849,6 @@ substitution}. Giving an explicit @samp{-k} option to @code{cvs update}, @code{cvs export}, or @code{cvs checkout} overrides this default. -@cindex Reserved checkouts -@cindex RCS-style locking @item -l[@var{rev}] Lock the revision with number @var{rev}. If a branch is given, lock the latest revision on that branch. If @@ -4846,6 +7085,8 @@ collection of source directories and files, or paths to directories or files in the repository. The symbolic names are defined in the @samp{modules} file. @xref{modules}. +@c Needs an example, particularly of the non-"modules" +@c case but probably of both. Depending on the modules you specify, @code{checkout} may recursively create directories and populate them with @@ -4884,6 +7125,9 @@ to the @code{update} command, that is, any new directories that have been created in the repository will appear in your work area. @xref{update}. +For the output produced by the @code{checkout} command +see @ref{update output}. + @menu * checkout options:: checkout options * checkout examples:: checkout examples @@ -4914,7 +7158,8 @@ Process @sc{rcs} keywords according to @var{kflag}. See co(1). This option is sticky; future updates of this file in this working directory will use the same @var{kflag}. The @code{status} command can be viewed -to see the sticky options. @xref{status}. +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. @@ -4925,11 +7170,14 @@ with the @samp{-o} option in the modules file; @pxref{modules}). @item -P -Prune empty directories. +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. @@ -4948,11 +7196,18 @@ Copy the module file, sorted, to the standard output, instead of creating or modifying any files or directories in your working directory. +@c Should clarify whether dir can specify a +@c subdirectory (for example "foo/bar"). As of May, +@c 1996, it is said to work for local CVS if the parent +@c directories already exist, and not at all for remote +@c CVS. The remote CVS behavior at least seems like it +@c is clearly a bug. @item -d @var{dir} Create a directory called @var{dir} for the working files, instead of using the module name. Unless you also use @samp{-N}, the paths created under @var{dir} will be as short as possible. +@c FIXME: What the #$@!#$# does "short as possible" mean? @item -j @var{tag} With two @samp{-j} options, merge changes from the @@ -5014,12 +7269,8 @@ $ cvs checkout -D yesterday tc @itemize @bullet @item -Version 1.3 Synopsis: commit [-lnR] [-m 'log_message' | --f file] [-r revision] [files@dots{}] -@item -Version 1.3.1 Synopsis: commit [-lnRf] [-m 'log_message' | +Synopsis: commit [-lnRf] [-m 'log_message' | -F file] [-r revision] [files@dots{}] -@c -- rename-f-F-- @item Requires: working directory, repository. @item @@ -5028,11 +7279,6 @@ Changes: repository. Synonym: ci @end itemize -@strong{Warning:} The @samp{-f @var{file}} option will -probably be renamed to @samp{-F @var{file}}, and @samp{-f} -will be given a new behavior in future releases of @sc{cvs}. -@c -- rename-f-F-- - Use @code{commit} when you want to incorporate changes from your working source files into the source repository. @@ -5064,8 +7310,7 @@ repository. This log message can be retrieved with the @code{log} command; @xref{log}. You can specify the log message on the command line with the @samp{-m @var{message}} option, and thus avoid the editor invocation, -or use the @samp{-f @var{file}} option to specify -@c -- rename-f-F-- +or use the @samp{-F @var{file}} option to specify that the argument file contains the log message. @menu @@ -5094,22 +7339,21 @@ Commit directories recursively. This is on by default. @item -r @var{revision} Commit to @var{revision}. @var{revision} must be either a branch, or a revision on the main trunk that -is higher than any existing revision number. You +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} -This option is present in @sc{cvs} releases 1.3-s3 and -later. Read the log message from @var{file}, instead +Read the log message from @var{file}, instead of invoking an editor. @item -f -@c -- rename-f-F-- -This option is present in @sc{cvs} 1.3-s3 and later releases -of @sc{cvs}. Note that this is not the standard behavior of +Note that this is not the standard behavior of the @samp{-f} option as defined in @xref{Common options}. Force @sc{cvs} to commit a new revision even if you haven't @@ -5122,14 +7366,12 @@ $ cvs commit -f @var{file} $ cvs commit -r 1.8 @var{file} @end example -@item -f @var{file} -@c -- rename-f-F-- -This option is present in @sc{cvs} releases 1.3, 1.3-s1 and -1.3-s2. Note that this is not the standard behavior of -the @samp{-f} option as defined in @xref{Common options}. - -Read the log message from @var{file}, instead -of invoking an editor. +@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 @@ -5141,36 +7383,6 @@ invoking an editor. @node commit examples @appendixsubsec commit examples -@appendixsubsubsec New major release number - -When you make a major release of your product, you -might want the revision numbers to track your major -release number. You should normally not care about -the revision numbers, but this is a thing that many -people want to do, and it can be done without doing any -harm. - -To bring all your files up to the @sc{rcs} revision 3.0 -(including those that haven't changed), you might do: - -@example -$ cvs commit -r 3.0 -@end example - -Note that it is generally a bad idea to try to make the -@sc{rcs} revision number equal to the current release number -of your product. You should think of the revision -number as an internal number that the @sc{cvs} package -maintains, and that you generally never need to care -much about. Using the @code{tag} and @code{rtag} -commands you can give symbolic names to the releases -instead. @xref{tag} and @xref{rtag}. - -Note that the number you specify with @samp{-r} must be -larger than any existing revision number. That is, if -revision 3.0 exists, you cannot @samp{cvs commit --r 1.3}. - @appendixsubsubsec Committing to a branch You can commit to a branch revision (one that has an @@ -5249,12 +7461,12 @@ $ cvs checkout -r EXPR1 whatever_module @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @node diff -@appendixsec diff---Run diffs between revisions +@appendixsec diff---Show differences between revisions @cindex Diff (subcommand) @itemize @bullet @item -Synopsis: diff [-l] [rcsdiff_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files@dots{}] +Synopsis: diff [-lR] [rcsdiff_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files@dots{}] @item Requires: working directory, repository. @item @@ -5292,14 +7504,6 @@ them): Use the most recent revision no later than @var{date}. See @samp{-r} for how this affects the comparison. -@sc{cvs} can be configured to pass the @samp{-D} option -through to @code{rcsdiff} (which in turn passes it on -to @code{diff}. @sc{Gnu} diff uses @samp{-D} as a way to -put @code{cpp}-style @samp{#define} statements around the output -differences. There is no way short of testing to -figure out how @sc{cvs} was configured. In the default -configuration @sc{cvs} will use the @samp{-D @var{date}} option. - @item -k @var{kflag} Process @sc{rcs} keywords according to @var{kflag}. See co(1). @@ -5323,18 +7527,72 @@ outcome in any way). One or both @samp{-r} options can be replaced by a @samp{-D @var{date}} option, described above. + +@item --ifdef=@var{arg} +Output in ifdef format. Consult the documentation of +your underlying diff program concerning the @samp{-D} +option to diff, for more information on this format. @end table -Any other options that are found are passed through to +@c FIXME? Probably should document -c here, and +@c perhaps arrange for CVS to support it via a diff library or +@c some such. Or perhaps figure that "all" diff +@c programs support -c? Ideas is to preserve the +@c ability to pass the buck to diff on all the hairy +@c stuff, while still providing at least one, and +@c perhaps several popular standard formats. But this +@c is all in the idea stage, and probably needs more +@c thought and refinement. -u might be similar, in +@c terms of being something that it might make sense to +@c document here. +@c FIXME: also should be a way to 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 option to diff. +@c Note on -N: The current CVS implementation does require that the +@c underlying diff supports -N so we can document it as +@c a pass-through even if the implementation details +@c are more complicated. +@c +@c FIXME? Reference to discussion of which diff CVS +@c uses (one in path, or....). +The following options are passed through to @code{rcsdiff}, which in turn passes them to @code{diff}. The exact meaning of the options depends -on which @code{diff} you are using. The long options -introduced in @sc{gnu} diff 2.0 are not yet supported in -@sc{cvs}. See the documentation for your @code{diff} to see -which options are supported. +on which @code{diff} you are using. See the +documentation for your @code{diff} for details. + +@code{-a} @code{-b} @code{-B} @code{-c} @w{@code{-C} +@var{nlines}} @code{-d} @code{-e} @code{-f} @code{-h} +@code{-H} @code{-i} @code{-n} @code{-N} @code{-p} +@code{-s} @code{-t} @code{-u} @code{-U} @var{nlines} +@w{@code{-F} @var{regexp}} @w{@code{-I} @var{regexp}} +@w{@code{-L} @var{label}} @code{-T} @w{@code{-V} +@var{arg}} @w{@code{-W} @var{columns}} @code{-w} +@code{-y} @code{-0} @code{-1} @code{-2} @code{-3} +@code{-4} @code{-5} @code{-6} @code{-7} @code{-8} +@code{-9} @code{--binary} @code{--brief} +@code{--changed-group-format=@var{arg}} +@code{--context[=@var{lines}]} @code{--ed} +@code{--expand-tabs} @code{--forward-ed} +@code{--horizon-lines=@var{arg}} +@code{--ignore-all-space} @code{--ignore-blank-lines} +@code{--ignore-case} +@code{--ignore-matching-lines=@var{regexp}} +@code{--ignore-space-change} @code{--initial-tab} +@code{--label=@var{label}} @code{--left-column} +@code{--minimal} @code{--new-file} +@code{--new-line-format=@var{arg}} +@code{--old-line-format=@var{arg}} @code{--paginate} +@code{--rcs} @code{--report-identical-files} +@code{--code-c-function} @code{--side-by-side} +@code{--show-function-line=@var{regexp}} +@code{--speed-large-files} +@code{--suppress-common-lines} @code{--text} +@code{--unchanged-group-format=@var{arg}} +@code{--unified[=@var{lines}]} +@code{--width=@var{columns}} -@c -- Document some common useful diff options, such as -@c -u and -c. @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . @node diff examples @appendixsubsec diff examples @@ -5380,7 +7638,7 @@ $ cvs diff -u | less @itemize @bullet @item -Synopsis: export [-flNn] [-r rev|-D date] [-k subst] [-d dir] module@dots{} +Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] module@dots{} @item Requires: repository. @item @@ -5539,6 +7797,8 @@ Certain commands have a single record type: release @item O checkout +@item E +export @item T rtag @end table @@ -5638,6 +7898,8 @@ Contributed examples will gratefully be accepted. @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{} @@ -5669,7 +7931,8 @@ 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 +@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 @@ -5691,8 +7954,19 @@ branch (e.g., for 1.1.1). You must also specify at least one @var{releasetag} to identify the files at the leaves created each time you execute @code{import}. +@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 @@ -5725,7 +7999,7 @@ in the future. Indicate the RCS keyword expansion mode desired. This setting will apply to all files created during the import, but not to any files that previously existed in -the repository. See @ref{Substitution modes} for a +the repository. See @ref{Substitution modes}, for a list of valid @samp{-k} settings. @item -I @var{name} @@ -5749,6 +8023,46 @@ 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 @@ -5756,31 +8070,51 @@ file. @xref{Wrappers}. @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @node log -@appendixsec log---Print out 'rlog' information for files +@appendixsec log---Print out log information for files @cindex Log (subcommand) @itemize @bullet @item -Synopsis: log [-l] rlog-options [files@dots{}] +Synopsis: log [options] [files@dots{}] @item Requires: repository, working directory. @item Changes: nothing. -@item -Synonym: rlog @end itemize -Display log information for files. @code{log} calls -the @sc{rcs} utility @code{rlog}, which prints all available -information about the @sc{rcs} history file. This includes -the location of the @sc{rcs} file, the @dfn{head} revision -(the latest revision on the trunk), all symbolic names (tags) -and some other things. For each revision, the revision -number, the author, the number of lines added/deleted and -the log message are printed. All times are displayed in -Coordinated Universal Time (UTC). (Other parts of @sc{cvs} -print times in the local timezone). -@c -- timezone-- +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{Warning:} @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 @@ -5791,42 +8125,29 @@ print times in the local timezone). @node log options @appendixsubsec log options -Only one option is interpreted by @sc{cvs} and not passed on to @code{rlog}: - -@table @code -@item -l -Local; run only in current working directory. (Default -is to run recursively). -@end table - -By default, @code{rlog} prints all information that is -available. All other options (including those that -normally behave differently) are passed through to -@code{rlog} and restrict the output. See rlog(1) for a -complete description of options. This incomplete list -(which is a slightly edited extract from rlog(1)) lists -all options that are useful in conjunction with @sc{cvs}. - -@strong{Please note:} There can be no space between the option -and its argument, since @code{rlog} parses its options -in a different way than @sc{cvs}. +By default, @code{log} prints all information that is +available. All other options restrict the output. @table @code @item -b Print information about the revisions on the default branch, normally the highest branch on the trunk. -@item -d@var{dates} +@item -d @var{dates} Print information about revisions with a checkin date/time in the range given by the -semicolon-separated list of dates. The following table -explains the available range formats: +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} inclusive. +@var{d1} and @var{d2}. @item <@var{d} @itemx @var{d}> @@ -5841,16 +8162,21 @@ Select the single, latest revision dated @var{d} or earlier. @end table -The date/time strings @var{d}, @var{d1}, and @var{d2} -are in the free format explained in co(1). Quoting is -normally necessary, especially for < and >. Note that -the separator is a semicolon (;). +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 @sc{rcs} pathname, working pathname, 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 @@ -5882,10 +8208,7 @@ branch containing @var{rev}. @item @var{branch} An argument that is a branch means all revisions on -that branch. You can unfortunately not specify a -symbolic branch here. You must specify the numeric -branch number. @xref{Magic branch numbers}, for an -explanation. +that branch. @item @var{branch1}:@var{branch2} A range of branches means all revisions @@ -5897,8 +8220,10 @@ The latest revision in @var{branch}. 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@var{states} +@item -s @var{states} Print information about revisions whose state attributes match one of the states given in the comma-separated list @var{states}. @@ -5910,13 +8235,14 @@ Print the same as @samp{-h}, plus the descriptive text. 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. +login is assumed. There can be no space between the +@samp{-w} option and its argument. @end table -@code{rlog} prints the intersection of the revisions -selected with the options @samp{-d}, @samp{-l}, -@samp{-s}, and @samp{-w}, intersected with the union of -the revisions selected by @samp{-b} and @samp{-r}. +@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 @@ -5985,6 +8311,9 @@ recent revision (instead of ignoring the file). @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 @@ -6087,7 +8416,7 @@ history log. @menu * release options:: release options -* release output:: release options +* release output:: release output * release examples:: release examples @end menu @@ -6103,12 +8432,12 @@ Delete your working copy of the file if the release succeeds. If this flag is not given your files will remain in your working directory. -@strong{Warning:} The @code{release} command uses -@samp{rm -r @file{module}} to delete your file. This +@strong{Warning:} The @code{release} command deletes +all directories and files recursively. This has the very serious side-effect that any directory that you have created inside your checked-out sources, and not added to the repository (using the @code{add} -command; @pxref{add}) will be silently deleted---even +command; @pxref{Adding files}) will be silently deleted---even if it is non-empty! @end table @@ -6122,15 +8451,18 @@ up-to-date. @strong{Warning:} Any new directories that you have created, but not added to the @sc{cvs} directory hierarchy -with the @code{add} command (@pxref{add}) will be +with the @code{add} command (@pxref{Adding files}) will be silently ignored (and deleted, if @samp{-d} is specified), even if they contain files. +@c FIXCVS: This is a bug. But is it true? I think +@c maybe they print "? dir" now. @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. +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 @@ -6155,13 +8487,6 @@ not in the list of files for @sc{cvs} to ignore (see the description of the @samp{-I} option, and @pxref{cvsignore}). If you remove your working sources, this file will be lost. - -Note that no warning message like this is printed for -spurious directories that @sc{cvs} encounters. The -directory, and all its contents, are silently ignored. - -@c FIXME -- CVS should be fixed to print "? foo" for -@c such spurious directories @end table @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . @@ -6181,7 +8506,7 @@ $ @end example @node rtag -@appendixsec rtag---Add a tag to the RCS file +@appendixsec rtag---Add a symbolic tag to a module @cindex Rtag (subcommand) @itemize @bullet @@ -6242,7 +8567,7 @@ Do not run any tag program that was specified with the (@pxref{modules}). @item -R -Commit directories recursively. This is on by default. +Tag directories recursively. This is on by default. @item -r @var{tag} Only tag those files that contain @var{tag}. This can @@ -6256,15 +8581,17 @@ are available: @table @code @item -a +@c FIXME: What does this option mean in terms of user +@c concepts, not CVS internals? Use the @samp{-a} option to have @code{rtag} look in the -@file{Attic} (@pxref{Removing files}) for removed files +@file{Attic} (@pxref{Attic}) for removed files that contain the specified tag. The tag is removed from these files, which makes it convenient to re-use a symbolic tag as development continues (and files get removed from the up-coming distribution). @item -b -Make the tag a branch tag. @xref{Branches}. +Make the tag a branch tag. @xref{Revisions and branches}. @item -d Delete the tag instead of creating it. @@ -6286,69 +8613,8 @@ module). @end ignore @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node status -@appendixsec status---Status info on the revisions -@cindex Status (subcommand) - -@itemize @bullet -@item -status [-lR] [-v] [files@dots{}] -@item -Requires: working directory, repository. -@item -Changes: nothing. -@end itemize - -Display a brief report on the current status of files -with respect to the source repository, including any -sticky tags, dates, or @samp{-k} options. - -You can also use this command to determine the -potential impact of a @samp{cvs update} on your working -source directory---but remember that things might -change in the repository before you run @code{update}. - -@menu -* status options:: status options -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node status options -@appendixsubsec status options - -These standard options are supported by @code{status} -(@pxref{Common options}, for a complete description of -them): - -@table @code -@item -l -Local; run only in current working directory. - -@item -R -Commit directories recursively. This is on by default. -@end table - -There is one additional option: - -@table @code -@item -v -Verbose. In addition to the information normally -displayed, print all symbolic tags, together with the -numerical value of the revision or branch they refer -to. -@end table - -@ignore -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@c @node status examples -@appendixsubsec status examples - -@c -- FIXME -@end ignore - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @node tag -@appendixsec tag---Add a symbolic tag to checked out version of RCS file +@appendixsec tag---Add a symbolic tag to checked out versions of files @c -- //////// - unnecessary. Also @c -- in a lot of other @c -- places. @@ -6356,7 +8622,7 @@ to. @itemize @bullet @item -tag [-lR] [-b] [-d] symbolic_tag [files@dots{}] +tag [-lR] [-b] [-c] [-d] symbolic_tag [files@dots{}] @item Requires: working directory, repository. @item @@ -6416,7 +8682,7 @@ different revision. This option is new in @sc{cvs} Local; run only in current working directory. @item -R -Commit directories recursively. This is on by default. +Tag directories recursively. This is on by default. @end table Two special options are available: @@ -6424,10 +8690,15 @@ Two special options are available: @table @code @item -b The -b option makes the tag a branch tag -(@pxref{Branches}), allowing concurrent, isolated +(@pxref{Revisions and branches}), allowing concurrent, isolated development. This is most useful for creating a patch to a previously released software distribution. +@item -c +The -c option checks that all files which are to be tagged are +unmodified. This can be used to make sure that you can reconstruct the +current file contents. + @item -d Delete a tag. @@ -6473,7 +8744,6 @@ since your last checkout or update. @menu * update options:: update options * update output:: update output -* update examples:: update examples @end menu @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . @@ -6501,20 +8771,21 @@ Process @sc{rcs} keywords according to @var{kflag}. See co(1). This option is sticky; future updates of this file in this working directory will use the same @var{kflag}. The @code{status} command can be viewed -to see the sticky options. @xref{status}. +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. @xref{Recursive behavior}. @item -P -Prune empty directories. +Prune empty directories. See @ref{Moving directories}. @item -p Pipe files to the standard output. @item -R -Operate recursively. This is on by default. -@xref{Recursive behavior}. +Update directories recursively (default). @xref{Recursive +behavior}. @item -r tag Retrieve revision @var{tag}. This option is sticky, @@ -6591,9 +8862,9 @@ date. An optional date is specified by adding a colon @node update output @appendixsubsec update output -@code{update} keeps you informed of its progress by -printing a line for each file, preceded by one -character indicating the status of the file: +@code{update} and @code{checkout} keep 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} @@ -6603,6 +8874,11 @@ the repository but not in your source, and for files that you haven't changed but are not the most recent versions available in the repository. +@item P @var{file} +Like @samp{U}, but the @sc{cvs} server sends a patch +instead of an entire file. These two things accomplish +the same thing. + @item A @var{file} The file has been added to your private copy of the sources, and will be added to the source repository @@ -6632,6 +8908,8 @@ 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 @@ -6640,11 +8918,21 @@ on the two revisions; an unmodified copy of your file is also in your working directory, with the name @file{.#@var{file}.@var{revision}} where @var{revision} is the @sc{rcs} revision that your modified file started -from. (Note that some systems automatically purge +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.) +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 @@ -6652,28 +8940,712 @@ 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 -Note that no warning message like this is printed for -spurious directories that @sc{cvs} encounters. The -directory, and all its contents, are silently ignored. +@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. Other relevant references are the +@samp{--help}/@samp{-H} option to @sc{cvs} +(@pxref{Global options}) and @ref{Index}. + +@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. +@table @code +@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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node update examples -@appendixsubsec update examples +@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. +@c FIXME: Should xref to a section which describes how +@c to use this with the vendor branch. -The following line will display all files which are not -up-to-date without actually change anything in your -working directory. It can be used to check what has -been going on with the project. +@item -c@var{string} +Set comment leader. -@example -$ cvs -n -q update -@end example +@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 history files + +@item -q +Run quietly; do not print diagnostics. + +@item -s@var{state}[:@var{rev}] +Set the state. + +@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 + +@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 +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 + +@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 + +@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 + +@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 rev1/date1 against rev2. See @ref{diff options}. +@end table + +@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 + +@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 + +@item export [@var{options}] @var{modules}@dots{} +Export files from 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 -P +Prune empty directories. See @ref{Moving directories}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. + +@item -r @var{tag} +Checkout revision @var{tag} (is sticky). See @ref{Common options}. +@end table + +@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 -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{TOEFWUCGMAR}. See @ref{history options}. + +@item -z @var{zone} +Output for time zone @var{zone}. See @ref{history +options}. +@end table + +@item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{} +Import files into CVS, using vendor branches. See +@ref{import}. + +@table @code +@item -b @var{bra} +Import to vendor branch @var{bra}. See +@ref{import options}. + +@item -d +Use the file's modification time as the time of +import. See @ref{import options}. + +@item -k @var{kflag} +Set default RCS 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 + +@item init +Create a CVS repository if it doesn't exist. See +@ref{Creating a repository}. + +@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 + +@item login +Prompt for password for authenticating server. See +@ref{Password authentication client}. + +@item logout +Remove stored password for authenticating server. See +@ref{Password authentication client}. + +@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. See +@ref{rdiff options}. +@end table + +@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 + +@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 + +@item rtag [@var{options}] @var{tag} @var{modules}@dots{} +Add a symbolic tag to a module. See @ref{rtag}. + +@table @code +@c Is this one of those dumb options which used to +@c work around the lack of death support? +@item -a +Clear tag from removed files that would not otherwise +be tagged. See @ref{rtag options}. + +@item -b +Create a branch named @var{tag}. See @ref{rtag options}. + +@item -D @var{date} +Tag revisions as of @var{date}. See @ref{rtag options}. + +@item -d +Delete the given tag. See @ref{rtag options}. + +@item -F +Move tag if it already exists. See @ref{rtag options}. + +@item -f +Force a head revision match if tag/date not found. +See @ref{rtag options}. + +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -n +No execution of tag program. See @ref{rtag options}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. + +@item -r @var{tag} +Tag existing tag @var{tag}. See @ref{rtag options}. +@end table + +@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 + +@item tag [@var{options}] @var{tag} [@var{files}@dots{}] +Add a symbolic tag to checked out version of files. +See @ref{tag}. + +@table @code +@item -b +Create a branch named @var{tag}. See @ref{tag options}. + +@item -D @var{date} +Tag revisions as of @var{date}. See @ref{tag options}. + +@item -d +Delete the given tag. See @ref{tag options}. + +@item -F +Move tag if it already exists. See @ref{tag options}. + +@item -f +Force a head revision match if tag/date not found. +See @ref{tag options}. + +@item -l +Local; run only in current working directory. See @ref{Recursive behavior}. + +@item -n +No execution of tag program. See @ref{tag options}. + +@item -R +Operate recursively (default). @xref{Recursive +behavior}. + +@item -r @var{tag} +Tag existing tag @var{tag}. See @ref{tag options}. +@end table + +@item unedit [@var{options}] [@var{files}@dots{}] +Undo an edit command. 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 + +@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 -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 + +@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 + +@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 the Administrative files +@appendix Reference manual for Administrative files @cindex Administrative files (reference) @cindex Files, reference manual @cindex Reference manual (files) @@ -6683,7 +9655,9 @@ 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. +properly they can help make life easier. For a +discussion of how to edit them, @xref{Intro +administrative files}. The most important of these files is the @file{modules} file, which defines the modules inside the repository. @@ -6693,12 +9667,13 @@ file, which defines the modules inside the repository. * Wrappers:: Treat directories as files * commit files:: The commit support files * commitinfo:: Pre-commit checking -* editinfo:: Specifying how log messages are created +* verifymsg:: How are log messages evaluated? +* editinfo:: Specifying how log messages are created + (obsolete) * loginfo:: Where should log messages be sent? * rcsinfo:: Templates for the log messages * cvsignore:: Ignoring files via cvsignore * history file:: History information -* Setting up:: Setting up the repository * Variables:: Various variables are expanded @end menu @@ -6771,9 +9746,33 @@ in the @sc{cvs} source repository. A module definition can refer to other modules by including @samp{&@var{module}} in its definition. @code{checkout} creates a subdirectory for each such -module, in your working directory. -@c -- Nope. "in your working directory" is wrong. What -@c -- is right? +module, in the directory containing the module. For +example, if modules contains + +@example +m4test &unsupported +@end example + +then a checkout will create an @code{m4test} directory +which contains a directory called @code{unsupported}, +which in turns contains all the directories and files +which live there. +@c FIXME: this is hard to describe since we don't tell +@c the user what the repository contains. Best way to +@c fix this whole mess is an extended example where we +@c first say what is in the repository, then show a +@c regular module, an alias module, and an & module. +@c We should mention the concept of options only +@c *after* we've taken care of those basics. +@c +@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. @table @code @item -d @var{name} @@ -6785,6 +9784,7 @@ module name. 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 Checkin program @item -i @var{prog} @@ -6792,14 +9792,16 @@ Specify a program @var{prog} to run whenever files in a module are committed. @var{prog} runs with a single argument, the full pathname of the affected directory in a source repository. The @file{commitinfo}, -@file{loginfo}, and @file{editinfo} files provide other +@file{loginfo}, and @file{verifymsg} files provide other ways to call a program on commit. +@c FIXME: Is it run on server? client? @cindex Checkout program @item -o @var{prog} Specify a program @var{prog} to run whenever files in a module are checked out. @var{prog} runs with a single argument, the module name. +@c FIXME: Is it run on server? client? @cindex Status of a module @cindex Module status @@ -6819,6 +9821,7 @@ module are tagged with @code{rtag}. @var{prog} runs with two arguments: the module name and the symbolic tag specified to @code{rtag}. There is no way to specify a program to run when @code{tag} is executed. +@c FIXME: Is it run on server? client? @cindex Update program @item -u @var{prog} @@ -6827,6 +9830,7 @@ update} is executed from the top-level directory of the checked-out module. @var{prog} runs with a single argument, the full path to the source repository for this module. +@c FIXME: Is it run on server? client? @end table @end table @@ -6837,9 +9841,14 @@ this module. @cindex CVSWRAPPERS, environment variable @cindex Wrappers +@c FIXME: need some better way of separating this out +@c by functionality. -t/-f is one feature, -m is +@c another, and -k is a third. And this discussion +@c should be better motivated (e.g. start with the +@c problems, then explain how the feature solves it). + Wrappers allow you to set a hook which transforms files on -their way in and out of @sc{cvs}. Most or all of the -wrappers features do not work with client/server @sc{cvs}. +their way in and out of @sc{cvs}. The file @file{cvswrappers} defines the script that will be run on a file when its name matches a regular @@ -6848,7 +9857,8 @@ file or directory. One script is executed on the file/directory before being checked into the repository (this is denoted with the @code{-t} flag) and the other when the file is checked out of the repository (this is denoted with the -@code{-f} flag) +@code{-f} flag). The @samp{-t}/@samp{-f} feature does +not work with client/server @sc{cvs}. The @file{cvswrappers} also has a @samp{-m} option to specify the merge methodology that should be used when @@ -6867,13 +9877,16 @@ 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 --f from cvs filter value: path tofilter +-f from cvs filter value: path to filter -t to cvs filter value: path to filter -m update methodology value: MERGE or COPY +-k keyword expansion value: expansion mode and value is a single-quote delimited value. @end example @@ -6894,6 +9907,11 @@ file is checked out of the repository. The 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 a @code{*.c} should be filtered with @file{indent} before being checked into the repository. Unlike the previous @@ -6911,6 +9929,57 @@ 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 CVS's operation: +determining when files are modified. 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 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. + +For another 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 commit files @appendixsec The commit support files @@ -6934,12 +10003,19 @@ 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}). +template (@pxref{rcsinfo}). (obsolete) @item loginfo The specified program is called when the commit is @@ -6961,15 +10037,34 @@ imagination is the limit! @cindex Syntax of info files @cindex Common syntax of info files -The four files @file{commitinfo}, @file{loginfo}, -@file{rcsinfo} and @file{editinfo} all have a common -format. The purpose of the files are described later -on. The common syntax is described here. +@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 -A regular expression +@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. @item A whitespace separator---one or more spaces and/or tabs. @@ -6988,6 +10083,13 @@ 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 commitinfo @appendixsec Commitinfo @@ -7032,14 +10134,129 @@ Note: when @sc{CVS} is accessing a remote repository, (i.e., server) side, not the client side (@pxref{Remote repositories}). +@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 +@appendixsec Verifying log messages +@cindex 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 +module, and then overriding it in a subdirectory. + +@cindex DEFAULT in 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. + +If the verification script exits with a non-zero exit status, +the commit is aborted. + +Note that the verification script cannot change the log +message; it can merely accept it or reject it. +@c FIXME? Is this an annoying limitation? It would be +@c relatively easy to fix (although it would *not* be a +@c good idea for a verifymsg script to interact with the user +@c at least in the client/server case because of locks +@c and all that jazz). + +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 head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then + exit 0 +else + echo "No BugId found." + exit 1 +fi +@end example + +The @file{verifymsg} 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 editinfo @appendixsec Editinfo -@cindex Editinfo +@cindex editinfo (admin file) @cindex Editor, specifying per module @cindex Per-module editor @cindex Log messages, editing +@emph{NOTE:} The @file{editinfo} feature has been +rendered obsolete. To set a default editor for log +messages use the @code{EDITOR} environment variable +(@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. @@ -7053,8 +10270,7 @@ file, the editor specified in the environment variable @code{$CVSEDITOR} is used instead. If that variable is not set, then the environment variable @code{$EDITOR} is used instead. If that variable is not -set a precompiled default, normally @code{vi}, will be -used. +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 @@ -7081,9 +10297,10 @@ If the edit script exits with a non-zero exit status, the commit is aborted. Note: when @sc{CVS} is accessing a remote repository, -@file{editinfo} will be run on the @emph{remote} -(i.e., server) side, not the client side (@pxref{Remote -repositories}). +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 @@ -7145,7 +10362,7 @@ The @file{rcsinfo} file contains this line: @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @node loginfo @appendixsec Loginfo -@cindex Loginfo +@cindex loginfo (admin file) @cindex Storing log messages @cindex Mailing log messages @cindex Distributing log messages @@ -7159,11 +10376,6 @@ relative to the @code{$CVSROOT}. If a match is found, then the remainder of the line is a filter program that should expect log information on its standard input. -The filter program may use one and only one % modifier -(a la printf). If @samp{%s} is specified in the filter -program, a brief title is included (enclosed in single -quotes) showing the modified file names. - If the repository name does not match any of the regular expressions in this file, the @samp{DEFAULT} line is used, if it is specified. @@ -7177,6 +10389,46 @@ 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 string of tokens separated by +spaces. For backwards compatibility, the the first +token will be the repository name. 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} 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 +/u/src/master 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 @@ -7184,6 +10436,7 @@ repositories}). @menu * loginfo example:: Loginfo example +* Keeping a checked out copy:: Updating a tree on every checkin @end menu @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . @@ -7214,17 +10467,66 @@ like this: @example #!/bin/sh -(echo "-----------------------------------------------------------------"; +(echo "------------------------------------------------------"; echo -n $USER" "; date; echo; sed '1s+'$@{CVSROOT@}'++') >> $1 @end example +@node Keeping a checked out copy +@appendixsubsec 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 (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 +@cindex rcsinfo (admin file) @cindex Form for log message @cindex Log message template @cindex Template for log message @@ -7232,7 +10534,7 @@ like this: The @file{rcsinfo} file can be used to specify a form to edit when filling out the commit log. The @file{rcsinfo} file has a syntax similar to the -@file{editinfo}, @file{commitinfo} and @file{loginfo} +@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 @@ -7246,13 +10548,26 @@ All occurances of the name @samp{ALL} appearing as a regular expression are used in addition to the first matching regular expression or @samp{DEFAULT}. +@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/cvsssupport +@c stuff is to use checkoutlist. FIXME: it doesn't +@c seem like checkoutlist is documented at all! +@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{editinfo example}, for an example @file{rcsinfo} +@xref{verifymsg}, for an example @file{rcsinfo} file. When @sc{CVS} is accessing a remote repository, @@ -7269,7 +10584,7 @@ directory. @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @node cvsignore @appendixsec Ignoring files via cvsignore -@cindex Cvsignore, global +@cindex cvsignore (admin file), global @cindex Global cvsignore @cindex Ignoring files @c -- This chapter should maybe be moved to the @@ -7343,6 +10658,20 @@ 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. + @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @node history file @appendixsec The history file @@ -7354,7 +10683,7 @@ to log information for the @code{history} command (@pxref{history}). This file must be created to turn on logging. This is done automatically if the @code{cvs init} command is used to set up the -repository (@pxref{Setting up}). +repository (@pxref{Creating a repository}). The file format of the @file{history} file is documented only in comments in the @sc{cvs} source @@ -7362,39 +10691,6 @@ code, but generally programs should use the @code{cvs history} command to access it anyway, in case the format changes with future releases of @sc{cvs}. -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Setting up -@appendixsec Setting up the repository -@cindex Repository, setting up -@cindex Creating a repository -@cindex Setting up a repository - -To set up a @sc{cvs} repository, choose a directory -with ample disk space available for the revision -history of the source files. It should be accessable -(directly or via a networked file system) from all -machines which want to use @sc{cvs} in server or local -mode; the client machines need not have any access to -it other than via the @sc{cvs} protocol. - -To create a repository, run the @code{cvs init} -command. It will set up an empty repository in the -@sc{cvs} root specified in the usual way -(@pxref{Repository}). For example, - -@example -cvs -d /usr/local/cvsroot init -@end example - -@code{cvs init} is careful to never overwrite any -existing files in the repository, so no harm is done if -you run @code{cvs init} on an already set-up -repository. - -@code{cvs init} will enable history logging; if you -don't want that, remove the history file after running -@code{cvs init}. @xref{history file}. - @node Variables @appendixsec Expansions in administrative files @@ -7462,7 +10758,14 @@ particularly useful to specify this option via For example, if you want the administrative file to refer to a test directory you might create a user variable @code{TESTDIR}. Then if @sc{cvs} is invoked -as @code{cvs -s TESTDIR=/work/local/tests}, and the +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}. @@ -7492,6 +10795,7 @@ A whitespace-separated list of file name patterns that @sc{cvs} should treat as wrappers. @xref{Wrappers}. @cindex CVSREAD +@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 @@ -7517,11 +10821,8 @@ directory. @item $EDITOR @itemx $CVSEDITOR Specifies the program to use for recording log messages -during commit. If not set, the default is -@samp{/usr/ucb/vi}. @code{$CVSEDITOR} overrides -@code{$EDITOR}. @code{$CVSEDITOR} does not exist in -@sc{cvs} 1.3, but the next release will probably -include it. +during commit. @code{$CVSEDITOR} overrides +@code{$EDITOR}. See @ref{Committing your changes}. @cindex PATH @item $PATH @@ -7531,9 +10832,10 @@ programs it uses. @cindex RCSBIN @item $RCSBIN -Specifies the full pathname of the location of @sc{rcs} programs, -such as co(1) and ci(1). If not set, a compiled-in -value is used, or your @code{$PATH} is searched. +This is the value @sc{cvs} is using for where to find +@sc{rcs} binaries. @xref{Global options}, for a +description of how to specify this. If not set, a +compiled-in value is used, or your @code{$PATH} is searched. @cindex HOME @item $HOME @@ -7545,13 +10847,9 @@ file is searched (@code{$HOMEPATH} is used for Windows-NT). @cindex CVS_RSH @item $CVS_RSH -Used in client-server mode when accessing a remote -repository using @sc{rsh}. The default value is -@code{rsh}. You can set it to use another program for -accssing the remote server (e.g. for HP-UX 9, you -should set it to @code{remsh} because @code{rsh} -invokes the restricted shell). @pxref{Connecting via -rsh} +Specifies the external program which CVS connects with, +when @code{:ext:} access method is specified. +@pxref{Connecting via rsh}. @item $CVS_SERVER Used in client-server mode when accessing a remote @@ -7565,11 +10863,6 @@ Used in client-server mode when accessing the @code{cvs login server}. Default value is @file{$HOME/.cvspass}. @pxref{Password authentication client} -@item $CVS_PASSWORD -Used in client-server mode when accessing the @code{cvs -login server}. -@pxref{Password authentication client} - @item $CVS_CLIENT_PORT Used in client-server mode when accessing the server via Kerberos. @@ -7605,10 +10898,37 @@ seconds so that you can attach to it with a debugger. Used under OS/2 only. It specifies the name of the command interpreter and defaults to @sc{cmd.exe}. +@cindex TMPDIR +@item $TMPDIR +@cindex TMP +@itemx $TMP +@cindex TEMP +@itemx $TEMP +@cindex temporary files, location of +@c I'm not even sure I've documented all the +@c conventions here. Furthermore, those conventions are +@c pretty crazy and they should be simplified. +Directory in which temporary files are located. Those +parts of @sc{cvs} which are implemented using @sc{rcs} +inspect the above variables in the order they appear +above and the first value found is taken; if none of +them are set, a host-dependent default is used, +typically @file{/tmp}. 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). @end table -@sc{cvs} is a front-end to @sc{rcs}. The following environment +@sc{cvs} invokes @sc{rcs} to perform certain +operations. The following environment variables affect @sc{rcs}. Note that if you are using the client/server @sc{cvs}, these variables need to be set on the server side (which may or not may be @@ -7631,18 +10951,6 @@ Options prepended to the argument list, separated by spaces. A backslash escapes spaces within an option. The @code{$RCSINIT} options are prepended to the argument lists of most @sc{rcs} commands. - -@cindex TMPDIR -@item $TMPDIR -@cindex TMP -@itemx $TMP -@cindex TEMP -@itemx $TEMP -Name of the temporary directory. The environment -variables are inspected in the order they appear above -and the first value found is taken; if none of them are -set, a host-dependent default is used, typically -@file{/tmp}. @end table @c --------------------------------------------------------------------- @@ -7650,7 +10958,7 @@ set, a host-dependent default is used, typically @appendix Troubleshooting @menu -* Magic branch numbers:: Magic branch numbers +* Error messages:: Partial list of CVS errors @end menu @ignore @@ -7661,64 +10969,567 @@ set, a host-dependent default is used, typically @c -- Give hints on how to fix them @end ignore -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Magic branch numbers -@appendixsec Magic branch numbers +@node Error messages +@appendixsec Partial list of error messages -Externally, branch numbers consist of an odd number of -dot-separated decimal integers. @xref{Revision -numbers}. That is not the whole truth, however. For -efficiency reasons @sc{cvs} sometimes inserts an extra 0 -in the second rightmost position (1.2.3 becomes -1.2.0.3, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so -on). +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. -@sc{cvs} does a pretty good job at hiding these so -called magic branches, but in at least four places the -hiding is incomplete. +The messages are alphabetical, but introductory text +such as @samp{cvs update: } is not considered in +ordering them. -@itemize @bullet +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). + +@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 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 Most recently this was in the multibranch-5 test. +@c But I'm not sure it is specific to that test. + +@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). +@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. + +@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}. +@c Future versions of @sc{cvs} are +@c expected to dispense with the need for an external +@c patch program, but might as well not advertise +@c vaporware. +@c Even after that change is made, probably want to +@c preserve this message, see above about old messages. + +@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 +This message seems to be caused by a hard-to-track-down +bug in @sc{cvs} or the systems it runs on (we don't +know---we haven't tracked it down yet!). If you see it, +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} 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}. + +@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}. + +@item cvs [server aborted]: received broken pipe signal +This message seems to be caused by a hard-to-track-down +bug in @sc{cvs} or the systems it runs on (we don't +know---we haven't tracked it down yet!). It seems to +happen only after a @sc{cvs} command has completed, and +you should be able to just ignore the message. +However, if you have discovered information concerning its +cause, please let us know as described in @ref{BUGS}. + +@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}. 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 cacErrCodes.h} and you are ready +to @code{cvs commit}. If it detects conflicts it will +print a message saying so, will report @samp{C cacErrCodes.h}, +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 +solution is to make sure @code{rcsmerge} finds GNU +diff3. Depending on how @code{rcsmerge} was compiled, +it might be sufficient to place GNU diff3 in your +@code{PATH}, or it might be necessary to recompile +@code{rcsmerge} or find a binary distribution of +@code{rcsmerge} which looks in the @code{PATH}. +@c Should we mention the cvsaux binaries here? + +@item cvs commit: warning: editor session failed +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 +@sc{CVSEDITOR} environment variable to a small script +such as: + +@example +#!/bin/sh +vi $* +exit 0 +@end example + +@c "warning: foo was lost" and "no longer pertinent" (both normal). +@c Would be nice to write these up--they are +@c potentially confusing for the new user. +@end table + +@c --------------------------------------------------------------------- +@node Copying +@appendix GNU GENERAL PUBLIC LICENSE +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@heading TERMS AND CONDITIONS FOR COPYING, +@heading DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate 0 @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. +This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The ``Program'', below, +refers to any such program or work, and a ``work based on the Program'' +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification''.) Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. @item -The magic branch number appears in the output from -@code{cvs log}. This is much harder to fix, since -@code{cvs log} runs @code{rlog} (which is part of the -@sc{rcs} distribution), and modifying @code{rlog} to -know about magic branches would probably break someone's -habits (if they use branch 0 for their own purposes). +You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. @item -You cannot specify a symbolic branch name to @code{cvs log}. +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: +@enumerate a @item -You cannot specify a symbolic branch name to @code{cvs -admin}. +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. -@end itemize +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. -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: +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate -@example -$ cvs admin -NR4patches:1.4.2 numbers.c -@end example +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. -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). +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: -@c --------------------------------------------------------------------- -@node Copying -@appendix GNU GENERAL PUBLIC LICENSE -@c @include gpl.texinfo +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +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 of the License, 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. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details +type `show w'. +This is free software, and you are welcome to redistribute it +under certain conditions; type `show c' for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than @samp{show w} and +@samp{show c}; they could even be mouse-clicks or menu items---whatever +suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here is a sample; alter the names: + +@smallexample +Yoyodyne, Inc., hereby disclaims all copyright interest in the program +`Gnomovision' (which makes passes at compilers) written by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end smallexample + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. @c --------------------------------------------------------------------- @node Index diff --git a/contrib/cvs/doc/cvsclient.texi b/contrib/cvs/doc/cvsclient.texi index 0d61ac1..0d80788 100644 --- a/contrib/cvs/doc/cvsclient.texi +++ b/contrib/cvs/doc/cvsclient.texi @@ -9,13 +9,12 @@ This document describes the client/server protocol used by CVS. It does not describe how to use or administer client/server CVS; see the regular CVS manual for that. This is version @value{CVSVN} of the protocol -specification---@xref{Introduction} for more on what this version number +specification---@xref{Introduction}, for more on what this version number means. @menu * Introduction:: What is CVS and what is the client/server protocol for? * Goals:: Basic design decisions, requirements, scope, etc. -* Notes:: Notes on the current implementation * Protocol Notes:: Possible enhancements, limitations, etc. of the protocol * Connection and Authentication:: Various ways to connect to the server * Protocol:: Complete description of the protocol @@ -60,7 +59,7 @@ versions of this specification. Although the specification is currently maintained in conjunction with the CVS implementation, and carries the same version number, it also intends to document what is involved with interoperating with other implementations (such as other versions of -CVS); see @xref{Requirements}. This version number should not be used +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 @@ -75,62 +74,45 @@ Do not assume any access to the repository other than via this protocol. It does not depend on NFS, rdist, etc. @item -Providing a reliable transport is outside this protocol. It is expected -that it runs over TCP, UUCP, etc. +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 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}). +below about @samp{cvs kserver} and @samp{cvs pserver}). @item -This might be a first step towards adding transactions to CVS (i.e. a -set of operations is either executed atomically or none of them is -executed), improving the locking, or other features. The current server -implementation is a long way from being able to do any of these -things. The protocol, however, is not known to contain any defects -which would preclude them. +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 server never has to have any CVS locks in place while it is waiting -for communication with the client. This makes things robust in the face -of flaky networks. - -@item -Data is transferred in large chunks, which is necessary for good -performance. In fact, currently the client uploads all the data -(without waiting for server responses), and then waits for one server -response (which consists of a massive download of all the data). There -may be cases in which it is better to have a richer interraction, but -the need for the server to release all locks whenever it waits for the -client makes it complicated. +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. @end itemize -@node Notes -@chapter Notes on the Current Implementation - -The client is built in to the normal @code{cvs} program, triggered by a -@code{CVSROOT} variable containing a colon, for example -@code{cygnus.com:/rel/cvsfiles}. - -The client stores what is stored in checked-out directories (including -@file{CVS}). The way these are stored is totally compatible with -standard CVS. The server requires no storage other than the repository, -which also is totally compatible with standard CVS. - -The server is started by @code{cvs server}. There is no particularly -compelling reason for this rather than making it a separate program -which shares a lot of sources with cvs. - -The server can also be started by @code{cvs kserver}, in which case it -does an initial Kerberos authentication on stdin. If the authentication -succeeds, it subsequently runs identically to @code{cvs server}. - -The current server implementation can use up huge amounts of memory -when transmitting a lot of data over a slow link (i.e. the network is -slower than the server can generate the data). There is some -experimental code (see @code{SERVER_FLOWCONTROL} in options.h) which -should help significantly. - @node Protocol Notes @chapter Notes on the Protocol @@ -140,10 +122,10 @@ A number of enhancements are possible: @item The @code{Modified} request could be speeded up by sending diffs rather than entire files. The client would need some way to keep the version -of the file which was originally checked out, which would double client -disk space requirements or require coordination with editors (e.g. maybe -it could use emacs numbered backups). This would also allow local -operation of @code{cvs diff} without arguments. +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 Have the client keep a copy of some part of the repository. This allows @@ -153,8 +135,13 @@ the master copy at night (but if the master copy has been updated since the latest nightly re-sync, then it would read what it needs to from the master). -@item -Provide encryption using kerberos. +It isn't clear exactly how this should relate to a more general +multisite feature (in which one can modify the local copy even if the +network is down between the local and the master, and then they get +reconciled by a potentially manual process). Another variant of a +multisite feature would be where version history is cached to speed up +operations such as @code{cvs diff}, but in which checkins still must be +checked in to all sites, or to a master site. @item The current procedure for @code{cvs update} is highly sub-optimal if @@ -166,6 +153,38 @@ more, if changes in the repository mean it has to ask the client for more files), because it can't keep locks open while waiting for the network. Perhaps this whole thing is irrelevant if client-side repositories are implemented, and the rcsmerge is done by the client. + +@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). + @end itemize @node Connection and Authentication @@ -175,7 +194,7 @@ Connection and authentication occurs before the CVS protocol itself is started. There are several ways to connect. @table @asis -@item rsh +@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, @@ -202,7 +221,11 @@ implementation, by having inetd call "cvs pserver") which defaults to connects, sends the string @samp{BEGIN AUTH REQUEST}, a linefeed, the cvs root, a linefeed, the username, a linefeed, the password trivially encoded (see scramble.c in the cvs sources), a linefeed, the string -@samp{END AUTH REQUEST}, and a linefeed. The server responds with +@samp{END AUTH REQUEST}, and a linefeed. 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 server responds with @samp{I LOVE YOU} and a linefeed if the authentication is successful or @samp{I HATE YOU} and a linefeed if the authentication fails. After receiving @samp{I LOVE YOU}, the client proceeds with the cvs protocol. @@ -211,6 +234,17 @@ protocol, the procedure is the same, except @samp{BEGIN AUTH REQUEST} is replaced with @samp{BEGIN VERIFICATION REQUEST}, @samp{END AUTH REQUEST} is replaced with @samp{END VERIFICATION REQUEST}, and upon receipt of @samp{I LOVE YOU} the connection is closed rather than continuing. + +@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 the General Security Service (GSS) API or +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 Protocol @@ -223,10 +257,13 @@ to a horizontal tab. * Entries Lines:: * Modes:: * Filenames:: Conventions regarding filenames +* File transmissions:: How file contents are transmitted +* Strings:: Strings in various requests and responses * Requests:: * Responses:: * Example:: * Requirements:: +* Obsolete:: Former protocol features @end menu @node Entries Lines @@ -245,6 +282,9 @@ 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 @@ -299,30 +339,74 @@ the same answer (and what to do if future server ports are operating on a repository like e:/foo or CVS_ROOT:[FOO.BAR] has not been carefully thought out). -@node Requests -@section Requests +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 -newline, followed by the specified number of bytes of file contents. +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}. The length specified is that of the compressed -version of the file. +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 newline iff that file (or its -compressed form) ends with a newline. +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 Requests +@section Requests + +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. @table @code @item Root @var{pathname} \n Response expected: no. Tell the server which @code{CVSROOT} to use. -@var{pathname} must already exist; if creating a new root, use the -@code{init} request, not @code{Root}. @var{pathname} does not include -the hostname of the server, how to access the server, etc.; by the time -the CVS protocol is in use, connection, authentication, etc., are -already taken care of. +Note that @var{pathname} is a local directory and @emph{not} a fully +qualified @code{CVSROOT} variable. @var{pathname} must +already exist; if creating a new root, use the @code{init} request, not +@code{Root}. @var{pathname} does not include the hostname of the +server, how to access the server, etc.; by the time the CVS protocol is +in use, connection, authentication, etc., are already taken care of. @item Valid-responses @var{request-list} \n Response expected: no. @@ -333,24 +417,83 @@ request-list is a space separated list of tokens. Response expected: yes. Ask the server to send back a @code{Valid-requests} response. -@item Repository @var{repository} \n -Response expected: no. Tell the server what repository to use. This -should be a directory name from a previous server response. Note that -this both gives a default for @code{Entry } and @code{Modified } and -also for @code{ci} and the other commands; normal usage is to send a -@code{Repository } for each directory in which there will be an -@code{Entry } or @code{Modified }, and then a final @code{Repository } -for the original directory, then the command. - @item Directory @var{local-directory} \n -Additional data: @var{repository} \n. This is like @code{Repository}, -but the local name of the directory may differ from the repository name. +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. If the client uses this request, it affects the way the server returns pathnames; see @ref{Responses}. @var{local-directory} is relative to the top level at which the command is occurring (i.e. the last -@code{Directory} or @code{Repository} which is sent before the command). +@code{Directory} which is sent before the command); +to indicate that top level, @samp{.} should be send 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. @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 @@ -361,7 +504,7 @@ request. @item Static-directory \n Response expected: no. Tell the server that the directory most recently -specified with @code{Repository} or @code{Directory} should not have +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} @@ -369,11 +512,17 @@ responses. @item Sticky @var{tagspec} \n Response expected: no. Tell the server that the directory most recently -specified with @code{Repository} has a sticky tag or date @var{tagspec}. +specified with @code{Directory} has a sticky tag or date @var{tagspec}. The first character of @var{tagspec} is @samp{T} for a tag, or @samp{D} for a date. The remainder of @var{tagspec} contains the actual tag or date. +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 Checkin-prog @var{program} \n Response expected: no. Tell the server that the directory most recently specified with @code{Directory} has a checkin program @var{program}. @@ -389,44 +538,72 @@ Such a program would have been previously set with the @item Entry @var{entry-line} \n Response expected: no. Tell the server what version of a file is on the local machine. The name in @var{entry-line} is a name relative to the -directory most recently specified with @code{Repository}. If the user +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{Unchanged}, or @code{Lost} for that -file the meaning depends on whether @code{UseUnchanged} has been sent; -if it has been it means the file is lost, if not it means the file is -unchanged. +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 Modified @var{filename} \n Response expected: no. Additional data: mode, \n, file transmission. Send the server a copy of one locally modified file. @var{filename} is -relative to the most recent repository sent with @code{Repository}. If +relative to the most recent repository sent with @code{Directory}. If the user is operating on only some files in a directory, only those files need to be included. This can also be sent without @code{Entry}, if there is no entry for the file. -@item Lost @var{filename} \n -Response expected: no. Tell the server that @var{filename} no longer -exists. The name is relative to the most recent repository sent with -@code{Repository}. This is used for any case in which @code{Entry} is -being sent but the file no longer exists. If the client has issued the -@code{UseUnchanged} request, then this request is not used. +@item 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}, +@code{init}, 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 name is relative to the most -recent repository sent with @code{Repository}. This request can only be -issued if @code{UseUnchanged} has been sent. +recent repository sent with @code{Directory}. @item UseUnchanged \n -Response expected: no. Tell the server that the client will be -indicating unmodified files with @code{Unchanged}, and that files for -which no information is sent are nonexistent on the client side, not -unchanged. This is necessary for correct behavior since only the server -knows what possible files may exist, and thus what files are -nonexistent. +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. @item Notify @var{filename} \n +Response expected: no. Tell the server that a @code{edit} or @code{unedit} command has taken place. The server needs to send a @code{Notified} response, but such response is deferred until the next time that the server is sending @@ -435,26 +612,56 @@ responses. Response expected: no. Additional data: @var{notification-type} \t @var{time} \t @var{clienthost} \t @var{working-dir} \t @var{watches} \n @end example -where @var{notification-type} is @samp{E} for edit or @samp{U} for -unedit, @var{time} is the time at which the edit or unedit took place, +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 to set; if it is followed by \t then the tab and the -rest of the line are ignored. +temporary watches to set. If @var{watches} is followed by \t then the +\t and the rest of the line should be ignored, for future expansion. + +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. +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 -Tell the server that filenames should be matched against ignore patterns -in a case-insensitive fashion. Note that this does not apply to other -comparisons---for example the filenames given in @code{Entry} and -@code{Modified} requests for the same file must match in case regardless -of whether the @code{Case} request is sent. +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). @item Argument @var{text} \n Response expected: no. @@ -467,6 +674,7 @@ 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 @@ -474,7 +682,29 @@ graceful handling of @code{valid-requests}, it is probably better to make new global options separate requests, rather than trying to add them to this request. +@item 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. + @item Set @var{variable}=@var{value} \n +Response expected: no. Set a user variable @var{variable} to @var{value}. @item expand-modules \n @@ -484,16 +714,57 @@ that the server can assume that this is checkout or export, not rtag or rdiff; the latter do not access the working directory and thus have no need to expand modules on the client side. -@item co \n -@itemx ci \n +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 log \n -@itemx add \n @itemx remove \n -@itemx rdiff \n -@itemx rtag \n @itemx admin \n @itemx export \n @itemx history \n @@ -501,38 +772,128 @@ need to expand modules on the client side. @itemx editors \n @itemx annotate \n Response expected: yes. Actually do a cvs command. This uses any -previous @code{Argument}, @code{Repository}, @code{Entry}, -@code{Modified}, or @code{Lost} requests, if they have been sent. The -last @code{Repository} sent specifies the working directory at the time +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. -@itemx init @var{root-name} \n +@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 rdiff \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 this command; they are not used. Arguments to these +commands are module names, as described for @code{co}. + +@item init @var{root-name} \n Response expected: yes. If it doesn't already exist, create a @sc{cvs} -repository @var{root-name}. The @code{Root} request need not have been -previously sent. +repository @var{root-name}. Note that @var{root-name} is a local +directory and @emph{not} a fully qualified @code{CVSROOT} variable. The +@code{Root} request need not have been previously sent. -@itemx update \n +@item update \n Response expected: yes. Actually do a @code{cvs update} command. This -uses any previous @code{Argument}, @code{Repository}, @code{Entry}, -@code{Modified}, or @code{Lost} requests, if they have been sent. The -last @code{Repository} sent specifies the working directory at the time +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{Repository}, @code{Entry}, -@code{Modified}, or @code{Lost} requests, if they have been sent. The -last @code{Repository} sent specifies the working directory at the time +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 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 a pathname specified in +an @code{Argument} request cannot contain @samp{/}. There is no good +reason for this restriction, and it could be eliminated if someone took +the effort to rewrite the @code{add} code in the CVS server to not have +it. But in the meantime, the way to comply with it 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, until servers are fixed to send the correct +responses. + @item watch-on \n @itemx watch-off \n @itemx watch-add \n @@ -540,8 +901,8 @@ argument. Response expected: yes. Actually do the @code{cvs watch on}, @code{cvs watch off}, @code{cvs watch add}, and @code{cvs watch remove} commands, respectively. This uses any previous @code{Argument}, -@code{Repository}, @code{Entry}, @code{Modified}, or @code{Lost} -requests, if they have been sent. The last @code{Repository} sent +@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 @@ -555,16 +916,21 @@ expecting a response) sends back any responses pertaining to pending errors, pending @code{Notified} responses, etc. @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 -This request asks the server to filter files it sends to the client -through the @samp{gzip} program, using the specified level of -compression. If this request is not made, the server must not do any -compression. +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 @@ -589,23 +955,52 @@ When the client is done, it drops the connection. @section Responses After a command which expects a response, the server sends however many -of the following responses are appropriate. Pathnames are of the actual -files operated on (i.e. they do not contain @samp{,v} endings), and are -suitable for use in a subsequent @code{Repository} request. However, if -the client has used the @code{Directory} request, then it is instead a -local directory name relative to the directory in which the command was -given (i.e. the last @code{Directory} before the command). Then a -newline and a repository name (the pathname which is sent if -@code{Directory} is not used). Then the slash and the filename. For -example, for a file @file{i386.mh} which is in the local directory -@file{gas.clean/config} and for which the repository is -@file{/rel/cvsfiles/devo/gas/config}: +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). + +@c FIXME: should better document when the specified repository needs to +@c end in "/.". +In the following, @var{pathname} 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. + Any response always ends with @samp{error} or @samp{ok}. This indicates that the response is over. @@ -631,7 +1026,34 @@ 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. +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, @@ -639,14 +1061,38 @@ with the one difference that after the new copy of the file is enclosed, it will still not be up to date. Used for the results of a merge, with or without conflicts. -@item Patched @var{pathname} \n +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 a patch produced by @samp{diff -u}. This client must -apply this patch, using the @samp{patch} program, to the existing file. -This will only be used when the client has an exact copy of an earlier -revision of a file. This response is only used if the @code{update} -command is given the @samp{-u} argument. +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 @@ -669,6 +1115,12 @@ 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}). @@ -692,8 +1144,10 @@ Like @code{Set-static-directory}, but clear, not set, the flag. Additional data: @var{tagspec} \n. Tell the client to set a sticky tag or date, which should be supplied with the @code{Sticky} request for future operations. @var{pathname} ends in a slash; its purpose is to -specify a directory, not a file within a directory. The first character -of @var{tagspec} is @samp{T} for a tag, or @samp{D} for a date. The +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 @@ -738,6 +1192,14 @@ A one-line message for the user. @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 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 @@ -753,72 +1215,182 @@ The command completed successfully. @node Example @section Example -Lines beginning with @samp{c>} are sent by the client; lines beginning -with @samp{s>} are sent by the server; lines beginning with @samp{#} are -not part of the actual exchange. +@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 RFC822-style BNF (I fear that would be less clear than +@c what we do now, however). Plus what about IETF terminology (SHOULD, +@c MUST, etc.) 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 reponses 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 -c> Root /rel/cvsfiles -# In actual practice the lists of valid responses and requests would -# be longer -c> Valid-responses Updated Checked-in M ok error -c> valid-requests -s> Valid-requests Root co Modified Entry Repository ci Argument Argumentx -s> ok -# cvs co devo/foo -c> Argument devo/foo -c> co -s> Updated /rel/cvsfiles/devo/foo/foo.c -s> /foo.c/1.4/Mon Apr 19 15:36:47 1993 Mon Apr 19 15:36:47 1993// -s> 26 -s> int mein () @{ abort (); @} -s> Updated /rel/cvsfiles/devo/foo/Makefile -s> /Makefile/1.2/Mon Apr 19 15:36:47 1993 Mon Apr 19 15:36:47 1993// -s> 28 -s> foo: foo.c -s> $(CC) -o foo $< -s> ok -# In actual practice the next part would be a separate connection. -# Here it is shown as part of the same one. -c> Repository /rel/cvsfiles/devo/foo -# foo.c relative to devo/foo just set as Repository. -c> Entry /foo.c/1.4/Mon Apr 19 15:36:47 1993 Mon Apr 19 15:36:47 1993// -c> Entry /Makefile/1.2/Mon Apr 19 15:36:47 1993 Mon Apr 19 15:36:47 1993// -c> Modified foo.c -c> 26 -c> int main () @{ abort (); @} -# cvs ci -m <log message> foo.c -c> Argument -m -c> Argument Well, you see, it took me hours and hours to find this typo and I -c> Argumentx searched and searched and eventually had to ask John for help. -c> Argument foo.c -c> ci -s> Checked-in /rel/cvsfiles/devo/foo/foo.c -s> /foo.c/1.5/ Mon Apr 19 15:54:22 CDT 1993// -s> M Checking in foo.c; -s> M /cygint/rel/cvsfiles/devo/foo/foo.c,v <-- foo.c -s> M new revision: 1.5; previous revision: 1.4 -s> M done -s> ok +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 and it is considered reasonable behavior to completely fail -to work if you are connected with an implementation which attempts to -not support them. Requests: Root, Valid-responses, valid-requests, -Repository, Entry, Modified, Argument, Argumentx, ci, co, update. -Responses: ok, error, Valid-requests, Checked-in, Updated, Merged, -Removed, M, E. - -Failure to support the Directory, UseUnchanged, and Unchanged requests -is deprecated. CVS 1.5 and later have supported these requests and in -the future it will be considered reasonable behavior to completely -fail to work with an implementation which attempts to not support -them. Support for the Repository and Lost requests is deprecated; CVS -clients 1.5 and later will not use them if communicating with a server -which supports Directory and UseUnchanged. +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. @bye |
