/contrib/cvs/doc/cvsclient.texi
https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 2080 lines · 1788 code · 292 blank · 0 comment · 0 complexity · d0204570b0f364de896fd056ee1a9ca7 MD5 · raw file
Large files are truncated click here to view the full file
- \input texinfo @c -*- texinfo -*-
- @setfilename cvsclient.info
- @include version-client.texi
- @dircategory Programming
- @direntry
- * cvsclient: (cvsclient). The CVS client/server protocol.
- @end direntry
- @node Top
- @top CVS Client/Server
- This document describes the client/server protocol used by CVS. It does
- not describe how to use or administer client/server CVS; see the regular
- CVS manual for that. This is version @value{VERSION} of the protocol
- specification---@xref{Introduction}, for more on what this version number
- means.
- @menu
- * Introduction:: What is CVS and what is the client/server protocol for?
- * Goals:: Basic design decisions, requirements, scope, etc.
- * Connection and Authentication:: Various ways to connect to the server
- * Password scrambling:: Scrambling used by pserver
- * Protocol:: Complete description of the protocol
- * Protocol Notes:: Possible enhancements, limitations, etc. of the protocol
- @end menu
- @node Introduction
- @chapter Introduction
- CVS is a version control system (with some additional configuration
- management functionality). It maintains a central @dfn{repository}
- which stores files (often source code), including past versions,
- information about who modified them and when, and so on. People who
- wish to look at or modify those files, known as @dfn{developers}, use
- CVS to @dfn{check out} a @dfn{working directory} from the repository, to
- @dfn{check in} new versions of files to the repository, and other
- operations such as viewing the modification history of a file. If
- developers are connected to the repository by a network, particularly a
- slow or flaky one, the most efficient way to use the network is with the
- CVS-specific protocol described in this document.
- Developers, using the machine on which they store their working
- directory, run the CVS @dfn{client} program. To perform operations
- which cannot be done locally, it connects to the CVS @dfn{server}
- program, which maintains the repository. For more information on how
- to connect see @ref{Connection and Authentication}.
- This document describes the CVS protocol. Unfortunately, it does not
- yet completely document one aspect of the protocol---the detailed
- operation of each CVS command and option---and one must look at the CVS
- user documentation, @file{cvs.texinfo}, for that information. The
- protocol is non-proprietary (anyone who wants to is encouraged to
- implement it) and an implementation, known as CVS, is available under
- the GNU Public License. The CVS distribution, containing this
- implementation, @file{cvs.texinfo}, and a copy (possibly more or less up
- to date than what you are reading now) of this document,
- @file{cvsclient.texi}, can be found at the usual GNU FTP sites, with a
- filename such as @file{cvs-@var{version}.tar.gz}.
- This is version @value{VERSION} of the protocol specification. This
- version number is intended only to aid in distinguishing different
- versions of this specification. Although the specification is currently
- maintained in conjunction with the CVS implementation, and carries the
- same version number, it also intends to document what is involved with
- interoperating with other implementations (such as other versions of
- CVS); see @ref{Requirements}. This version number should not be used
- by clients or servers to determine what variant of the protocol to
- speak; they should instead use the @code{valid-requests} and
- @code{Valid-responses} mechanism (@pxref{Protocol}), which is more
- flexible.
- @node Goals
- @chapter Goals
- @itemize @bullet
- @item
- Do not assume any access to the repository other than via this protocol.
- It does not depend on NFS, rdist, etc.
- @item
- Providing a reliable transport is outside this protocol. The protocol
- expects a reliable transport that is transparent (that is, there is no
- translation of characters, including characters such as
- linefeeds or carriage returns), and can transmit all 256 octets (for
- example for proper handling of binary files, compression, and
- encryption). The encoding of characters specified by the protocol (the
- names of requests and so on) is the invariant ISO 646 character set (a
- subset of most popular character sets including ASCII and others). For
- more details on running the protocol over the TCP reliable transport,
- see @ref{Connection and Authentication}.
- @item
- Security and authentication are handled outside this protocol (but see
- below about @samp{cvs kserver} and @samp{cvs pserver}).
- @item
- The protocol makes it possible for updates to be atomic with respect to
- checkins; that is if someone commits changes to several files in one cvs
- command, then an update by someone else would either get all the
- changes, or none of them. The current @sc{cvs} server can't do this,
- but that isn't the protocol's fault.
- @item
- The protocol is, with a few exceptions, transaction-based. That is, the
- client sends all its requests (without waiting for server responses),
- and then waits for the server to send back all responses (without
- waiting for further client requests). This has the advantage of
- minimizing network turnarounds and the disadvantage of sometimes
- transferring more data than would be necessary if there were a richer
- interaction. Another, more subtle, advantage is that there is no need
- for the protocol to provide locking for features such as making checkins
- atomic with respect to updates. Any such locking can be handled
- entirely by the server. A good server implementation (such as the
- current @sc{cvs} server) will make sure that it does not have any such
- locks in place whenever it is waiting for communication with the client;
- this prevents one client on a slow or flaky network from interfering
- with the work of others.
- @item
- It is a general design goal to provide only one way to do a given
- operation (where possible). For example, implementations have no choice
- about whether to terminate lines with linefeeds or some other
- character(s), and request and response names are case-sensitive. This
- is to enhance interoperability. If a protocol allows more than one way
- to do something, it is all too easy for some implementations to support
- only some of them (perhaps accidentally).
- @c I vaguely remember reading, probably in an RFC, about the problems
- @c that were caused when some people decided that SMTP should accept
- @c other line termination (in the message ("DATA")?) than CRLF. However, I
- @c can't seem to track down the reference.
- @end itemize
- @node Connection and Authentication
- @chapter How to Connect to and Authenticate Oneself to the CVS server
- Connection and authentication occurs before the CVS protocol itself is
- started. There are several ways to connect.
- @table @asis
- @item server
- If the client has a way to execute commands on the server, and provide
- input to the commands and output from them, then it can connect that
- way. This could be the usual rsh (port 514) protocol, Kerberos rsh,
- SSH, or any similar mechanism. The client may allow the user to specify
- the name of the server program; the default is @code{cvs}. It is
- invoked with one argument, @code{server}. Once it invokes the server,
- the client proceeds to start the cvs protocol.
- @item kserver
- The kerberized server listens on a port (in the current implementation,
- by having inetd call "cvs kserver") which defaults to 1999. The client
- connects, sends the usual kerberos authentication information, and then
- starts the cvs protocol. Note: port 1999 is officially registered for
- another use, and in any event one cannot register more than one port for
- CVS, so GSS-API (see below) is recommended instead of kserver as a way
- to support kerberos.
- @item pserver
- The name @dfn{pserver} is somewhat confusing. It refers to both a
- generic framework which allows the CVS protocol to support several
- authentication mechanisms, and a name for a specific mechanism which
- transfers a username and a cleartext password. Servers need not support
- all mechanisms, and in fact servers will typically want to support only
- those mechanisms which meet the relevant security needs.
- The pserver server listens on a port (in the current
- implementation, by having inetd call "cvs pserver") which defaults to
- 2401 (this port is officially registered). The client
- connects, and sends the following:
- @itemize @bullet
- @item
- the string @samp{BEGIN AUTH REQUEST}, a linefeed,
- @item
- the cvs root, a linefeed,
- @item
- the username, a linefeed,
- @item
- the password trivially encoded (see @ref{Password scrambling}), a
- linefeed,
- @item
- the string @samp{END AUTH REQUEST}, and a linefeed.
- @end itemize
- The client must send the
- identical string for cvs root both here and later in the
- @code{Root} request of the cvs
- protocol itself. Servers are encouraged to enforce this restriction.
- The possible server responses (each of which is followed by a linefeed)
- are the following. Note that although there is a small similarity
- between this authentication protocol and the cvs protocol, they are
- separate.
- @table @code
- @item I LOVE YOU
- The authentication is successful. The client proceeds with the cvs
- protocol itself.
- @item I HATE YOU
- The authentication fails. After sending this response, the server may
- close the connection. It is up to the server to decide whether to give
- this response, which is generic, or a more specific response using
- @samp{E} and/or @samp{error}.
- @item E @var{text}
- Provide a message for the user. After this response, the authentication
- protocol continues with another response. Typically the server will
- provide a series of @samp{E} responses followed by @samp{error}.
- Compatibility note: @sc{cvs} 1.9.10 and older clients will print
- @code{unrecognized auth response} and @var{text}, and then exit, upon
- receiving this response.
- @item error @var{code} @var{text}
- The authentication fails. After sending this response, the server may
- close the connection. The @var{code} is a code describing why it
- failed, intended for computer consumption. The only code currently
- defined is @samp{0} which is nonspecific, but clients must silently
- treat any unrecognized codes as nonspecific.
- The @var{text} should be supplied to the
- user. Compatibility note: @sc{cvs} 1.9.10 and older clients will print
- @code{unrecognized auth response} and @var{text}, and then exit, upon
- receiving this response.
- Note that @var{text} for this response, or the @var{text} in an @code{E}
- response, is not designed for machine parsing. More vigorous use of
- @var{code}, or future extensions, will be needed to prove a cleaner
- machine-parseable indication of what the error was.
- @end table
- @c If you are thinking of putting samp or code around BEGIN AUTH REQUEST
- @c and friends, watch for overfull hboxes.
- If the client wishes to merely authenticate without starting the cvs
- protocol, the procedure is the same, except BEGIN AUTH REQUEST is
- replaced with BEGIN VERIFICATION REQUEST, END AUTH REQUEST
- is replaced with END VERIFICATION REQUEST, and upon receipt of
- I LOVE YOU the connection is closed rather than continuing.
- Another mechanism is GSSAPI authentication. GSSAPI is a
- generic interface to security services such as kerberos. GSSAPI is
- specified in RFC2078 (GSSAPI version 2) and RFC1508 (GSSAPI version 1);
- we are not aware of differences between the two which affect the
- protocol in incompatible ways, so we make no attempt to specify one
- version or the other.
- The procedure here is to start with @samp{BEGIN
- GSSAPI REQUEST}. GSSAPI authentication information is then exchanged
- between the client and the server. Each packet of information consists
- of a two byte big-endian length, followed by that many bytes of data.
- After the GSSAPI authentication is complete, the server continues with
- the responses described above (@samp{I LOVE YOU}, etc.).
- @item future possibilities
- There are a nearly unlimited number of ways to connect and authenticate.
- One might want to allow access based on IP address (similar to the usual
- rsh protocol but with different/no restrictions on ports < 1024), to
- adopt mechanisms such as Pluggable Authentication Modules (PAM), to
- allow users to run their own servers under their own usernames without
- root access, or any number of other possibilities. The way to add
- future mechanisms, for the most part, should be to continue to use port
- 2401, but to use different strings in place of @samp{BEGIN AUTH
- REQUEST}.
- @end table
- @node Password scrambling
- @chapter Password scrambling algorithm
- The pserver authentication protocol, as described in @ref{Connection and
- Authentication}, trivially encodes the passwords. This is only to
- prevent inadvertent compromise; it provides no protection against even a
- relatively unsophisticated attacker. For comparison, HTTP Basic
- Authentication (as described in RFC2068) uses BASE64 for a similar
- purpose. CVS uses its own algorithm, described here.
- The scrambled password starts with @samp{A}, which serves to identify
- the scrambling algorithm in use. After that follows a single octet for
- each character in the password, according to a fixed encoding. The
- values are shown here, with the encoded values in decimal. Control
- characters, space, and characters outside the invariant ISO 646
- character set are not shown; such characters are not recommended for use
- in passwords. There is a long discussion of character set issues in
- @ref{Protocol Notes}.
- @example
- 0 111 P 125 p 58
- ! 120 1 52 A 57 Q 55 a 121 q 113
- " 53 2 75 B 83 R 54 b 117 r 32
- 3 119 C 43 S 66 c 104 s 90
- 4 49 D 46 T 124 d 101 t 44
- % 109 5 34 E 102 U 126 e 100 u 98
- & 72 6 82 F 40 V 59 f 69 v 60
- ' 108 7 81 G 89 W 47 g 73 w 51
- ( 70 8 95 H 38 X 92 h 99 x 33
- ) 64 9 65 I 103 Y 71 i 63 y 97
- * 76 : 112 J 45 Z 115 j 94 z 62
- + 67 ; 86 K 50 k 93
- , 116 < 118 L 42 l 39
- - 74 = 110 M 123 m 37
- . 68 > 122 N 91 n 61
- / 87 ? 105 O 35 _ 56 o 48
- @end example
- @node Protocol
- @chapter The CVS client/server protocol
- In the following, @samp{\n} refers to a linefeed and @samp{\t} refers to
- a horizontal tab; @dfn{requests} are what the client sends and
- @dfn{responses} are what the server sends. In general, the connection is
- governed by the client---the server does not send responses without
- first receiving requests to do so; see @ref{Response intro} for more
- details of this convention.
- It is typical, early in the connection, for the client to transmit a
- @code{Valid-responses} request, containing all the responses it
- supports, followed by a @code{valid-requests} request, which elicits
- from the server a @code{Valid-requests} response containing all the
- requests it understands. In this way, the client and server each find
- out what the other supports before exchanging large amounts of data
- (such as file contents).
- @c Hmm, having 3 sections in this menu makes a certain amount of sense
- @c but that structure gets lost in the printed manual (not sure about
- @c HTML). Perhaps there is a better way.
- @menu
- General protocol conventions:
- * Entries Lines:: Transmitting RCS data
- * File Modes:: Read, write, execute, and possibly more...
- * Filenames:: Conventions regarding filenames
- * File transmissions:: How file contents are transmitted
- * Strings:: Strings in various requests and responses
- * Dates:: Times and dates
- The protocol itself:
- * Request intro:: General conventions relating to requests
- * Requests:: List of requests
- * Response intro:: General conventions relating to responses
- * Response pathnames:: The "pathname" in responses
- * Responses:: List of responses
- * Text tags:: More details about the MT response
- An example session, and some further observations:
- * Example:: A conversation between client and server
- * Requirements:: Things not to omit from an implementation
- * Obsolete:: Former protocol features
- @end menu
- @node Entries Lines
- @section Entries Lines
- Entries lines are transmitted as:
- @example
- / @var{name} / @var{version} / @var{conflict} / @var{options} / @var{tag_or_date}
- @end example
- @var{tag_or_date} is either @samp{T} @var{tag} or @samp{D} @var{date}
- or empty. If it is followed by a slash, anything after the slash
- shall be silently ignored.
- @var{version} can be empty, or start with @samp{0} or @samp{-}, for no
- user file, new user file, or user file to be removed, respectively.
- @c FIXME: should distinguish sender and receiver behavior here; the
- @c "anything else" and "does not start with" are intended for future
- @c expansion, and we should specify a sender behavior.
- @var{conflict}, if it starts with @samp{+}, indicates that the file had
- conflicts in it. The rest of @var{conflict} is @samp{=} if the
- timestamp matches the file, or anything else if it doesn't. If
- @var{conflict} does not start with a @samp{+}, it is silently ignored.
- @var{options} signifies the keyword expansion options (for example
- @samp{-ko}). In an @code{Entry} request, this indicates the options
- that were specified with the file from the previous file updating
- response (@pxref{Response intro}, for a list of file updating
- responses); if the client is specifying the @samp{-k} or @samp{-A}
- option to @code{update}, then it is the server which figures out what
- overrides what.
- @node File Modes
- @section File Modes
- A mode is any number of repetitions of
- @example
- @var{mode-type} = @var{data}
- @end example
- separated by @samp{,}.
- @var{mode-type} is an identifier composed of alphanumeric characters.
- Currently specified: @samp{u} for user, @samp{g} for group, @samp{o}
- for other (see below for discussion of whether these have their POSIX
- meaning or are more loose). Unrecognized values of @var{mode-type}
- are silently ignored.
- @var{data} consists of any data not containing @samp{,}, @samp{\0} or
- @samp{\n}. For @samp{u}, @samp{g}, and @samp{o} mode types, data
- consists of alphanumeric characters, where @samp{r} means read, @samp{w}
- means write, @samp{x} means execute, and unrecognized letters are
- silently ignored.
- The two most obvious ways in which the mode matters are: (1) is it
- writeable? This is used by the developer communication features, and
- is implemented even on OS/2 (and could be implemented on DOS), whose
- notion of mode is limited to a readonly bit. (2) is it executable?
- Unix CVS users need CVS to store this setting (for shell scripts and
- the like). The current CVS implementation on unix does a little bit
- more than just maintain these two settings, but it doesn't really have
- a nice general facility to store or version control the mode, even on
- unix, much less across operating systems with diverse protection
- features. So all the ins and outs of what the mode means across
- operating systems haven't really been worked out (e.g. should the VMS
- port use ACLs to get POSIX semantics for groups?).
- @node Filenames
- @section Conventions regarding transmission of file names
- In most contexts, @samp{/} is used to separate directory and file
- names in filenames, and any use of other conventions (for example,
- that the user might type on the command line) is converted to that
- form. The only exceptions might be a few cases in which the server
- provides a magic cookie which the client then repeats verbatim, but as
- the server has not yet been ported beyond unix, the two rules provide
- the same answer (and what to do if future server ports are operating
- on a repository like e:/foo or CVS_ROOT:[FOO.BAR] has not been
- carefully thought out).
- Characters outside the invariant ISO 646 character set should be avoided
- in filenames. This restriction may need to be relaxed to allow for
- characters such as @samp{[} and @samp{]} (see above about non-unix
- servers); this has not been carefully considered (and currently
- implementations probably use whatever character sets that the operating
- systems they are running on allow, and/or that users specify). Of
- course the most portable practice is to restrict oneself further, to the
- POSIX portable filename character set as specified in POSIX.1.
- @node File transmissions
- @section File transmissions
- File contents (noted below as @var{file transmission}) can be sent in
- one of two forms. The simpler form is a number of bytes, followed by a
- linefeed, followed by the specified number of bytes of file contents.
- These are the entire contents of the specified file. Second, if both
- client and server support @samp{gzip-file-contents}, a @samp{z} may
- precede the length, and the `file contents' sent are actually compressed
- with @samp{gzip} (RFC1952/1951) compression. The length specified is
- that of the compressed version of the file.
- In neither case are the file content followed by any additional data.
- The transmission of a file will end with a linefeed iff that file (or its
- compressed form) ends with a linefeed.
- The encoding of file contents depends on the value for the @samp{-k}
- option. If the file is binary (as specified by the @samp{-kb} option in
- the appropriate place), then it is just a certain number of octets, and
- the protocol contributes nothing towards determining the encoding (using
- the file name is one widespread, if not universally popular, mechanism).
- If the file is text (not binary), then the file is sent as a series of
- lines, separated by linefeeds. If the keyword expansion is set to
- something other than @samp{-ko}, then it is expected that the file
- conform to the RCS expectations regarding keyword expansion---in
- particular, that it is in a character set such as ASCII in which 0x24 is
- a dollar sign (@samp{$}).
- @node Strings
- @section Strings
- In various contexts, for example the @code{Argument} request and the
- @code{M} response, one transmits what is essentially an arbitrary
- string. Often this will have been supplied by the user (for example,
- the @samp{-m} option to the @code{ci} request). The protocol has no
- mechanism to specify the character set of such strings; it would be
- fairly safe to stick to the invariant ISO 646 character set but the
- existing practice is probably to just transmit whatever the user
- specifies, and hope that everyone involved agrees which character set is
- in use, or sticks to a common subset.
- @node Dates
- @section Dates
- The protocol contains times and dates in various places.
- For the @samp{-D} option to the @code{annotate}, @code{co}, @code{diff},
- @code{export}, @code{history}, @code{rannotate}, @code{rdiff},
- @code{rtag}, @code{tag},
- and @code{update} requests, the server should support two formats:
- @example
- 26 May 1997 13:01:40 -0000 ; @r{RFC 822 as modified by RFC 1123}
- 5/26/1997 13:01:40 GMT ; @r{traditional}
- @end example
- The former format is preferred; the latter however is sent by the CVS
- command line client (versions 1.5 through at least 1.9).
- For the @samp{-d} option to the @code{log} and @code{rlog} requests,
- servers should at
- least support RFC 822/1123 format. Clients are encouraged to use this
- format too (the command line CVS client, version 1.10 and older, just passed
- along the date format specified by the user, however).
- The @code{Mod-time} response and @code{Checkin-time} request use RFC
- 822/1123 format (see the descriptions of that response and request for
- details).
- For @code{Notify}, see the description of that request.
- @node Request intro
- @section Request intro
- By convention, requests which begin with a capital letter do not elicit
- a response from the server, while all others do -- save one. The
- exception is @samp{gzip-file-contents}. Unrecognized requests will
- always elicit a response from the server, even if that request begins
- with a capital letter.
- The term @dfn{command} means a request which expects a response (except
- @code{valid-requests}). The general model is that the client transmits
- a great number of requests, but nothing happens until the very end when
- the client transmits a command. Although the intention is that
- transmitting several commands in one connection should be legal,
- existing servers probably have some bugs with some combinations of more
- than one command, and so clients may find it necessary to make several
- connections in some cases. This should be thought of as a workaround
- rather than a desired attribute of the protocol.
- @node Requests
- @section Requests
- Here are the requests:
- @table @code
- @item Root @var{pathname} \n
- Response expected: no. Tell the server which @code{CVSROOT} to use.
- Note that @var{pathname} is @emph{not} a fully qualified @code{CVSROOT}
- variable, but only the local directory part of it. @var{pathname} must
- already exist on the server. Again, @var{pathname} @emph{does not} include
- the hostname of the server, how to access the server, etc.; by the time
- the CVS protocol is in use, connection, authentication, etc., are
- already taken care of.
- The @code{Root} request must be sent only once, and it must be sent
- before any requests other than @code{Valid-responses},
- @code{valid-requests}, @code{UseUnchanged}, @code{Set},
- @code{Global_option}, @code{noop}, or @code{version}.
- @item Valid-responses @var{request-list} \n
- Response expected: no.
- Tell the server what responses the client will accept.
- request-list is a space separated list of tokens.
- The @code{Root} request need not have been previously sent.
- @item valid-requests \n
- Response expected: yes.
- Ask the server to send back a @code{Valid-requests} response.
- The @code{Root} request need not have been previously sent.
- @item Directory @var{local-directory} \n
- Additional data: @var{repository} \n. Response expected: no.
- Tell the server what directory to use. The @var{repository} should be a
- directory name from a previous server response. Note that
- this both gives a default for @code{Entry} and @code{Modified} and
- also for @code{ci} and the other commands; normal usage is to send
- @code{Directory} for each directory in which there will be an
- @code{Entry} or @code{Modified}, and then a final @code{Directory}
- for the original directory, then the command.
- The @var{local-directory} is relative to
- the top level at which the command is occurring (i.e., the last
- @code{Directory} which is sent before the command);
- to indicate that top level, @samp{.} should be sent for
- @var{local-directory}.
- Here is an example of where a client gets @var{repository} and
- @var{local-directory}. Suppose that there is a module defined by
- @example
- moddir 1dir
- @end example
- That is, one can check out @code{moddir} and it will take @code{1dir} in
- the repository and check it out to @code{moddir} in the working
- directory. Then an initial check out could proceed like this:
- @example
- C: Root /home/kingdon/zwork/cvsroot
- . . .
- C: Argument moddir
- C: Directory .
- C: /home/kingdon/zwork/cvsroot
- C: co
- S: Clear-sticky moddir/
- S: /home/kingdon/zwork/cvsroot/1dir/
- . . .
- S: ok
- @end example
- In this example the response shown is @code{Clear-sticky}, but it could
- be another response instead. Note that it returns two pathnames.
- The first one, @file{moddir/}, indicates the working
- directory to check out into. The second one, ending in @file{1dir/},
- indicates the directory to pass back to the server in a subsequent
- @code{Directory} request. For example, a subsequent @code{update}
- request might look like:
- @example
- C: Directory moddir
- C: /home/kingdon/zwork/cvsroot/1dir
- . . .
- C: update
- @end example
- For a given @var{local-directory}, the repository will be the same for
- each of the responses, so one can use the repository from whichever
- response is most convenient. Typically a client will store the
- repository along with the sources for each @var{local-directory}, use
- that same setting whenever operating on that @var{local-directory}, and
- not update the setting as long as the @var{local-directory} exists.
- A client is free to rename a @var{local-directory} at any time (for
- example, in response to an explicit user request). While it is true
- that the server supplies a @var{local-directory} to the client, as noted
- above, this is only the default place to put the directory. Of course,
- the various @code{Directory} requests for a single command (for example,
- @code{update} or @code{ci} request) should name a particular directory
- with the same @var{local-directory}.
- Each @code{Directory} request specifies a brand-new
- @var{local-directory} and @var{repository}; that is,
- @var{local-directory} and @var{repository} are never relative to paths
- specified in any previous @code{Directory} request.
- Here's a more complex example, in which we request an update of a
- working directory which has been checked out from multiple places in the
- repository.
- @example
- C: Argument dir1
- C: Directory dir1
- C: /home/foo/repos/mod1
- . . .
- C: Argument dir2
- C: Directory dir2
- C: /home/foo/repos/mod2
- . . .
- C: Argument dir3
- C: Directory dir3/subdir3
- C: /home/foo/repos/mod3
- . . .
- C: update
- @end example
- While directories @code{dir1} and @code{dir2} will be handled in similar
- fashion to the other examples given above, @code{dir3} is slightly
- different from the server's standpoint. Notice that module @code{mod3}
- is actually checked out into @code{dir3/subdir3}, meaning that directory
- @code{dir3} is either empty or does not contain data checked out from
- this repository.
- The above example will work correctly in @sc{cvs} 1.10.1 and later. The
- server will descend the tree starting from all directories mentioned in
- @code{Argument} requests and update those directories specifically
- mentioned in @code{Directory} requests.
- Previous versions of @sc{cvs} (1.10 and earlier) do not behave the same
- way. While the descent of the tree begins at all directories mentioned
- in @code{Argument} requests, descent into subdirectories only occurs if
- a directory has been mentioned in a @code{Directory} request.
- Therefore, the above example would succeed in updating @code{dir1} and
- @code{dir2}, but would skip @code{dir3} because that directory was not
- specifically mentioned in a @code{Directory} request. A functional
- version of the above that would run on a 1.10 or earlier server is as
- follows:
- @example
- C: Argument dir1
- C: Directory dir1
- C: /home/foo/repos/mod1
- . . .
- C: Argument dir2
- C: Directory dir2
- C: /home/foo/repos/mod2
- . . .
- C: Argument dir3
- C: Directory dir3
- C: /home/foo/repos/.
- . . .
- C: Directory dir3/subdir3
- C: /home/foo/repos/mod3
- . . .
- C: update
- @end example
- Note the extra @code{Directory dir3} request. It might be better to use
- @code{Emptydir} as the repository for the @code{dir3} directory, but the
- above will certainly work.
- One more peculiarity of the 1.10 and earlier protocol is the ordering of
- @code{Directory} arguments. In order for a subdirectory to be
- registered correctly for descent by the recursion processor, its parent
- must be sent first. For example, the following would not work to update
- @code{dir3/subdir3}:
- @example
- . . .
- C: Argument dir3
- C: Directory dir3/subdir3
- C: /home/foo/repos/mod3
- . . .
- C: Directory dir3
- C: /home/foo/repos/.
- . . .
- C: update
- @end example
- The implementation of the server in 1.10 and earlier writes the
- administration files for a given directory at the time of the
- @code{Directory} request. It also tries to register the directory with
- its parent to mark it for recursion. In the above example, at the time
- @code{dir3/subdir3} is created, the physical directory for @code{dir3}
- will be created on disk, but the administration files will not have been
- created. Therefore, when the server tries to register
- @code{dir3/subdir3} for recursion, the operation will silently fail
- because the administration files do not yet exist for @code{dir3}.
- @item Max-dotdot @var{level} \n
- Response expected: no.
- Tell the server that @var{level} levels of directories above the
- directory which @code{Directory} requests are relative to will be
- needed. For example, if the client is planning to use a
- @code{Directory} request for @file{../../foo}, it must send a
- @code{Max-dotdot} request with a @var{level} of at least 2.
- @code{Max-dotdot} must be sent before the first @code{Directory}
- request.
- @item Static-directory \n
- Response expected: no. Tell the server that the directory most recently
- specified with @code{Directory} should not have
- additional files checked out unless explicitly requested. The client
- sends this if the @code{Entries.Static} flag is set, which is controlled
- by the @code{Set-static-directory} and @code{Clear-static-directory}
- responses.
- @item Sticky @var{tagspec} \n
- Response expected: no. Tell the server that the directory most recently
- specified with @code{Directory} has a sticky tag or date @var{tagspec}.
- The first character of @var{tagspec} is @samp{T} for a tag, @samp{D}
- for a date, or some other character supplied by a Set-sticky response
- from a previous request to the server. The remainder of @var{tagspec}
- contains the actual tag or date, again as supplied by Set-sticky.
- The server should remember @code{Static-directory} and @code{Sticky}
- requests for a particular directory; the client need not resend them
- each time it sends a @code{Directory} request for a given directory.
- However, the server is not obliged to remember them beyond the context
- of a single command.
- @item Entry @var{entry-line} \n
- Response expected: no. Tell the server what version of a file is on the
- local machine. The name in @var{entry-line} is a name relative to the
- directory most recently specified with @code{Directory}. If the user
- is operating on only some files in a directory, @code{Entry} requests
- for only those files need be included. If an @code{Entry} request is
- sent without @code{Modified}, @code{Is-modified}, or @code{Unchanged},
- it means the file is
- lost (does not exist in the working directory). If both @code{Entry}
- and one of @code{Modified}, @code{Is-modified}, or @code{Unchanged} are
- sent for the same file, @code{Entry} must be sent first. For a
- given file, one can send @code{Modified}, @code{Is-modified}, or
- @code{Unchanged}, but not more than one of these three.
- @item Kopt @var{option} \n
- This indicates to the server which keyword expansion options to use for
- the file specified by the next @code{Modified} or @code{Is-modified}
- request (for example @samp{-kb} for a binary file). This is similar to
- @code{Entry}, but is used for a file for which there is no entries line.
- Typically this will be a file being added via an @code{add} or
- @code{import} request. The client may not send both @code{Kopt} and
- @code{Entry} for the same file.
- @item Checkin-time @var{time} \n
- For the file specified by the next @code{Modified} request, use
- @var{time} as the time of the checkin. The @var{time} is in the format
- specified by RFC822 as modified by RFC1123. The client may specify any
- timezone it chooses; servers will want to convert that to their own
- timezone as appropriate. An example of this format is:
- @example
- 26 May 1997 13:01:40 -0400
- @end example
- There is no requirement that the client and server clocks be
- synchronized. The client just sends its recommendation for a timestamp
- (based on file timestamps or whatever), and the server should just believe
- it (this means that the time might be in the future, for example).
- Note that this is not a general-purpose way to tell the server about the
- timestamp of a file; that would be a separate request (if there are
- servers which can maintain timestamp and time of checkin separately).
- This request should affect the @code{import} request, and may optionally
- affect the @code{ci} request or other relevant requests if any.
- @item Modified @var{filename} \n
- Response expected: no. Additional data: mode, \n, file transmission.
- Send the server a copy of one locally modified file. @var{filename} is
- a file within the most recent directory sent with @code{Directory}; it
- must not contain @samp{/}. If
- the user is operating on only some files in a directory, only those
- files need to be included. This can also be sent without @code{Entry},
- if there is no entry for the file.
- @item Is-modified @var{filename} \n
- Response expected: no. Additional data: none. Like @code{Modified},
- but used if the server only needs
- to know whether the file is modified, not the contents.
- The commands which can take @code{Is-modified} instead of
- @code{Modified} with no known change in behavior are: @code{admin},
- @code{diff} (if and only if two @samp{-r} or @samp{-D} options are
- specified), @code{watch-on}, @code{watch-off}, @code{watch-add},
- @code{watch-remove}, @code{watchers}, @code{editors},
- @code{log}, and @code{annotate}.
- For the @code{status} command, one can send @code{Is-modified} but if
- the client is using imperfect mechanisms such as timestamps to determine
- whether to consider a file modified, then the behavior will be
- different. That is, if one sends @code{Modified}, then the server will
- actually compare the contents of the file sent and the one it derives
- from to determine whether the file is genuinely modified. But if one
- sends @code{Is-modified}, then the server takes the client's word for
- it. A similar situation exists for @code{tag}, if the @samp{-c} option
- is specified.
- Commands for which @code{Modified} is necessary are @code{co},
- @code{ci}, @code{update}, and @code{import}.
- Commands which do not need to inform the server about a working
- directory, and thus should not be sending either @code{Modified} or
- @code{Is-modified}: @code{rdiff}, @code{rtag}, @code{history},
- and @code{release}.
- Commands for which further investigation is warranted are:
- @code{remove}, @code{add}, and @code{export}. Pending such
- investigation, the more conservative course of action is to stick to
- @code{Modified}.
- @item Unchanged @var{filename} \n
- Response expected: no. Tell the server that @var{filename} has not been
- modified in the checked out directory. The @var{filename} is
- a file within the most recent directory sent with @code{Directory}; it
- must not contain @samp{/}.
- @item UseUnchanged \n
- Response expected: no. To specify the version of the protocol described
- in this document, servers must support this request (although it need
- not do anything) and clients must issue it.
- The @code{Root} request need not have been previously sent.
- @item Empty-conflicts \n
- Response expected: yes. This request is an alias for @code{noop}. Its
- presence in the list of @code{valid-requests} is intended to be used as a
- placeholder to alert the client that the server does not require the contents
- of files with conflicts that have not been modified since the merge, for
- operations other than diff. It was a bug in pre 1.11.22 & pre 1.12.14 servers
- that the contents of files with conflicts was required for the server to
- acknowledge the existence of the conflicts.
- @item Notify @var{filename} \n
- Response expected: no.
- Tell the server that an @code{edit} or @code{unedit} command has taken
- place. The server needs to send a @code{Notified} response, but such
- response is deferred until the next time that the server is sending
- responses.
- The @var{filename} is a file within the most recent directory sent with
- @code{Directory}; it must not contain @samp{/}.
- Additional data:
- @example
- @var{notification-type} \t @var{time} \t @var{clienthost} \t
- @var{working-dir} \t @var{watches} \n
- @end example
- where @var{notification-type} is @samp{E} for edit, @samp{U} for
- unedit, undefined behavior if @samp{C}, and all other letters should be
- silently ignored for future expansion.
- @var{time} is the time at which the edit or unedit took place, in a
- user-readable format of the client's choice (the server should treat the
- time as an opaque string rather than interpreting it).
- @c Might be useful to specify a format, but I don't know if we want to
- @c specify the status quo (ISO C asctime() format plus timezone) without
- @c offering the option of ISO8601 and/or RFC822/1123 (see cvs.texinfo
- @c for much much more on date formats).
- @var{clienthost} is the name of the host on which the edit or unedit
- took place, and @var{working-dir} is the pathname of the working
- directory where the edit or unedit took place. @var{watches} are the
- temporary watches, zero or more of the following characters in the
- following order: @samp{E} for edit, @samp{U} for unedit, @samp{C} for
- commit, and all other letters should be silently ignored for future
- expansion. If @var{notification-type} is @samp{E} the temporary watches
- are set; if it is @samp{U} they are cleared.
- If @var{watches} is followed by \t then the
- \t and the rest of the line should be ignored, for future expansion.
- The @var{time}, @var{clienthost}, and @var{working-dir} fields may not
- contain the characters @samp{+}, @samp{,}, @samp{>}, @samp{;}, or @samp{=}.
- Note that a client may be capable of performing an @code{edit} or
- @code{unedit} operation without connecting to the server at that time,
- and instead connecting to the server when it is convenient (for example,
- when a laptop is on the net again) to send the @code{Notify} requests.
- Even if a client is capable of deferring notifications, it should
- attempt to send them immediately (one can send @code{Notify} requests
- together with a @code{noop} request, for example), unless perhaps if
- it can know that a connection would be impossible.
- @item Questionable @var{filename} \n
- Response expected: no. Additional data: no. Tell the server to check
- whether @var{filename} should be ignored, and if not, next time the
- server sends responses, send (in a @code{M} response) @samp{?} followed
- by the directory and filename. @var{filename} must not contain
- @samp{/}; it needs to be a file in the directory named by the most
- recent @code{Directory} request.
- @c FIXME: the bit about not containing / is true of most of the
- @c requests, but isn't documented and should be.
- @item Case \n
- Response expected: no. Tell the server that filenames should be matched
- in a case-insensitive fashion. Note that this is not the primary
- mechanism for achieving case-insensitivity; for the most part the client
- keeps track of the case which the server wants to use and takes care to
- always use that case regardless of what the user specifies. For example
- the filenames given in @code{Entry} and @code{Modified} requests for the
- same file must match in case regardless of whether the @code{Case}
- request is sent. The latter mechanism is more general (it could also be
- used for 8.3 filenames, VMS filenames with more than one @samp{.}, and
- any other situation in which there is a predictable mapping between
- filenames in the working directory and filenames in the protocol), but
- there are some situations it cannot handle (ignore patterns, or
- situations where the user specifies a filename and the client does not
- know about that file).
- Though this request will be supported into the foreseeable future, it has been
- the source of numerous bug reports in the past due to the complexity of testing
- this functionality via the test suite and client developers are encouraged not
- to use it. Instead, please consider munging conflicting names and maintaining
- a map for communicating with the server. For example, suppose the server sends
- files @file{case}, @file{CASE}, and @file{CaSe}. The client could write all
- three files to names such as, @file{case}, @file{case_prefix_case}, and
- @file{case_prefix_2_case} and maintain a mapping between the file names in, for
- instance a new @file{CVS/Map} file.
- @item Argument @var{text} \n
- Response expected: no.
- Save argument for use in a subsequent command. Arguments
- accumulate until an argument-using command is given, at which point
- they are forgotten.
- @item Argumentx @var{text} \n
- Response expected: no. Append \n followed by text to the current
- argument being saved.
- @item Global_option @var{option} \n
- Response expected: no.
- Transmit one of the global options @samp{-q}, @samp{-Q}, @samp{-l},
- @samp{-t}, @samp{-r}, or @samp{-n}. @var{option} must be one of those
- strings, no variations (such as combining of options) are allowed. For
- graceful handling of @code{valid-requests}, it is probably better to
- make new global options separate requests, rather than trying to add
- them to this request.
- The @code{Root} request need not have been previously sent.
- @item Gzip-stream @var{level} \n
- Response expected: no.
- Use zlib (RFC 1950/1951) compression to compress all further communication
- between the client and the server. After this request is sent, all
- further communication must be compressed. All further data received
- from the server will also be compressed. The @var{level} argument
- suggests to the server the level of compression that it should apply; it
- should be an integer between 1 and 9, inclusive, where a higher number
- indicates more compression.
- @item Kerberos-encrypt \n
- Response expected: no.
- Use Kerberos encryption to encrypt all further communication between the
- client and the server. This will only work if the connection was made
- over Kerberos in the first place. If both the @code{Gzip-stream} and
- the @code{Kerberos-encrypt} requests are used, the
- @code{Kerberos-encrypt} request should be used first. This will make
- the client and server encrypt the compressed data, as opposed to
- compressing the encrypted data. Encrypted data is generally
- incompressible.
- Note that this request does not fully prevent an attacker from hijacking
- the connection, in the sense that it does not prevent hijacking the
- connection between the initial authentication and the
- @code{Kerberos-encrypt} request.
- @item Gssapi-encrypt \n
- Response expected: no.
- Use GSSAPI encryption to encrypt all further communication between the
- client and the server. This will only work if the connection was made
- over GSSAPI in the first place. See @code{Kerberos-encrypt}, above, for
- the relation between @code{Gssapi-encrypt} and @code{Gzip-stream}.
- Note that this request does not fully prevent an attacker from hijacking
- the connection, in the sense that it does not prevent hijacking the
- connection between the initial authentication and the
- @code{Gssapi-encrypt} request.
- @item Gssapi-authenticate \n
- Response expected: no.
- Use GSSAPI authentication to authenticate all further communication
- between the client and the server. This will only work if the
- connection was made over GSSAPI in the first place. Encrypted data is
- automatically authenticated, so using both @code{Gssapi-authenticate}
- and @code{Gssapi-encrypt} has no effect beyond that of
- @code{Gssapi-encrypt}. Unlike encrypted data, it is reasonable to
- compress authenticated data.
- Note that this request does not fully prevent an attacker from hijacking
- the connection, in the sense that it does not prevent hijacking the
- connection between the initial authentication and the
- @code{Gssapi-authenticate} request.
- @item Set @var{variable}=@var{value} \n
- Response expected: no.
- Set a user variable @var{variable} to @var{value}.
- The @code{Root} request need not have been previously sent.
- @item expand-modules \n
- Response expected: yes. Expand the modules which are specified in the
- arguments. Returns the data in @code{Module-expansion} responses. Note
- that the server can assume that this is checkout or export, not rtag or
- rdiff; the latter do not access the working directory and thus have no
- need to expand modules on the client side.
- Expand may not be the best word for what this request does. It does not
- necessarily tell you all the files contained in a module, for example.
- Basically it is a way of telling you which working directories the
- server needs to know about in order to handle a checkout of the
- specified modules.
- For example, suppose that the server has a module defined by
- @example
- aliasmodule -a 1dir
- @end example
- That is, one can check out @code{aliasmodule} and it will take
- @code{1dir} in the repository and check it out to @code{1dir} in the
- working directory. Now suppose the client already has this module
- checked out and is planning on using the @code{co} request to update it.
- Without using @code{expand-modules}, the client would have two bad
- choices: it could either send information about @emph{all} working
- directories under the current directory, which could be unnecessarily
- slow, or it could be ignorant of the fact that @code{aliasmodule} stands
- for @code{1dir}, and neglect to send information for @code{1dir}, which
- would lead to incorrect operation.
- @c Those don't really seem like the only two options. I mean, what
- @c about keeping track of the correspondence from when we first checked
- @c out a fresh directory? Not that the CVS client does this, or that
- @c I've really thought about whether it would be a good idea...
- With @code{expand-modules}, the client would first ask for the module to
- be expanded:
- @example
- C: Root /home/kingdon/zwork/cvsroot
- . . .
- C: Argument aliasmodule
- C: Directory .
- C: /home/kingdon/zwork/cvsroot
- C: expand-modules
- S: Module-expansion 1dir
- S: ok
- @end example
- and then it knows to check the @file{1dir} directory and send
- requests such as @code{Entry} and @code{Modified} for the files in that
- directory.
- @item ci \n
- @itemx diff \n
- @itemx tag \n
- @itemx status \n
- @itemx admin \n
- @itemx history \n
- @itemx watchers \n
- @itemx editors \n
- @itemx annotate \n
- Response expected: yes. Actually do a cvs command. This uses any
- previous @code{Argument}, @code{Directory}, @code{Entry}, or
- @code{Modified} requests, if they have been sent. The
- last @code{Directory} sent specifies the working directory at the time
- of the operation. No provision is made for any input from the user.
- This means that @code{ci} must use a @code{-m} argument if it wants to
- specify a log message.
- @item log \n
- Response expected: yes. Show information for past revisions. This uses
- any previous @code{Directory}, @code{Entry}, or @code{Modified}
- requests, if they have been sent. The last @code{Directory} sent
- specifies the working directory at the time of the operation. Also uses
- previous @code{Argument}'s of which the canonical forms are the
- following (@sc{cvs} 1.10 and older cl…