diff options
Diffstat (limited to 'contrib/cvs/doc')
| -rw-r--r-- | contrib/cvs/doc/ChangeLog | 42 | ||||
| -rw-r--r-- | contrib/cvs/doc/cvs.texinfo | 307 | ||||
| -rw-r--r-- | contrib/cvs/doc/cvsclient.texi | 2 |
3 files changed, 332 insertions, 19 deletions
diff --git a/contrib/cvs/doc/ChangeLog b/contrib/cvs/doc/ChangeLog index 3fd4433..9a01d1b 100644 --- a/contrib/cvs/doc/ChangeLog +++ b/contrib/cvs/doc/ChangeLog @@ -1,3 +1,45 @@ +1998-03-04 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Special Files): Add notes about client/server CVS + and hard links across directories. + +1998-03-01 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Keeping a checked out copy): The magic loginfo + incantation isn't too likely to work except on unix. + +1998-02-23 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (user-defined logging): Double "@" literal. + +1998-02-18 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (user-defined logging): Add taginfo example. + +1998-02-04 Tim Pierce <twp@skepsis.com> + + * cvs.texinfo (config): PreservePermissions variable. + (Special Files): New. + (Editing files): Add note about PreservePermissions. + +Tue Feb 10 18:07:35 1998 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Connection): New node. + + * cvsclient.texi (Protocol): Fix typo (lots -> lost). + +Sun Feb 8 21:39:22 1998 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Invoking CVS): For admin -b, point to the section + where we talk about reverting to vendor branch. + + * cvs.texinfo (Invoking CVS, rdiff options): Document rdiff -V + option as obsolete, since it was made a fatal error some time ago. + + * cvs.texinfo (Invoking CVS): Add global options, keywords, and + keyword substitution modes. Wording fix in reference to --help + and Index. + Wed Jan 28 23:09:39 1998 Jim Kingdon <kingdon@harvey.cyclic.com> * cvs.texinfo (Excluding directories): Add index entry for "!". diff --git a/contrib/cvs/doc/cvs.texinfo b/contrib/cvs/doc/cvs.texinfo index e50a793..5558538 100644 --- a/contrib/cvs/doc/cvs.texinfo +++ b/contrib/cvs/doc/cvs.texinfo @@ -152,6 +152,7 @@ CVS and the Real World. * Keyword substitution:: CVS can include the revision inside the file * Tracking sources:: Tracking third-party sources * Builds:: Issues related to CVS and builds +* Special Files:: Devices, links and other non-regular files References. ----------- @@ -724,7 +725,7 @@ they should be in separate locations. @c /home/joe/sources. But this node is too long @c as it is; need a little reorganization... -@cindex :local: +@cindex :local:, setting up @sc{Cvs} can access a repository by a variety of means. It might be on the local computer, or it might be on a computer across the room or across the world. @@ -2058,8 +2059,8 @@ for example @file{/usr/local/bin/cvs-1.6}. There is no need to edit @code{inetd.conf} or start a @sc{cvs} server daemon. -@cindex :server: -@cindex :ext: +@cindex :server:, setting up +@cindex :ext:, setting up 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. @@ -2284,7 +2285,7 @@ passwd} command. @cindex Login (subcommand) @cindex password client, using @cindex authenticated client, using -@cindex :pserver: +@cindex :pserver:, setting up 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 @@ -2417,7 +2418,7 @@ security, get Kerberos. @cindex GSSAPI @cindex security, GSSAPI -@cindex :gserver: +@cindex :gserver:, setting up GSSAPI is a generic interface to network security systems such as Kerberos 5. If you have a working GSSAPI library, you can have @@ -2470,7 +2471,7 @@ cvs -d :gserver:chainsaw.yard.com:/usr/local/cvsroot checkout foo @cindex kerberos @cindex security, kerberos -@cindex :kserver: +@cindex :kserver:, setting up The easiest way to use kerberos is to use the kerberos @code{rsh}, as described in @ref{Connecting via rsh}. The main disadvantage of using rsh is that all the data @@ -4731,6 +4732,21 @@ pairs of @var{filename} @var{revision}. A non-zero exit of the filter program will cause the tag to be aborted. +Here is an example of using taginfo to log tag and rtag +commands. In the taginfo file put: + +@example +ALL /usr/local/cvsroot/CVSROOT/loggit +@end example + +Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the +following script: + +@example +#!/bin/sh +echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog +@end example + @node annotate @section Annotate command @cindex annotate (subcommand) @@ -5841,6 +5857,14 @@ receive notifications, she should specify @code{-a none}. The @var{files} and options are processed as for the @code{cvs watch} commands. +@strong{Caution:} If the @var{PreservePermissions} +option is enabled in the repository (@pxref{config}), +CVS will not change the permissions on any of the +@var{files}. The reason for this change is to ensure +that using @samp{cvs edit} does not interfere with the +ability to store file permissions in the CVS +repository. + @end deffn Normally when you are done with a set of changes, you @@ -6740,6 +6764,67 @@ is Odin (see @c can work with CVS. @c --------------------------------------------------------------------- +@node Special Files +@chapter Special Files + +In normal circumstances, CVS works only with regular +files. Every file in a project is assumed to be +persistent; it must be possible to open, read and close +them; and so on. CVS also ignores file permissions and +ownerships, leaving such issues to be resolved by the +developer at installation time. In other words, it is +not possible to "check in" a device into a repository; +if the device file cannot be opened, CVS will refuse to +handle it. Files also lose their ownerships and +permissions during repository transactions. + +If the configuration variable @var{PreservePermissions} +(@pxref{config}) is set in the repository, CVS will +preserve file permissions and ownership across +repository transactions, and will permit checkin and +checkout of special files and symbolic links. + +Using this option affects the behavior of CVS in +several ways. First, some of the new operations +supported by CVS are not accessible to all users. In +particular, file ownership and special file +characteristics may only be changed by the superuser. +When the @var{PreservePermissions} configuration +variable is set, therefore, users will have to be +`root' in order to perform CVS operations. + +A more subtle difference is that CVS considers a file +to have changed only if its contents have changed +(specifically, if the modification time of the working +file does not match that of the repository's file). +Therefore, if only the permissions or ownership have +changed, or if a device's major or minor numbers have +changed, CVS will not notice. In order to commit such +a change to the repository, you must force the commit +with @samp{cvs commit -f}. This also means that if a +file's permissions have changed and the repository file +is newer than the working copy, performing @samp{cvs +update} will silently change the permissions on the +working copy. + +It is worth noting that only regular files may +be merged, for reasons that hopefully are obvious. If +@samp{cvs update} or @samp{cvs checkout -j} attempts to +merge a symbolic link with a regular file, or two +device files for different kinds of devices, CVS will +report a conflict and refuse to perform the merge. At +the same time, @samp{cvs diff} will not report any +differences between these files, since no meaningful +textual comparisons can be made on files which contain +no text. + +The PreservePermissions features do not work with +client/server @sc{cvs}. Another limitation is that +hard links must be to other files within the same +directory; hard links across directories are not +supported. + +@c --------------------------------------------------------------------- @node CVS commands @appendix Guide to CVS commands @@ -9117,7 +9202,9 @@ you should probably not use @samp{-u}. @item -V @var{vn} Expand keywords according to the rules current in @sc{rcs} version @var{vn} (the expansion format changed with -@sc{rcs} version 5). +@sc{rcs} version 5). Note that this option is no +longer accepted. CVS will always expand keywords the +way that @sc{rcs} version 5 does. @end table @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . @@ -9741,9 +9828,121 @@ description of the @samp{-I} option, and 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}. +described in detail. For other references run the +@code{cvs --help} command, or see @ref{Index}. + +A @sc{cvs} command looks like: + +@example +cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ] +@end example + +Global options: + +@table @code +@item --allow-root=@var{rootdir} +Specify legal @sc{cvsroot} directory (server only) (not +in @sc{cvs} 1.9 and older). See @ref{Password +authentication server}. + +@item -a +Authenticate all communication (client only) (not in @sc{cvs} +1.9 and older). See @ref{Global options}. + +@item -b +Specify RCS location (@sc{cvs} 1.9 and older). See +@ref{Global options}. + +@item -d @var{root} +Specify the @sc{cvsroot}. See @ref{Repository}. + +@item -e @var{editor} +Edit messages with @var{editor}. See @ref{Committing +your changes}. + +@item -f +Do not read the @file{~/.cvsrc} file. See @ref{Global +options}. + +@item -H +@itemx --help +Print a help message. See @ref{Global options}. + +@item -l +Do not log in CVSROOT/history file. See @ref{Global +options}. + +@item -n +Do not change any files. See @ref{Global options}. + +@item -Q +Cause the command to be really quiet. See @ref{Global options}. + +@item -q +Cause the command to be somewhat quiet. See @ref{Global options}. + +@item -r +Make new working files files read-only. See @ref{Global options}. + +@item -s @var{variable}=@var{value} +Set a user variable. See @ref{Variables}. + +@item -T @var{tempdir} +Put temporary files in @var{tempdir}. See @ref{Global +options}. + +@item -t +Trace @sc{cvs} execution. See @ref{Global options}. + +@item -v +@item --version +Display version and copyright information for @sc{cvs}. + +@item -w +Make new working files read-write. See @ref{Global +options}. + +@item -x +Encrypt all communication (client only). See +@ref{Global options}. + +@item -z @var{gzip-level} +Set the compression level (client only). +@c FIXME: what are the valid values for gzip-level. +@c And shouldn't this be documented in at least a +@c little bit of detail somewhere? + +@end table + +Keyword expansion modes (@pxref{Substitution modes}): + +@example +-kkv $@asis{}Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp $ +-kkvl $@asis{}Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ +-kk $@asis{}Id$ +-kv file1,v 1.1 1993/12/09 03:21:13 joe Exp +-ko @i{no expansion} +-kb @i{no expansion, file is binary} +@end example + +Keywords (@pxref{Keyword list}): + +@example +$@asis{}Author: joe $ +$@asis{}Date: 1993/12/09 03:21:13 $ +$@asis{}Header: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ +$@asis{}Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ +$@asis{}Locker: harry $ +$@asis{}Name: snapshot_1_14 $ +$@asis{}RCSfile: file1,v $ +$@asis{}Revision: 1.1 $ +$@asis{}Source: /home/files/file1,v $ +$@asis{}State: Exp $ +$@asis{}Log: file1,v $ +Revision 1.1 1993/12/09 03:30:17 joe +Initial revision + +@end example @c The idea behind this table is that we want each item @c to be a sentence or two at most. Preferably a @@ -9752,6 +9951,8 @@ described in detail. Other relevant references are the @c In some cases refs to "foo options" are just to get @c this thing written quickly, not because the "foo @c options" node is really the best place to point. +Commands, command options, and command arguments: + @table @code @item add [@var{options}] [@var{files}@dots{}] Add a new file/directory. See @ref{Adding files}. @@ -9773,9 +9974,7 @@ Administration of history files in the repository. See @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. +Set default branch. See @ref{Reverting local changes}. @item -c@var{string} Set comment leader. @@ -10209,7 +10408,7 @@ Top two diffs - last change made to the file. See Unidiff output format. See @ref{rdiff options}. @item -V @var{vers} -Use RCS Version @var{vers} for keyword expansion. See +Use RCS Version @var{vers} for keyword expansion (obsolete). See @ref{rdiff options}. @end table @@ -11493,7 +11692,7 @@ must be run in the background. @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): +Here is an example for unix (this should all be on one line): @example ^cyclic-pages (date; cat; (sleep 2; cd /u/www/local-docs; @@ -11811,6 +12010,14 @@ for users in the system's user database if not found in pserver users must exist in @file{CVSROOT/passwd}. The default is @samp{yes}. For more on pserver, see @ref{Password authenticated}. + +@cindex PreservePermissions, in CVSROOT/config +@item PreservePermissions=@var{value} +Enable support for saving special device files, +symbolic links, file permissions and ownerships in the +repository. The default value is @samp{no}. +@xref{Special Files} for the full implications of using +this keyword. @end table @c --------------------------------------------------------------------- @@ -12060,6 +12267,7 @@ mentioned there. @menu * Error messages:: Partial list of CVS errors +* Connection:: Trouble making a connection to a CVS server * Other problems:: Problems not readily listed by error message @end menu @@ -12394,12 +12602,75 @@ exit 0 @c potentially confusing for the new user. @end table +@node Connection +@appendixsec Trouble making a connection to a CVS server + +This section concerns what to do if you are having +trouble making a connection to a @sc{cvs} server. If +you are running the @sc{cvs} command line client +running on Windows, first upgrade the client to +@sc{cvs} 1.9.12 or later. The error reporting in +earlier versions provided much less information about +what the problem was. If the client is non-Windows, +@sc{cvs} 1.9 should be fine. + +If the error messages are not sufficient to track down +the problem, the next steps depend largely on which +access method you are using. + +@table @code +@cindex :ext:, troubleshooting +@item :ext: +Try running the rsh program from the command line. For +example: "rsh servername cvs -v" should print @sc{cvs} +version information. If this doesn't work, you need to +fix it before you can worry about @sc{cvs} problems. + +@cindex :server:, troubleshooting +@item :server: +You don't need a command line rsh program to use this +access method, but if you have an rsh program around, +it may be useful as a debugging tool. Follow the +directions given for :ext:. + +@cindex :pserver:, troubleshooting +@item :pserver: +One good debugging tool is to "telnet servername +2401". After connecting, send any text (for example +"foo" followed by return). If @sc{cvs} is working +correctly, it will respond with + +@example +cvs [pserver aborted]: bad auth protocol start: foo +@end example + +If this fails to work, then make sure inetd is working +right. Change the invocation in inetd.conf to run the +echo program instead of cvs. For example: + +@example +2401 stream tcp nowait root /bin/echo echo hello +@end example + +After making that change and instructing inetd to +re-read its configuration file, "telnet servername +2401" should show you the text hello and then the +server should close the connection. If this doesn't +work, you need to fix it before you can worry about +@sc{cvs} problems. + +On AIX systems, the system will often have its own +program trying to use port 2401. This is AIX's problem +in the sense that port 2401 is registered for use with +@sc{cvs}. I hear that there is an AIX patch available +to address this problem. +@end table + @node Other problems @appendixsec Other common problems -Here is a list of problems which cannot be readily -looked up based on an error message. They are in no -particular order. +Here is a list of problems which do not fit into the +above categories. They are in no particular order. @itemize @bullet @item diff --git a/contrib/cvs/doc/cvsclient.texi b/contrib/cvs/doc/cvsclient.texi index 35fe39b..56577c2 100644 --- a/contrib/cvs/doc/cvsclient.texi +++ b/contrib/cvs/doc/cvsclient.texi @@ -309,7 +309,7 @@ out what the other supports before exchanging large amounts of data (such as file contents). @c Hmm, having 3 sections in this menu makes a certain amount of sense -@c but that structure gets lots in the printed manual (not sure about +@c but that structure gets lost in the printed manual (not sure about @c HTML). Perhaps there is a better way. @menu |
