d441cc732dd4d93350050d28364d1d23439070dd
[alioth/cvs.git] / doc / cvsclient.texi
1 \input texinfo @c -*- texinfo -*-
2
3 @setfilename cvsclient.info
4 @afourpaper
5 @comment $MirOS: src/gnu/usr.bin/cvs/doc/cvsclient.texi,v 1.7 2016/11/08 23:04:35 tg Exp $
6 @include version-client.texi
7
8 @dircategory Programming
9 @direntry
10 * cvsclient: (cvsclient).      The CVS client/server protocol.
11 @end direntry
12
13 @node Top
14 @top CVS Client/Server
15
16 This document describes the client/server protocol used by CVS.  It does
17 not describe how to use or administer client/server CVS; for that,
18 @pxref{Top, the regular CVS manual,, cvs, the regular CVS manual}.
19 This is version @value{VERSION} of the protocol
20 specification---@xref{Introduction}, for more on what this version number
21 means.
22
23 @menu
24 * Introduction::      What is CVS and what is the client/server protocol for?
25 * Goals::             Basic design decisions, requirements, scope, etc.
26 * Connection and Authentication::  Various ways to connect to the server
27 * Password scrambling::  Scrambling used by pserver
28 * Protocol::          Complete description of the protocol
29 * Protocol Notes::    Possible enhancements, limitations, etc. of the protocol
30 @end menu
31
32 @node Introduction
33 @chapter Introduction
34
35 CVS is a version control system (with some additional configuration
36 management functionality).  It maintains a central @dfn{repository}
37 which stores files (often source code), including past versions,
38 information about who modified them and when, and so on.  People who
39 wish to look at or modify those files, known as @dfn{developers}, use
40 CVS to @dfn{check out} a @dfn{working directory} from the repository, to
41 @dfn{check in} new versions of files to the repository, and other
42 operations such as viewing the modification history of a file.  If
43 developers are connected to the repository by a network, particularly a
44 slow or flaky one, the most efficient way to use the network is with the
45 CVS-specific protocol described in this document.
46
47 Developers, using the machine on which they store their working
48 directory, run the CVS @dfn{client} program.  To perform operations
49 which cannot be done locally, it connects to the CVS @dfn{server}
50 program, which maintains the repository.  For more information on how
51 to connect see @ref{Connection and Authentication}.
52
53 This document describes the CVS protocol.  Unfortunately, it does not
54 yet completely document one aspect of the protocol---the detailed
55 operation of each CVS command and option---and one must look at the CVS
56 user documentation, @file{cvs.texinfo}, for that information.  The
57 protocol is non-proprietary (anyone who wants to is encouraged to
58 implement it) and an implementation, known as CVS, is available under
59 the GNU General Public License.  The CVS distribution, containing this
60 implementation, @file{cvs.texinfo}, and a copy (possibly more or less up
61 to date than what you are reading now) of this document,
62 @file{cvsclient.texi}, can be found at the usual GNU FTP sites, with a
63 filename such as @file{cvs-@var{version}.tar.gz}.
64
65 This is version @value{VERSION} of the protocol specification.  This
66 version number is intended only to aid in distinguishing different
67 versions of this specification.  Although the specification is currently
68 maintained in conjunction with the CVS implementation, and carries the
69 same version number, it also intends to document what is involved with
70 interoperating with other implementations (such as other versions of
71 CVS); see @ref{Requirements}.  This version number should not be used
72 by clients or servers to determine what variant of the protocol to
73 speak; they should instead use the @code{valid-requests} and
74 @code{Valid-responses} mechanism (@pxref{Protocol}), which is more
75 flexible.
76
77 @node Goals
78 @chapter Goals
79
80 @itemize @bullet
81 @item
82 Do not assume any access to the repository other than via this protocol.
83 It does not depend on NFS, rdist, etc.
84
85 @item
86 Providing a reliable transport is outside this protocol.  The protocol
87 expects a reliable transport that is transparent (that is, there is no
88 translation of characters, including characters such as
89 linefeeds or carriage returns), and can transmit all 256 octets (for
90 example for proper handling of binary files, compression, and
91 encryption).  The encoding of characters specified by the protocol (the
92 names of requests and so on) is the invariant ISO 646 character set (a
93 subset of most popular character sets including ASCII and others).  For
94 more details on running the protocol over the TCP reliable transport,
95 see @ref{Connection and Authentication}.
96
97 @item
98 Security and authentication are handled outside this protocol (but see
99 below about @samp{cvs kserver} and @samp{cvs pserver}).
100
101 @item
102 The protocol makes it possible for updates to be atomic with respect to
103 checkins; that is if someone commits changes to several files in one cvs
104 command, then an update by someone else would either get all the
105 changes, or none of them.  The current @sc{cvs} server can't do this,
106 but that isn't the protocol's fault.
107
108 @item
109 The protocol is, with a few exceptions, transaction-based.  That is, the
110 client sends all its requests (without waiting for server responses),
111 and then waits for the server to send back all responses (without
112 waiting for further client requests).  This has the advantage of
113 minimizing network turnarounds and the disadvantage of sometimes
114 transferring more data than would be necessary if there were a richer
115 interaction.  Another, more subtle, advantage is that there is no need
116 for the protocol to provide locking for features such as making checkins
117 atomic with respect to updates.  Any such locking can be handled
118 entirely by the server.  A good server implementation (such as the
119 current @sc{cvs} server) will make sure that it does not have any such
120 locks in place whenever it is waiting for communication with the client;
121 this prevents one client on a slow or flaky network from interfering
122 with the work of others.
123
124 @item
125 It is a general design goal to provide only one way to do a given
126 operation (where possible).  For example, implementations have no choice
127 about whether to terminate lines with linefeeds or some other
128 character(s), and request and response names are case-sensitive.  This
129 is to enhance interoperability.  If a protocol allows more than one way
130 to do something, it is all too easy for some implementations to support
131 only some of them (perhaps accidentally).
132 @c I vaguely remember reading, probably in an RFC, about the problems
133 @c that were caused when some people decided that SMTP should accept
134 @c other line termination (in the message ("DATA")?) than CRLF.  However, I
135 @c can't seem to track down the reference.
136 @end itemize
137
138 @node Connection and Authentication
139 @chapter How to Connect to and Authenticate Oneself to the CVS server
140
141 Connection and authentication occurs before the CVS protocol itself is
142 started.  There are several ways to connect.
143
144 @table @asis
145 @item server
146 If the client has a way to execute commands on the server, and provide
147 input to the commands and output from them, then it can connect that
148 way.  This could be the usual rsh (port 514) protocol, Kerberos rsh,
149 SSH, or any similar mechanism.  The client may allow the user to specify
150 the name of the server program; the default is @code{cvs}.  It is
151 invoked with one argument, @code{server}.  Once it invokes the server,
152 the client proceeds to start the cvs protocol.
153
154 @item kserver
155 The kerberized server listens on a port (in the current implementation,
156 by having inetd call "cvs kserver") which defaults to 1999.  The client
157 connects, sends the usual kerberos authentication information, and then
158 starts the cvs protocol.  Note: port 1999 is officially registered for
159 another use, and in any event one cannot register more than one port for
160 CVS, so GSS-API (see below) is recommended instead of kserver as a way
161 to support kerberos.
162
163 @item pserver
164 The name @dfn{pserver} is somewhat confusing.  It refers to both a
165 generic framework which allows the CVS protocol to support several
166 authentication mechanisms, and a name for a specific mechanism which
167 transfers a username and a cleartext password.  Servers need not support
168 all mechanisms, and in fact servers will typically want to support only
169 those mechanisms which meet the relevant security needs.
170
171 The pserver server listens on a port (in the current
172 implementation, by having inetd call "cvs pserver") which defaults to
173 2401 (this port is officially registered).  The client
174 connects, and sends the following:
175
176 @itemize @bullet
177 @item
178 the string @samp{BEGIN AUTH REQUEST}, a linefeed, 
179 @item
180 the cvs root, a linefeed,
181 @item
182 the username, a linefeed,
183 @item
184 the password trivially encoded (see @ref{Password scrambling}), a
185 linefeed,
186 @item
187 the string @samp{END AUTH REQUEST}, and a linefeed.
188 @end itemize
189
190 The client must send the
191 identical string for cvs root both here and later in the
192 @code{Root} request of the cvs
193 protocol itself.  Servers are encouraged to enforce this restriction.
194 The possible server responses (each of which is followed by a linefeed)
195 are the following.  Note that although there is a small similarity
196 between this authentication protocol and the cvs protocol, they are
197 separate.
198
199 @table @code
200 @item I LOVE YOU
201 The authentication is successful.  The client proceeds with the cvs
202 protocol itself.
203
204 @item I HATE YOU
205 The authentication fails.  After sending this response, the server may
206 close the connection.  It is up to the server to decide whether to give
207 this response, which is generic, or a more specific response using
208 @samp{E} and/or @samp{error}.
209
210 @item E @var{text}
211 Provide a message for the user.  After this reponse, the authentication
212 protocol continues with another response.  Typically the server will
213 provide a series of @samp{E} responses followed by @samp{error}.
214 Compatibility note: @sc{cvs} 1.9.10 and older clients will print
215 @code{unrecognized auth response} and @var{text}, and then exit, upon
216 receiving this response.
217
218 @item error @var{code} @var{text}
219 The authentication fails.  After sending this response, the server may
220 close the connection.  The @var{code} is a code describing why it
221 failed, intended for computer consumption.  The only code currently
222 defined is @samp{0} which is nonspecific, but clients must silently
223 treat any unrecognized codes as nonspecific.
224 The @var{text} should be supplied to the
225 user.  Compatibility note: @sc{cvs} 1.9.10 and older clients will print
226 @code{unrecognized auth response} and @var{text}, and then exit, upon
227 receiving this response.
228 Note that @var{text} for this response, or the @var{text} in an @code{E}
229 response, is not designed for machine parsing.  More vigorous use of
230 @var{code}, or future extensions, will be needed to prove a cleaner
231 machine-parseable indication of what the error was.
232 @end table
233
234 @c If you are thinking of putting samp or code around BEGIN AUTH REQUEST
235 @c and friends, watch for overfull hboxes.
236 If the client wishes to merely authenticate without starting the cvs
237 protocol, the procedure is the same, except BEGIN AUTH REQUEST is
238 replaced with BEGIN VERIFICATION REQUEST, END AUTH REQUEST
239 is replaced with END VERIFICATION REQUEST, and upon receipt of
240 I LOVE YOU the connection is closed rather than continuing.
241
242 Another mechanism is GSSAPI authentication.  GSSAPI is a
243 generic interface to security services such as kerberos.  GSSAPI is
244 specified in RFC2078 (GSSAPI version 2) and RFC1508 (GSSAPI version 1);
245 we are not aware of differences between the two which affect the
246 protocol in incompatible ways, so we make no attempt to specify one
247 version or the other.
248 The procedure here is to start with @samp{BEGIN
249 GSSAPI REQUEST}.  GSSAPI authentication information is then exchanged
250 between the client and the server.  Each packet of information consists
251 of a two byte big endian length, followed by that many bytes of data.
252 After the GSSAPI authentication is complete, the server continues with
253 the responses described above (@samp{I LOVE YOU}, etc.).
254
255 @item future possibilities
256 There are a nearly unlimited number of ways to connect and authenticate.
257 One might want to allow access based on IP address (similar to the usual
258 rsh protocol but with different/no restrictions on ports < 1024), to
259 adopt mechanisms such as Pluggable Authentication Modules (PAM), to
260 allow users to run their own servers under their own usernames without
261 root access, or any number of other possibilities.  The way to add
262 future mechanisms, for the most part, should be to continue to use port
263 2401, but to use different strings in place of @samp{BEGIN AUTH
264 REQUEST}.
265 @end table
266
267 @node Password scrambling
268 @chapter Password scrambling algorithm
269
270 The pserver authentication protocol, as described in @ref{Connection and
271 Authentication}, trivially encodes the passwords.  This is only to
272 prevent inadvertent compromise; it provides no protection against even a
273 relatively unsophisticated attacker.  For comparison, HTTP Basic
274 Authentication (as described in RFC2068) uses BASE64 for a similar
275 purpose.  CVS uses its own algorithm, described here.
276
277 The scrambled password starts with @samp{A}, which serves to identify
278 the scrambling algorithm in use.  After that follows a single octet for
279 each character in the password, according to a fixed encoding.  The
280 values are shown here, with the encoded values in decimal.  Control
281 characters, space, and characters outside the invariant ISO 646
282 character set are not shown; such characters are not recommended for use
283 in passwords.  There is a long discussion of character set issues in
284 @ref{Protocol Notes}.
285
286 @example
287         0 111           P 125           p  58
288 ! 120   1  52   A  57   Q  55   a 121   q 113
289 "  53   2  75   B  83   R  54   b 117   r  32
290         3 119   C  43   S  66   c 104   s  90
291         4  49   D  46   T 124   d 101   t  44
292 % 109   5  34   E 102   U 126   e 100   u  98
293 &  72   6  82   F  40   V  59   f  69   v  60
294 ' 108   7  81   G  89   W  47   g  73   w  51
295 (  70   8  95   H  38   X  92   h  99   x  33
296 )  64   9  65   I 103   Y  71   i  63   y  97
297 *  76   : 112   J  45   Z 115   j  94   z  62
298 +  67   ;  86   K  50           k  93
299 , 116   < 118   L  42           l  39
300 -  74   = 110   M 123           m  37
301 .  68   > 122   N  91           n  61
302 /  87   ? 105   O  35   _  56   o  48
303 @end example
304
305 @node Protocol
306 @chapter The CVS client/server protocol
307
308 In the following, @samp{\n} refers to a linefeed and @samp{\t} refers to
309 a horizontal tab; @dfn{requests} are what the client sends and
310 @dfn{responses} are what the server sends.  In general, the connection is
311 governed by the client---the server does not send responses without
312 first receiving requests to do so; see @ref{Response intro} for more
313 details of this convention.
314
315 It is typical, early in the connection, for the client to transmit a
316 @code{Valid-responses} request, containing all the responses it
317 supports, followed by a @code{valid-requests} request, which elicits
318 from the server a @code{Valid-requests} response containing all the
319 requests it understands.  In this way, the client and server each find
320 out what the other supports before exchanging large amounts of data
321 (such as file contents).
322
323 @c Hmm, having 3 sections in this menu makes a certain amount of sense
324 @c but that structure gets lost in the printed manual (not sure about
325 @c HTML).  Perhaps there is a better way.
326 @menu
327
328 General protocol conventions:
329
330 * Entries Lines::                   Transmitting RCS data
331 * File Modes::                      Read, write, execute, and possibly more...
332 * Filenames::                       Conventions regarding filenames
333 * File transmissions::              How file contents are transmitted
334 * Strings::                         Strings in various requests and responses
335 * Dates::                           Times and dates
336
337 The protocol itself:
338
339 * Request intro::                   General conventions relating to requests
340 * Requests::                        List of requests
341 * Response intro::                  General conventions relating to responses
342 * Response pathnames::              The "pathname" in responses
343 * Responses::                       List of responses
344 * Text tags::                       More details about the MT response
345
346 An example session, and some further observations:
347
348 * Example::                         A conversation between client and server
349 * Requirements::                    Things not to omit from an implementation
350 * Obsolete::                        Former protocol features
351 @end menu
352
353 @node Entries Lines
354 @section Entries Lines
355
356 Entries lines are transmitted as:
357
358 @example
359 / @var{name} / @var{version} / @var{conflict} / @var{options} / @var{tag_or_date}
360 @end example
361
362 @var{tag_or_date} is either @samp{T} @var{tag} or @samp{D} @var{date}
363 or empty.  If it is followed by a slash, anything after the slash
364 shall be silently ignored.
365
366 @var{version} can be empty, or start with @samp{0} or @samp{-}, for no
367 user file, new user file, or user file to be removed, respectively.
368
369 @c FIXME: should distinguish sender and receiver behavior here; the
370 @c "anything else" and "does not start with" are intended for future
371 @c expansion, and we should specify a sender behavior.
372 @var{conflict}, if it starts with @samp{+}, indicates that the file had
373 conflicts in it.  The rest of @var{conflict} is @samp{=} if the
374 timestamp matches the file, or anything else if it doesn't.  If
375 @var{conflict} does not start with a @samp{+}, it is silently ignored.
376
377 @var{options} signifies the keyword expansion options (for example
378 @samp{-ko}).  In an @code{Entry} request, this indicates the options
379 that were specified with the file from the previous file updating
380 response (@pxref{Response intro}, for a list of file updating
381 responses); if the client is specifying the @samp{-k} or @samp{-A}
382 option to @code{update}, then it is the server which figures out what
383 overrides what.
384
385 @node File Modes
386 @section File Modes
387
388 A mode is any number of repetitions of
389
390 @example
391 @var{mode-type} = @var{data}
392 @end example
393
394 separated by @samp{,}.
395
396 @var{mode-type} is an identifier composed of alphanumeric characters.
397 Currently specified: @samp{u} for user, @samp{g} for group, @samp{o}
398 for other (see below for discussion of whether these have their POSIX
399 meaning or are more loose).  Unrecognized values of @var{mode-type}
400 are silently ignored.
401
402 @var{data} consists of any data not containing @samp{,}, @samp{\0} or
403 @samp{\n}.  For @samp{u}, @samp{g}, and @samp{o} mode types, data
404 consists of alphanumeric characters, where @samp{r} means read, @samp{w}
405 means write, @samp{x} means execute, and unrecognized letters are
406 silently ignored.
407
408 The two most obvious ways in which the mode matters are: (1) is it
409 writeable?  This is used by the developer communication features, and
410 is implemented even on OS/2 (and could be implemented on DOS), whose
411 notion of mode is limited to a readonly bit. (2) is it executable?
412 Unix CVS users need CVS to store this setting (for shell scripts and
413 the like).  The current CVS implementation on unix does a little bit
414 more than just maintain these two settings, but it doesn't really have
415 a nice general facility to store or version control the mode, even on
416 unix, much less across operating systems with diverse protection
417 features.  So all the ins and outs of what the mode means across
418 operating systems haven't really been worked out (e.g. should the VMS
419 port use ACLs to get POSIX semantics for groups?).
420
421 @node Filenames
422 @section Conventions regarding transmission of file names
423
424 In most contexts, @samp{/} is used to separate directory and file
425 names in filenames, and any use of other conventions (for example,
426 that the user might type on the command line) is converted to that
427 form.  The only exceptions might be a few cases in which the server
428 provides a magic cookie which the client then repeats verbatim, but as
429 the server has not yet been ported beyond unix, the two rules provide
430 the same answer (and what to do if future server ports are operating
431 on a repository like e:/foo or CVS_ROOT:[FOO.BAR] has not been
432 carefully thought out).
433
434 Characters outside the invariant ISO 646 character set should be avoided
435 in filenames.  This restriction may need to be relaxed to allow for
436 characters such as @samp{[} and @samp{]} (see above about non-unix
437 servers); this has not been carefully considered (and currently
438 implementations probably use whatever character sets that the operating
439 systems they are running on allow, and/or that users specify).  Of
440 course the most portable practice is to restrict oneself further, to the
441 POSIX portable filename character set as specified in POSIX.1.
442
443 @node File transmissions
444 @section File transmissions
445
446 File contents (noted below as @var{file transmission}) can be sent in
447 one of two forms.  The simpler form is a number of bytes, followed by a
448 linefeed, followed by the specified number of bytes of file contents.
449 These are the entire contents of the specified file.  Second, if both
450 client and server support @samp{gzip-file-contents}, a @samp{z} may
451 precede the length, and the `file contents' sent are actually compressed
452 with @samp{gzip} (RFC1952/1951) compression.  The length specified is
453 that of the compressed version of the file.
454
455 In neither case are the file content followed by any additional data.
456 The transmission of a file will end with a linefeed iff that file (or its
457 compressed form) ends with a linefeed.
458
459 The encoding of file contents depends on the value for the @samp{-k}
460 option.  If the file is binary (as specified by the @samp{-kb} option in
461 the appropriate place), then it is just a certain number of octets, and
462 the protocol contributes nothing towards determining the encoding (using
463 the file name is one widespread, if not universally popular, mechanism).
464 If the file is text (not binary), then the file is sent as a series of
465 lines, separated by linefeeds.  If the keyword expansion is set to
466 something other than @samp{-ko}, then it is expected that the file
467 conform to the RCS expectations regarding keyword expansion---in
468 particular, that it is in a character set such as ASCII in which 0x24 is
469 a dollar sign (@samp{$}).
470
471 @node Strings
472 @section Strings
473
474 In various contexts, for example the @code{Argument} request and the
475 @code{M} response, one transmits what is essentially an arbitrary
476 string.  Often this will have been supplied by the user (for example,
477 the @samp{-m} option to the @code{ci} request).  The protocol has no
478 mechanism to specify the character set of such strings; it would be
479 fairly safe to stick to the invariant ISO 646 character set but the
480 existing practice is probably to just transmit whatever the user
481 specifies, and hope that everyone involved agrees which character set is
482 in use, or sticks to a common subset.
483
484 @node Dates
485 @section Dates
486
487 The protocol contains times and dates in various places.
488
489 For the @samp{-D} option to the @code{annotate}, @code{co}, @code{diff},
490 @code{export}, @code{history}, @code{rannotate}, @code{rdiff},
491 @code{rtag}, @code{tag},
492 and @code{update} requests, the server should support two formats:
493
494 @example
495 26 May 1997 13:01:40 -0000  ; @r{RFC 822 as modified by RFC 1123}
496 5/26/1997 13:01:40 GMT    ; @r{traditional}
497 @end example
498
499 The former format is preferred; the latter however is sent by the CVS
500 command line client (versions 1.5 through at least 1.9).
501
502 For the @samp{-d} option to the @code{log} and @code{rlog} requests,
503 servers should at
504 least support RFC 822/1123 format.  Clients are encouraged to use this
505 format too (the command line CVS client, version 1.10 and older, just passed
506 along the date format specified by the user, however).
507
508 The @code{Mod-time} response and @code{Checkin-time} request use RFC
509 822/1123 format (see the descriptions of that response and request for
510 details).
511
512 For @code{Notify}, see the description of that request.
513
514 @node Request intro
515 @section Request intro
516
517 By convention, requests which begin with a capital letter do not elicit
518 a response from the server, while all others do -- save one.  The
519 exception is @samp{gzip-file-contents}.  Unrecognized requests will
520 always elicit a response from the server, even if that request begins
521 with a capital letter.
522
523 The term @dfn{command} means a request which expects a response (except
524 @code{valid-requests}).  The general model is that the client transmits
525 a great number of requests, but nothing happens until the very end when
526 the client transmits a command.  Although the intention is that
527 transmitting several commands in one connection should be legal,
528 existing servers probably have some bugs with some combinations of more
529 than one command, and so clients may find it necessary to make several
530 connections in some cases.  This should be thought of as a workaround
531 rather than a desired attribute of the protocol.
532
533 @node Requests
534 @section Requests
535
536 Here are the requests:
537
538 @table @code
539 @item Root @var{pathname} \n
540 Response expected: no.  Tell the server which @code{CVSROOT} to use.
541 Note that @var{pathname} is a local directory and @emph{not} a fully
542 qualified @code{CVSROOT} variable.  @var{pathname} must
543 already exist; if creating a new root, use the @code{init} request, not
544 @code{Root}.  @var{pathname} does not include the hostname of the
545 server, how to access the server, etc.; by the time the CVS protocol is
546 in use, connection, authentication, etc., are already taken care of.
547
548 The @code{Root} request must be sent only once, and it must be sent
549 before any requests other than @code{Valid-responses},
550 @code{valid-requests}, @code{UseUnchanged}, @code{Set},
551 @code{Global_option}, @code{init}, @code{noop}, or @code{version}.
552
553 @item Valid-responses @var{request-list} \n
554 Response expected: no.
555 Tell the server what responses the client will accept.
556 request-list is a space separated list of tokens.
557 The @code{Root} request need not have been previously sent.
558
559 @item valid-requests \n
560 Response expected: yes.
561 Ask the server to send back a @code{Valid-requests} response.
562 The @code{Root} request need not have been previously sent.
563
564 @item Command-prep @var{command} \n
565 Response expected: yes.
566 Notify the server of the command that we are leading up to.  Intended to allow
567 the server to send a redirect for write operations.  Requires either an
568 @code{ok} or @code{Redirect} respnose.
569
570 @item Referrer @var{CVSROOT} \n
571 Response expected: no.
572 Notify a primary server of a server which referred us.  Intended to allow
573 a primary (write) server to update the read-only mirror a client is using
574 for reads to minimize races on any subsequent updates from the client.
575
576 @item Directory @var{local-directory} \n
577 @itemx Relative-directory @var{local-directory} \n
578 Additional data: @var{repository} \n.  Response expected: no.
579 Tell the server what directory to use.
580
581 The @var{repository} should be a directory name from a previous server
582 response and may be specified either relative to the @var{pathname} provided
583 with the @code{Root} request or absolute.  Relative or absolute, it must
584 specify a path within @var{pathname}.
585
586 Prior to @sc{cvs} version @strong{FIXME - release number 1.12.10?},
587 @var{repository} had to be absolute and @code{Relative-directory} was not a
588 valid request.  The @code{Relative-directory} request is synonymous with
589 @code{Directory} and is provided to alert modern clients that a relative
590 @var{repository} is acceptable.
591
592 Note that this both gives a default for @code{Entry} and @code{Modified} and
593 also for @code{ci} and the other commands; normal usage is to send 
594 @code{Directory} for each directory in which there will be an
595 @code{Entry} or @code{Modified}, and then a final @code{Directory}
596 for the original directory, then the command.
597 The @var{local-directory} is relative to
598 the top level at which the command is occurring (i.e. the last
599 @code{Directory} which is sent before the command);
600 to indicate that top level, @samp{.} should be sent for
601 @var{local-directory}.
602
603 Here is an example of where a client gets @var{repository} and
604 @var{local-directory}.  Suppose that there is a module defined by
605
606 @example
607 moddir 1dir
608 @end example
609
610 That is, one can check out @code{moddir} and it will take @code{1dir} in
611 the repository and check it out to @code{moddir} in the working
612 directory.  Then an initial check out could proceed like this:
613
614 @example
615 C: Root /home/kingdon/zwork/cvsroot
616 . . .
617 C: Argument moddir
618 C: Directory .
619 C: .
620 C: co
621 S: Clear-sticky moddir/
622 S: 1dir/
623 . . .
624 S: ok
625 @end example
626
627 In this example the response shown is @code{Clear-sticky}, but it could
628 be another response instead.  Note that it returns two pathnames.
629 The first one, @file{moddir/}, indicates the working
630 directory to check out into.  The second one, ending in @file{1dir/},
631 indicates the directory to pass back to the server in a subsequent
632 @code{Directory} request.  For example, a subsequent @code{update}
633 request might look like:
634
635 @example
636 C: Directory moddir
637 C: 1dir
638 . . .
639 C: update
640 @end example
641
642 For a given @var{local-directory}, the repository will be the same for
643 each of the responses, so one can use the repository from whichever
644 response is most convenient.  Typically a client will store the
645 repository along with the sources for each @var{local-directory}, use
646 that same setting whenever operating on that @var{local-directory}, and
647 not update the setting as long as the @var{local-directory} exists.
648
649 A client is free to rename a @var{local-directory} at any time (for
650 example, in response to an explicit user request).  While it is true
651 that the server supplies a @var{local-directory} to the client, as noted
652 above, this is only the default place to put the directory.  Of course,
653 the various @code{Directory} requests for a single command (for example,
654 @code{update} or @code{ci} request) should name a particular directory
655 with the same @var{local-directory}.
656
657 Each @code{Directory} request specifies a brand-new
658 @var{local-directory} and @var{repository}; that is,
659 @var{local-directory} and @var{repository} are never relative to paths
660 specified in any previous @code{Directory} request.
661
662 Here's a more complex example, in which we request an update of a
663 working directory which has been checked out from multiple places in the
664 repository.
665
666 @example
667 C: Argument dir1
668 C: Directory dir1
669 C: mod1
670 . . .
671 C: Argument dir2
672 C: Directory dir2
673 C: mod2
674 . . .
675 C: Argument dir3
676 C: Directory dir3/subdir3
677 C: mod3
678 . . .
679 C: update
680 @end example
681
682 While directories @code{dir1} and @code{dir2} will be handled in similar
683 fashion to the other examples given above, @code{dir3} is slightly
684 different from the server's standpoint.  Notice that module @code{mod3}
685 is actually checked out into @code{dir3/subdir3}, meaning that directory
686 @code{dir3} is either empty or does not contain data checked out from
687 this repository.  
688
689 The above example will work correctly in @sc{cvs} 1.10.1 and later.  The
690 server will descend the tree starting from all directories mentioned in
691 @code{Argument} requests and update those directories specifically
692 mentioned in @code{Directory} requests.
693
694 Previous versions of @sc{cvs} (1.10 and earlier) do not behave the same
695 way.  While the descent of the tree begins at all directories mentioned
696 in @code{Argument} requests, descent into subdirectories only occurs if
697 a directory has been mentioned in a @code{Directory} request.
698 Therefore, the above example would succeed in updating @code{dir1} and
699 @code{dir2}, but would skip @code{dir3} because that directory was not
700 specifically mentioned in a @code{Directory} request.  A functional
701 version of the above that would run on a 1.10 or earlier server is as
702 follows:
703
704 @example
705 C: Argument dir1
706 C: Directory dir1
707 C: mod1
708 . . .
709 C: Argument dir2
710 C: Directory dir2
711 C: mod2
712 . . .
713 C: Argument dir3
714 C: Directory dir3
715 C: .
716 . . .
717 C: Directory dir3/subdir3
718 C: mod3
719 . . .
720 C: update
721 @end example
722
723 Note the extra @code{Directory dir3} request.  It might be better to use
724 @code{Emptydir} as the repository for the @code{dir3} directory, but the
725 above will certainly work.
726
727 One more peculiarity of the 1.10 and earlier protocol is the ordering of
728 @code{Directory} arguments.  In order for a subdirectory to be
729 registered correctly for descent by the recursion processor, its parent
730 must be sent first.  For example, the following would not work to update
731 @code{dir3/subdir3}:
732
733 @example
734 . . .
735 C: Argument dir3
736 C: Directory dir3/subdir3
737 C: mod3
738 . . .
739 C: Directory dir3
740 C: .
741 . . .
742 C: update
743 @end example
744
745 The implementation of the server in 1.10 and earlier writes the
746 administration files for a given directory at the time of the
747 @code{Directory} request.  It also tries to register the directory with
748 its parent to mark it for recursion.  In the above example, at the time
749 @code{dir3/subdir3} is created, the physical directory for @code{dir3}
750 will be created on disk, but the administration files will not have been
751 created.  Therefore, when the server tries to register
752 @code{dir3/subdir3} for recursion, the operation will silently fail
753 because the administration files do not yet exist for @code{dir3}.
754
755 @item Max-dotdot @var{level} \n
756 Response expected: no.
757 Tell the server that @var{level} levels of directories above the
758 directory which @code{Directory} requests are relative to will be
759 needed.  For example, if the client is planning to use a
760 @code{Directory} request for @file{../../foo}, it must send a
761 @code{Max-dotdot} request with a @var{level} of at least 2.
762 @code{Max-dotdot} must be sent before the first @code{Directory}
763 request.
764
765 @item Static-directory \n
766 Response expected: no.  Tell the server that the directory most recently
767 specified with @code{Directory} should not have
768 additional files checked out unless explicitly requested.  The client
769 sends this if the @code{Entries.Static} flag is set, which is controlled
770 by the @code{Set-static-directory} and @code{Clear-static-directory}
771 responses.
772
773 @item Sticky @var{tagspec} \n
774 Response expected: no.  Tell the server that the directory most recently
775 specified with @code{Directory} has a sticky tag or date @var{tagspec}.
776 The first character of @var{tagspec} is @samp{T} for a tag, @samp{D}
777 for a date, or some other character supplied by a Set-sticky response
778 from a previous request to the server.  The remainder of @var{tagspec}
779 contains the actual tag or date, again as supplied by Set-sticky.
780
781 The server should remember @code{Static-directory} and @code{Sticky}
782 requests for a particular directory; the client need not resend them
783 each time it sends a @code{Directory} request for a given directory.
784 However, the server is not obliged to remember them beyond the context
785 of a single command.
786
787 @item Checkin-prog @var{program} \n
788 Response expected: no.  Tell the server that the directory most recently
789 specified with @code{Directory} has a checkin program @var{program}.
790 Such a program would have been previously set with the
791 @code{Set-checkin-prog} response.
792
793 @item Update-prog @var{program} \n
794 Response expected: no.  Tell the server that the directory most recently
795 specified with @code{Directory} has an update program @var{program}.
796 Such a program would have been previously set with the
797 @code{Set-update-prog} response.
798
799 @item Entry @var{entry-line} \n
800 Response expected: no.  Tell the server what version of a file is on the
801 local machine.  The name in @var{entry-line} is a name relative to the
802 directory most recently specified with @code{Directory}.  If the user
803 is operating on only some files in a directory, @code{Entry} requests
804 for only those files need be included.  If an @code{Entry} request is
805 sent without @code{Modified}, @code{Is-modified}, or @code{Unchanged},
806 it means the file is
807 lost (does not exist in the working directory).  If both @code{Entry}
808 and one of @code{Modified}, @code{Is-modified}, or @code{Unchanged} are
809 sent for the same file, @code{Entry} must be sent first.  For a
810 given file, one can send @code{Modified}, @code{Is-modified}, or
811 @code{Unchanged}, but not more than one of these three.
812
813 @item Kopt @var{option} \n
814 This indicates to the server which keyword expansion options to use for
815 the file specified by the next @code{Modified} or @code{Is-modified}
816 request (for example @samp{-kb} for a binary file).  This is similar to
817 @code{Entry}, but is used for a file for which there is no entries line.
818 Typically this will be a file being added via an @code{add} or
819 @code{import} request.  The client may not send both @code{Kopt} and
820 @code{Entry} for the same file.
821
822 @item Checkin-time @var{time} \n
823 For the file specified by the next @code{Modified} request, use
824 @var{time} as the time of the checkin.  The @var{time} is in the format
825 specified by RFC822 as modified by RFC1123.  The client may specify any
826 timezone it chooses; servers will want to convert that to their own
827 timezone as appropriate.  An example of this format is:
828
829 @example
830 26 May 1997 13:01:40 -0400
831 @end example
832
833 There is no requirement that the client and server clocks be
834 synchronized.  The client just sends its recommendation for a timestamp
835 (based on file timestamps or whatever), and the server should just believe
836 it (this means that the time might be in the future, for example).
837
838 Note that this is not a general-purpose way to tell the server about the
839 timestamp of a file; that would be a separate request (if there are
840 servers which can maintain timestamp and time of checkin separately).
841
842 This request should affect the @code{import} request, and may optionally
843 affect the @code{ci} request or other relevant requests if any.
844
845 @item Modified @var{filename} \n
846 Response expected: no.  Additional data: mode, \n, file transmission.
847 Send the server a copy of one locally modified file.  @var{filename} is
848 a file within the most recent directory sent with @code{Directory}; it
849 must not contain @samp{/}.  If
850 the user is operating on only some files in a directory, only those
851 files need to be included.  This can also be sent without @code{Entry},
852 if there is no entry for the file.
853
854 @item Is-modified @var{filename} \n
855 Response expected: no.  Additional data: none.  Like @code{Modified},
856 but used if the server only needs
857 to know whether the file is modified, not the contents.
858
859 The commands which can take @code{Is-modified} instead of
860 @code{Modified} with no known change in behavior are: @code{admin},
861 @code{diff} (if and only if two @samp{-r} or @samp{-D} options are
862 specified), @code{watch-on}, @code{watch-off}, @code{watch-add},
863 @code{watch-remove}, @code{watchers}, @code{editors},
864 @code{log}, and @code{annotate}.
865
866 For the @code{status} command, one can send @code{Is-modified} but if
867 the client is using imperfect mechanisms such as timestamps to determine
868 whether to consider a file modified, then the behavior will be
869 different.  That is, if one sends @code{Modified}, then the server will
870 actually compare the contents of the file sent and the one it derives
871 from to determine whether the file is genuinely modified.  But if one
872 sends @code{Is-modified}, then the server takes the client's word for
873 it.  A similar situation exists for @code{tag}, if the @samp{-c} option
874 is specified.
875
876 Commands for which @code{Modified} is necessary are @code{co},
877 @code{ci}, @code{update}, and @code{import}.
878
879 Commands which do not need to inform the server about a working
880 directory, and thus should not be sending either @code{Modified} or
881 @code{Is-modified}: @code{rdiff}, @code{rtag}, @code{history},
882 @code{init}, and @code{release}.
883
884 Commands for which further investigation is warranted are:
885 @code{remove}, @code{add}, and @code{export}.  Pending such
886 investigation, the more conservative course of action is to stick to
887 @code{Modified}.
888
889 @item Unchanged @var{filename} \n
890 Response expected: no.  Tell the server that @var{filename} has not been
891 modified in the checked out directory.  The @var{filename} is
892 a file within the most recent directory sent with @code{Directory}; it
893 must not contain @samp{/}.
894
895 @item UseUnchanged \n
896 Response expected: no.  To specify the version of the protocol described
897 in this document, servers must support this request (although it need
898 not do anything) and clients must issue it.
899 The @code{Root} request need not have been previously sent.
900
901 @item Notify @var{filename} \n
902 Response expected: no.
903 Tell the server that an @code{edit} or @code{unedit} command has taken
904 place.  The server needs to send a @code{Notified} response, but such
905 response is deferred until the next time that the server is sending
906 responses.
907 The @var{filename} is a file within the most recent directory sent with
908 @code{Directory}; it must not contain @samp{/}.
909 Additional data:
910 @example
911 @var{notification-type} \t @var{time} \t @var{clienthost} \t
912 @var{working-dir} \t @var{watches} \n
913 @end example
914 where @var{notification-type} is @samp{E} for edit, @samp{U} for
915 unedit, undefined behavior if @samp{C}, and all other letters should be
916 silently ignored for future expansion.
917 @var{time} is the time at which the edit or unedit took place, in a
918 user-readable format of the client's choice (the server should treat the
919 time as an opaque string rather than interpreting it).
920 @c Might be useful to specify a format, but I don't know if we want to
921 @c specify the status quo (ISO C asctime() format plus timezone) without
922 @c offering the option of ISO8601 and/or RFC822/1123 (see cvs.texinfo
923 @c for much much more on date formats).
924 @var{clienthost} is the name of the host on which the edit or unedit
925 took place, and @var{working-dir} is the pathname of the working
926 directory where the edit or unedit took place.  @var{watches} are the
927 temporary watches, zero or more of the following characters in the
928 following order: @samp{E} for edit, @samp{U} for unedit, @samp{C} for
929 commit, and all other letters should be silently ignored for future
930 expansion.  If @var{notification-type} is @samp{E} the temporary watches
931 are set; if it is @samp{U} they are cleared.
932 If @var{watches} is followed by \t then the
933 \t and the rest of the line should be ignored, for future expansion.
934
935 The @var{time}, @var{clienthost}, and @var{working-dir} fields may not
936 contain the characters @samp{+}, @samp{,}, @samp{>}, @samp{;}, or @samp{=}.
937
938 Note that a client may be capable of performing an @code{edit} or
939 @code{unedit} operation without connecting to the server at that time,
940 and instead connecting to the server when it is convenient (for example,
941 when a laptop is on the net again) to send the @code{Notify} requests.
942 Even if a client is capable of deferring notifications, it should
943 attempt to send them immediately (one can send @code{Notify} requests
944 together with a @code{noop} request, for example), unless perhaps if
945 it can know that a connection would be impossible.
946
947 @item Questionable @var{filename} \n
948 Response expected: no.  Additional data: no.  Tell the server to check
949 whether @var{filename} should be ignored, and if not, next time the
950 server sends responses, send (in a @code{M} response) @samp{?} followed
951 by the directory and filename.  @var{filename} must not contain
952 @samp{/}; it needs to be a file in the directory named by the most
953 recent @code{Directory} request.
954 @c FIXME: the bit about not containing / is true of most of the
955 @c requests, but isn't documented and should be.
956
957 @item Case \n
958 Response expected: no.  Tell the server that filenames should be matched
959 in a case-insensitive fashion.  Note that this is not the primary
960 mechanism for achieving case-insensitivity; for the most part the client
961 keeps track of the case which the server wants to use and takes care to
962 always use that case regardless of what the user specifies.  For example
963 the filenames given in @code{Entry} and @code{Modified} requests for the
964 same file must match in case regardless of whether the @code{Case}
965 request is sent.  The latter mechanism is more general (it could also be
966 used for 8.3 filenames, VMS filenames with more than one @samp{.}, and
967 any other situation in which there is a predictable mapping between
968 filenames in the working directory and filenames in the protocol), but
969 there are some situations it cannot handle (ignore patterns, or
970 situations where the user specifies a filename and the client does not
971 know about that file).
972
973 Though this request will be supported into the forseeable future, it has been
974 the source of numerous bug reports in the past due to the complexity of testing
975 this functionality via the test suite and client developers are encouraged not
976 to use it.  Instead, please consider munging conflicting names and maintaining
977 a map for communicating with the server.  For example, suppose the server sends
978 files @file{case}, @file{CASE}, and @file{CaSe}.  The client could write all
979 three files to names such as, @file{case}, @file{case_prefix_case}, and
980 @file{case_prefix_2_case} and maintain a mapping between the file names in, for
981 instance a new @file{CVS/Map} file.
982
983 @item Argument @var{text} \n
984 Response expected: no.
985 Save argument for use in a subsequent command.  Arguments
986 accumulate until an argument-using command is given, at which point
987 they are forgotten.
988
989 @item Argumentx @var{text} \n
990 Response expected: no.  Append \n followed by text to the current
991 argument being saved.
992
993 @item Global_option @var{option} \n
994 Response expected: no.
995 Transmit one of the global options @samp{-q}, @samp{-Q}, @samp{-l},
996 @samp{-t}, @samp{-r}, or @samp{-n}.  @var{option} must be one of those
997 strings, no variations (such as combining of options) are allowed.  For
998 graceful handling of @code{valid-requests}, it is probably better to
999 make new global options separate requests, rather than trying to add
1000 them to this request.
1001 The @code{Root} request need not have been previously sent.
1002
1003 @item Gzip-stream @var{level} \n
1004 Response expected: no.
1005 Use zlib (RFC 1950/1951) compression to compress all further communication
1006 between the client and the server.  As of @sc{cvs} 1.12.13, this request needs
1007 to be sent as the first non-rootless request if the server is configured
1008 with compression level restrictions and @var{level} is outside the restricted
1009 range.  After this request is sent, all further communication must be
1010 compressed.  All further data received from the server will also be
1011 compressed.  The @var{level} argument suggests to the server the level of
1012 compression that it should apply; it should be an integer between 0 and 9,
1013 inclusive, where @samp{0} means no compression and higher numbers indicate more
1014 compression.
1015
1016 @item Kerberos-encrypt \n
1017 Response expected: no.
1018 Use Kerberos encryption to encrypt all further communication between the
1019 client and the server.  This will only work if the connection was made
1020 over Kerberos in the first place.  If both the @code{Gzip-stream} and
1021 the @code{Kerberos-encrypt} requests are used, the
1022 @code{Kerberos-encrypt} request should be used first.  This will make
1023 the client and server encrypt the compressed data, as opposed to
1024 compressing the encrypted data.  Encrypted data is generally
1025 incompressible.
1026
1027 Note that this request does not fully prevent an attacker from hijacking
1028 the connection, in the sense that it does not prevent hijacking the
1029 connection between the initial authentication and the
1030 @code{Kerberos-encrypt} request.
1031
1032 @item Gssapi-encrypt \n
1033 Response expected: no.
1034 Use GSSAPI encryption to encrypt all further communication between the
1035 client and the server.  This will only work if the connection was made
1036 over GSSAPI in the first place.  See @code{Kerberos-encrypt}, above, for
1037 the relation between @code{Gssapi-encrypt} and @code{Gzip-stream}.
1038
1039 Note that this request does not fully prevent an attacker from hijacking
1040 the connection, in the sense that it does not prevent hijacking the
1041 connection between the initial authentication and the
1042 @code{Gssapi-encrypt} request.
1043
1044 @item Gssapi-authenticate \n
1045 Response expected: no.
1046 Use GSSAPI authentication to authenticate all further communication
1047 between the client and the server.  This will only work if the
1048 connection was made over GSSAPI in the first place.  Encrypted data is
1049 automatically authenticated, so using both @code{Gssapi-authenticate}
1050 and @code{Gssapi-encrypt} has no effect beyond that of
1051 @code{Gssapi-encrypt}.  Unlike encrypted data, it is reasonable to
1052 compress authenticated data.
1053
1054 Note that this request does not fully prevent an attacker from hijacking
1055 the connection, in the sense that it does not prevent hijacking the
1056 connection between the initial authentication and the
1057 @code{Gssapi-authenticate} request.
1058
1059 @item Set @var{variable}=@var{value} \n
1060 Response expected: no.
1061 Set a user variable @var{variable} to @var{value}.
1062 The @code{Root} request need not have been previously sent.
1063
1064 @item Hostname @var{hostname} \n
1065 Response expected: no.  Set the client hostname for an upcoming @code{edit}
1066 request.
1067
1068 @item LocalDir @var{hostname} \n
1069 Response expected: no.  Set the local client directory name for an upcoming
1070 @code{edit} request.
1071
1072 @item expand-modules \n
1073 Response expected: yes.  Expand the modules which are specified in the
1074 arguments.  Returns the data in @code{Module-expansion} responses.  Note
1075 that the server can assume that this is checkout or export, not rtag or
1076 rdiff; the latter do not access the working directory and thus have no
1077 need to expand modules on the client side.
1078
1079 Expand may not be the best word for what this request does.  It does not
1080 necessarily tell you all the files contained in a module, for example.
1081 Basically it is a way of telling you which working directories the
1082 server needs to know about in order to handle a checkout of the
1083 specified modules.
1084
1085 For example, suppose that the server has a module defined by
1086
1087 @example
1088 aliasmodule -a 1dir
1089 @end example
1090
1091 That is, one can check out @code{aliasmodule} and it will take
1092 @code{1dir} in the repository and check it out to @code{1dir} in the
1093 working directory.  Now suppose the client already has this module
1094 checked out and is planning on using the @code{co} request to update it.
1095 Without using @code{expand-modules}, the client would have two bad
1096 choices: it could either send information about @emph{all} working
1097 directories under the current directory, which could be unnecessarily
1098 slow, or it could be ignorant of the fact that @code{aliasmodule} stands
1099 for @code{1dir}, and neglect to send information for @code{1dir}, which
1100 would lead to incorrect operation.
1101 @c Those don't really seem like the only two options.  I mean, what
1102 @c about keeping track of the correspondence from when we first checked
1103 @c out a fresh directory?  Not that the CVS client does this, or that
1104 @c I've really thought about whether it would be a good idea...
1105
1106 With @code{expand-modules}, the client would first ask for the module to
1107 be expanded:
1108
1109 @example
1110 C: Root /home/kingdon/zwork/cvsroot
1111 . . .
1112 C: Argument aliasmodule
1113 C: Directory .
1114 C: .
1115 C: expand-modules
1116 S: Module-expansion 1dir
1117 S: ok
1118 @end example
1119
1120 and then it knows to check the @file{1dir} directory and send
1121 requests such as @code{Entry} and @code{Modified} for the files in that
1122 directory.
1123
1124 @item ci \n
1125 @itemx diff \n
1126 @itemx list \n
1127 @itemx tag \n
1128 @itemx status \n
1129 @itemx admin \n
1130 @itemx history \n
1131 @itemx watchers \n
1132 @itemx editors \n
1133 @itemx annotate \n
1134 Response expected: yes.  Actually do a cvs command.  This uses any
1135 previous @code{Argument}, @code{Directory}, @code{Entry}, or
1136 @code{Modified} requests, if they have been sent.  The
1137 last @code{Directory} sent specifies the working directory at the time
1138 of the operation.  No provision is made for any input from the user.
1139 This means that @code{ci} must use a @code{-m} argument if it wants to
1140 specify a log message.
1141
1142 @item log \n
1143 Response expected: yes.  Show information for past revisions.  This uses
1144 any previous @code{Directory}, @code{Entry}, or @code{Modified}
1145 requests, if they have been sent.  The last @code{Directory} sent
1146 specifies the working directory at the time of the operation.  Also uses
1147 previous @code{Argument}'s of which the canonical forms are the
1148 following (@sc{cvs} 1.10 and older clients sent what the user specified,
1149 but clients are encouraged to use the canonical forms and other forms
1150 are deprecated):
1151
1152 @table @code
1153 @item -b, -h, -l, -N, -R, -t
1154 These options go by themselves, one option per @code{Argument} request.
1155
1156 @item -d @var{date1}<@var{date2}
1157 Select revisions between @var{date1} and @var{date2}.  Either date
1158 may be omitted in which case there is no date limit at that end of the
1159 range (clients may specify dates such as 1 Jan 1970 or 1 Jan 2038 for
1160 similar purposes but this is problematic as it makes assumptions about
1161 what dates the server supports).  Dates are in RFC822/1123 format.  The
1162 @samp{-d} is one @code{Argument} request and the date range is a second
1163 one.
1164
1165 @item -d @var{date1}<=@var{date2}
1166 Likewise but compare dates for equality.
1167
1168 @item -d @var{singledate}
1169 Select the single, latest revision dated @var{singledate} or earlier.
1170
1171 To include several date ranges and/or singledates, repeat the @samp{-d}
1172 option as many times as necessary.
1173
1174 @item -r@var{rev1}:@var{rev2}
1175 @itemx -r@var{branch}
1176 @itemx -r@var{branch}.
1177 @itemx -r
1178 Specify revisions (note that @var{rev1} or @var{rev2} can be omitted, or
1179 can refer to branches).  Send both the @samp{-r} and the revision
1180 information in a single @code{Argument} request.  To include several
1181 revision selections, repeat the @samp{-r} option.
1182
1183 @item -s @var{state}
1184 @itemx -w
1185 @itemx -w@var{login}
1186 Select on states or users.  To include more than one state or user,
1187 repeat the option.  Send the @samp{-s} option as a separate argument
1188 from the state being selected.  Send the @samp{-w} option as part of the
1189 same argument as the user being selected.
1190 @end table
1191
1192 @item co \n
1193 Response expected: yes.  Get files from the repository.  This uses any
1194 previous @code{Argument}, @code{Directory}, @code{Entry}, or
1195 @code{Modified} requests, if they have been sent.  Arguments to this
1196 command are module names; the client cannot know what directories they
1197 correspond to except by (1) just sending the @code{co} request, and then
1198 seeing what directory names the server sends back in its responses, and
1199 (2) the @code{expand-modules} request.
1200
1201 @item export \n
1202 Response expected: yes.  Get files from the repository.  This uses any
1203 previous @code{Argument}, @code{Directory}, @code{Entry}, or
1204 @code{Modified} requests, if they have been sent.  Arguments to this
1205 command are module names, as described for the @code{co} request.  The
1206 intention behind this command is that a client can get sources from a
1207 server without storing CVS information about those sources.  That is, a
1208 client probably should not count on being able to take the entries line
1209 returned in the @code{Created} response from an @code{export} request
1210 and send it in a future @code{Entry} request.  Note that the entries
1211 line in the @code{Created} response must indicate whether the file is
1212 binary or text, so the client can create it correctly.
1213
1214 @item ls \n
1215 @itemx rannotate \n
1216 @itemx rdiff \n
1217 @itemx rlist \n
1218 @itemx rlog \n
1219 @itemx rtag \n
1220 Response expected: yes.  Actually do a cvs command.  This uses any
1221 previous @code{Argument} requests, if they have been sent.  The client
1222 should not send @code{Directory}, @code{Entry}, or @code{Modified}
1223 requests for these commands; they are not used.  Arguments to these
1224 commands are module names, as described for @code{co}.  @code{ls} is a
1225 synonym for @code{rlist}, for compatibility with CVSNT.
1226
1227 @item init @var{root-name} \n
1228 Response expected: yes.  If it doesn't already exist, create a @sc{cvs}
1229 repository @var{root-name}.  Note that @var{root-name} is a local
1230 directory and @emph{not} a fully qualified @code{CVSROOT} variable.
1231 The @code{Root} request need not have been previously sent.
1232
1233 @item suck \n
1234 Response expected: yes.
1235 Actually do a @code{cvs suck} command.
1236 This uses a previous @code{Argument} request (only one, because the
1237 @code{cvs suck} CLI command takes only one).
1238 This is an extension specific to MirBSD, MirPorts and Debian.
1239
1240 @item update \n
1241 Response expected: yes.  Actually do a @code{cvs update} command.  This
1242 uses any previous @code{Argument}, @code{Directory}, @code{Entry},
1243 or @code{Modified} requests, if they have been sent.  The
1244 last @code{Directory} sent specifies the working directory at the time
1245 of the operation.  The @code{-I} option is not used--files which the
1246 client can decide whether to ignore are not mentioned and the client
1247 sends the @code{Questionable} request for others.
1248
1249 @item import \n
1250 Response expected: yes.  Actually do a @code{cvs import} command.  This
1251 uses any previous @code{Argument}, @code{Directory}, @code{Entry}, or
1252 @code{Modified} requests, if they have been sent.  The
1253 last @code{Directory} sent specifies the working directory at the time
1254 of the operation - unlike most commands, the repository field of each
1255 @code{Directory} request is ignored (it merely must point somewhere
1256 within the root).  The files to be imported are sent in @code{Modified}
1257 requests (files which the client knows should be ignored are not sent;
1258 the server must still process the CVSROOT/cvsignore file unless -I ! is
1259 sent).  A log message must have been specified with a @code{-m}
1260 argument.
1261
1262 @item add \n
1263 Response expected: yes.  Add a file or directory.  This uses any
1264 previous @code{Argument}, @code{Directory}, @code{Entry}, or
1265 @code{Modified} requests, if they have been sent.  The
1266 last @code{Directory} sent specifies the working directory at the time
1267 of the operation.
1268
1269 To add a directory, send the directory to be added using
1270 @code{Directory} and @code{Argument} requests.  For example:
1271
1272 @example
1273 C: Root /u/cvsroot
1274 . . .
1275 C: Argument nsdir
1276 C: Directory nsdir
1277 C: 1dir/nsdir
1278 C: Directory .
1279 C: 1dir
1280 C: add
1281 S: M Directory /u/cvsroot/1dir/nsdir put under version control
1282 S: ok
1283 @end example
1284
1285 You will notice that the server does not signal to the client in any
1286 particular way that the directory has been successfully added.  The
1287 client is supposed to just assume that the directory has been added and
1288 update its records accordingly.  Note also that adding a directory is
1289 immediate; it does not wait until a @code{ci} request as files do.
1290
1291 To add a file, send the file to be added using a @code{Modified}
1292 request.  For example:
1293
1294 @example
1295 C: Argument nfile
1296 C: Directory .
1297 C: 1dir
1298 C: Modified nfile
1299 C: u=rw,g=r,o=r
1300 C: 6
1301 C: hello
1302 C: add
1303 S: E cvs server: scheduling file `nfile' for addition
1304 S: Mode u=rw,g=r,o=r
1305 S: Checked-in ./
1306 S: /u/cvsroot/1dir/nfile
1307 S: /nfile/0///
1308 S: E cvs server: use 'cvs commit' to add this file permanently
1309 S: ok
1310 @end example
1311
1312 Note that the file has not been added to the repository; the only effect
1313 of a successful @code{add} request, for a file, is to supply the client
1314 with a new entries line containing @samp{0} to indicate an added file.
1315 In fact, the client probably could perform this operation without
1316 contacting the server, although using @code{add} does cause the server
1317 to perform a few more checks.
1318
1319 The client sends a subsequent @code{ci} to actually add the file to the
1320 repository.
1321
1322 Another quirk of the @code{add} request is that with CVS 1.9 and older,
1323 a pathname specified in
1324 an @code{Argument} request cannot contain @samp{/}.  There is no good
1325 reason for this restriction, and in fact more recent CVS servers don't
1326 have it.
1327 But the way to interoperate with the older servers is to ensure that
1328 all @code{Directory} requests for @code{add} (except those used to add
1329 directories, as described above), use @samp{.} for
1330 @var{local-directory}.  Specifying another string for
1331 @var{local-directory} may not get an error, but it will get you strange
1332 @code{Checked-in} responses from the buggy servers.
1333
1334 @item remove \n
1335 Response expected: yes.  Remove a file.  This uses any
1336 previous @code{Argument}, @code{Directory}, @code{Entry}, or
1337 @code{Modified} requests, if they have been sent.  The
1338 last @code{Directory} sent specifies the working directory at the time
1339 of the operation.
1340
1341 Note that this request does not actually do anything to the repository;
1342 the only effect of a successful @code{remove} request is to supply the
1343 client with a new entries line containing @samp{-} to indicate a removed
1344 file.  In fact, the client probably could perform this operation without
1345 contacting the server, although using @code{remove} may cause the server
1346 to perform a few more checks.
1347
1348 The client sends a subsequent @code{ci} request to actually record the
1349 removal in the repository.
1350
1351 @item edit \n
1352 Response expected: yes.  Actually do the @code{cvs edit} command.  This uses
1353 any previous @code{Argument}, @code{Directory}, @code{Entry}, @code{LocalDir},
1354 or @code{Hostname} requests, if they have been sent.  Unless the user has
1355 requested that edits not be granted unless no one else is editing a file, a
1356 local edit followed by an attempt to send @code{Notify} requests to the
1357 server is preferred.
1358
1359 @item watch-on \n
1360 @itemx watch-off \n
1361 @itemx watch-add \n
1362 @itemx watch-remove \n
1363 Response expected: yes.  Actually do the @code{cvs watch on}, @code{cvs
1364 watch off}, @code{cvs watch add}, and @code{cvs watch remove} commands,
1365 respectively.  This uses any previous @code{Argument},
1366 @code{Directory}, @code{Entry}, or @code{Modified}
1367 requests, if they have been sent.  The last @code{Directory} sent
1368 specifies the working directory at the time of the operation.
1369
1370 @item release \n
1371 Response expected: yes.  Note that a @code{cvs release} command has
1372 taken place and update the history file accordingly.
1373
1374 @item global-list-quiet \n
1375 Response expected: yes.  This request is a synonym for noop, but its existance
1376 notifies the client that a @code{-q} option to @code{list} and @code{rlist}
1377 will be rejected.  This, in a reverse-logic sort of way, is here so that when
1378 it @emph{isn't} received, as for instance from CVSNT, the client will know that
1379 the quiet option has to be sent as a command option rather than a global
1380 option.
1381
1382 @item noop \n
1383 Response expected: yes.  This request is a null command in the sense
1384 that it doesn't do anything, but merely (as with any other requests
1385 expecting a response) sends back any responses pertaining to pending
1386 errors, pending @code{Notified} responses, etc.
1387 The @code{Root} request need not have been previously sent.
1388
1389 @item update-patches \n
1390 Response expected: yes.
1391 This request does not actually do anything.  It is used as a signal that
1392 the server is able to generate patches when given an @code{update}
1393 request.  The client must issue the @code{-u} argument to @code{update}
1394 in order to receive patches.
1395
1396 @item gzip-file-contents @var{level} \n
1397 Response expected: no.  Note that this request does not follow the
1398 response convention stated above.  @code{Gzip-stream} is suggested
1399 instead of @code{gzip-file-contents} as it gives better compression; the
1400 only reason to implement the latter is to provide compression with
1401 @sc{cvs} 1.8 and earlier.  The @code{gzip-file-contents} request asks
1402 the server to compress files it sends to the client using @code{gzip}
1403 (RFC1952/1951) compression, using the specified level of compression.
1404 If this request is not made, the server must not compress files.
1405
1406 This is only a hint to the server.  It may still decide (for example, in
1407 the case of very small files, or files that already appear to be
1408 compressed) not to do the compression.  Compression is indicated by a
1409 @samp{z} preceding the file length.
1410
1411 Availability of this request in the server indicates to the client that
1412 it may compress files sent to the server, regardless of whether the
1413 client actually uses this request.
1414
1415 @item wrapper-sendme-rcsOptions \n
1416 Response expected: yes.
1417 Request that the server transmit mappings from filenames to keyword
1418 expansion modes in @code{Wrapper-rcsOption} responses.
1419
1420 @item version \n
1421 Response expected: yes.
1422 Request that the server transmit its version message.
1423 The @code{Root} request need not have been previously sent.
1424
1425 @item @var{other-request} @var{text} \n
1426 Response expected: yes.
1427 Any unrecognized request expects a response, and does not
1428 contain any additional data.  The response will normally be something like
1429 @samp{error  unrecognized request}, but it could be a different error if
1430 a previous request which doesn't expect a response produced an error.
1431 @end table
1432
1433 When the client is done, it drops the connection.
1434
1435 @node Response intro
1436 @section Introduction to Responses
1437
1438 After a command which expects a response, the server sends however many
1439 of the following responses are appropriate.  The server should not send
1440 data at other times (the current implementation may violate this
1441 principle in a few minor places, where the server is printing an error
1442 message and exiting---this should be investigated further).
1443
1444 Any set of responses always ends with @samp{error} or @samp{ok}.  This
1445 indicates that the response is over.
1446
1447 @c "file updating response" and "file update modifying response" are
1448 @c lame terms (mostly because they are so awkward).  Any better ideas?
1449 The responses @code{Checked-in}, @code{New-entry}, @code{Updated},
1450 @code{Created}, @code{Update-existing}, @code{Merged}, and
1451 @code{Patched} are refered to as @dfn{file updating} responses, because
1452 they change the status of a file in the working directory in some way.
1453 The responses @code{Mode}, @code{Mod-time}, and @code{Checksum} are
1454 referred to as @dfn{file update modifying} responses because they modify
1455 the next file updating response.  In no case shall a file update
1456 modifying response apply to a file updating response other than the next
1457 one.  Nor can the same file update modifying response occur twice for
1458 a given file updating response (if servers diagnose this problem, it may
1459 aid in detecting the case where clients send an update modifying
1460 response without following it by a file updating response).
1461
1462 @node Response pathnames
1463 @section The "pathname" in responses
1464
1465 Many of the responses contain something called @var{pathname}.
1466 @c FIXME: should better document when the specified repository needs to
1467 @c end in "/.".
1468 The name is somewhat misleading; it actually indicates a pair of
1469 pathnames.  First, a local directory name
1470 relative to the directory in which the command was given (i.e. the last
1471 @code{Directory} before the command).  Then a linefeed and a repository
1472 name.  Then a slash and the filename (without a @samp{,v} ending).
1473
1474 The repository name may be absolute or relative to the @var{pathname}
1475 sent with the @code{Root} request.  If absolute, the repository name must begin
1476 with the @var{pathname} sent with the @code{Root} request.  Relative or
1477 absolute, the repository name must specify a path underneath the @code{Root}
1478 @var{pathname}.
1479
1480 For example, for a file @file{i386.mh}
1481 which is in the local directory @file{gas.clean/config} and for which
1482 the repository name is @file{devo/gas/config}:
1483
1484 @example
1485 gas.clean/config/
1486 devo/gas/config/i386.mh
1487 @end example
1488
1489 If the server wants to tell the client to create a directory, then it
1490 merely uses the directory in any response, as described above, and the
1491 client should create the directory if it does not exist.  Note that this
1492 should only be done one directory at a time, in order to permit the
1493 client to correctly store the repository for each directory.  Servers
1494 can use requests such as @code{Clear-sticky},
1495 @code{Clear-static-directory}, or any other requests, to create
1496 directories.
1497 @c FIXME: Need example here of how "repository" needs to be sent for
1498 @c each directory, and cannot be correctly deduced from, say, the most
1499 @c deeply nested directory.
1500
1501 Some server
1502 implementations may poorly distinguish between a directory which should
1503 not exist and a directory which contains no files; in order to refrain
1504 from creating empty directories a client should both send the @samp{-P}
1505 option to @code{update} or @code{co}, and should also detect the case in
1506 which the server asks to create a directory but not any files within it
1507 (in that case the client should remove the directory or refrain from
1508 creating it in the first place).  Note that servers could clean this up
1509 greatly by only telling the client to create directories if the
1510 directory in question should exist, but until servers do this, clients
1511 will need to offer the @samp{-P} behavior described above.
1512
1513 @node Responses
1514 @section Responses
1515
1516 Here are the responses:
1517
1518 @table @code
1519 @item Valid-requests @var{request-list} \n
1520 Indicate what requests the server will accept.  @var{request-list}
1521 is a space separated list of tokens.  If the server supports sending
1522 patches, it will include @samp{update-patches} in this list.  The
1523 @samp{update-patches} request does not actually do anything.
1524
1525 @item Force-gzip \n
1526 Response expected: no.
1527 Indicates that the server requires compression.  The client must send a
1528 @code{Gzip-stream} request, though the requested @var{level} may be @samp{0}.
1529
1530 @item Referrer @var{CVSROOT}
1531 Request that the client store @var{CVSROOT} as the name of this server and that
1532 this name be passed via a @code{Referrer} @emph{request} to any subsequent
1533 servers contacted as a result of a @code{Redirect} response.  This can be
1534 useful to allow the secondary administrator to configure the @code{CVSROOT} the
1535 primary should use to update the secondary in case the client uses a
1536 non-standard name or even a name that is unique to the client for some reason.
1537
1538 @item Redirect @var{CVSROOT}
1539 Request that the client redirect its connection to @var{CVSROOT} and begin
1540 again.  This response is only valid in response to a @code{Command-prep}
1541 request.  If a client receives this response, it is expected to notify the
1542 write server it subsequently contacts of the CVSROOT of the server which
1543 redirected it using the @samp{Referrer} request.  This information makes it
1544 possible for primary servers to update the client's mirror first, hopefully
1545 minimizing race conditions on subsequent updates from the same client.
1546
1547 @item Checked-in @var{pathname} \n
1548 Additional data: New Entries line, \n.  This means a file @var{pathname}
1549 has been successfully operated on (checked in, added, etc.).  name in
1550 the Entries line is the same as the last component of @var{pathname}.
1551
1552 @item New-entry @var{pathname} \n
1553 Additional data: New Entries line, \n.  Like @code{Checked-in}, but the
1554 file is not up to date.
1555
1556 @item Updated @var{pathname} \n
1557 Additional data: New Entries line, \n, mode, \n, file transmission.  A
1558 new copy of the file is enclosed.  This is used for a new revision of an
1559 existing file, or for a new file, or for any other case in which the
1560 local (client-side) copy of the file needs to be updated, and after
1561 being updated it will be up to date.  If any directory in pathname does
1562 not exist, create it.  This response is not used if @code{Created} and
1563 @code{Update-existing} are supported.
1564
1565 @item Created @var{pathname} \n
1566 This is just like @code{Updated} and takes the same additional data, but
1567 is used only if no @code{Entry}, @code{Modified}, or
1568 @code{Unchanged} request has been sent for the file in question.  The
1569 distinction between @code{Created} and @code{Update-existing} is so
1570 that the client can give an error message in several cases: (1) there is
1571 a file in the working directory, but not one for which @code{Entry},
1572 @code{Modified}, or @code{Unchanged} was sent (for example, a file which
1573 was ignored, or a file for which @code{Questionable} was sent), (2)
1574 there is a file in the working directory whose name differs from the one
1575 mentioned in @code{Created} in ways that the client is unable to use to
1576 distinguish files.  For example, the client is case-insensitive and the
1577 names differ only in case.
1578
1579 @item Update-existing @var{pathname} \n
1580 This is just like @code{Updated} and takes the same additional data, but
1581 is used only if a @code{Entry}, @code{Modified}, or @code{Unchanged}
1582 request has been sent for the file in question.
1583
1584 This response, or @code{Merged}, indicates that the server has
1585 determined that it is OK to overwrite the previous contents of the file
1586 specified by @var{pathname}.  Provided that the client has correctly
1587 sent @code{Modified} or @code{Is-modified} requests for a modified file,
1588 and the file was not modified while CVS was running, the server can
1589 ensure that a user's modifications are not lost.
1590
1591 @item Merged @var{pathname} \n
1592 This is just like @code{Updated} and takes the same additional data,
1593 with the one difference that after the new copy of the file is enclosed,
1594 it will still not be up to date.  Used for the results of a merge, with
1595 or without conflicts.
1596
1597 It is useful to preserve an copy of what the file looked like before the
1598 merge.  This is basically handled by the server; before sending
1599 @code{Merged} it will send a @code{Copy-file} response.  For example, if
1600 the file is @file{aa} and it derives from revision 1.3, the
1601 @code{Copy-file} response will tell the client to copy @file{aa} to
1602 @file{.#aa.1.3}.  It is up to the client to decide how long to keep this
1603 file around; traditionally clients have left it around forever, thus
1604 letting the user clean it up as desired.  But another answer, such as
1605 until the next commit, might be preferable.
1606
1607 @item Rcs-diff @var{pathname} \n
1608 This is just like @code{Updated} and takes the same additional data,
1609 with the one difference that instead of sending a new copy of the file,
1610 the server sends an RCS change text.  This change text is produced by
1611 @samp{diff -n} (the GNU diff @samp{-a} option may also be used).  The
1612 client must apply this change text to the existing file.  This will only
1613 be used when the client has an exact copy of an earlier revision of a
1614 file.  This response is only used if the @code{update} command is given
1615 the @samp{-u} argument.
1616
1617 @item Patched @var{pathname} \n
1618 This is just like @code{Rcs-diff} and takes the same additional data,
1619 except that it sends a standard patch rather than an RCS change text.
1620 The patch is produced by @samp{diff -c} for @sc{cvs} 1.6 and later (see
1621 POSIX.2 for a description of this format), or @samp{diff -u} for
1622 previous versions of @sc{cvs}; clients are encouraged to accept either
1623 format.  Like @code{Rcs-diff}, this response is only used if the
1624 @code{update} command is given the @samp{-u} argument.
1625
1626 The @code{Patched} response is deprecated in favor of the
1627 @code{Rcs-diff} response.  However, older clients (CVS 1.9 and earlier)
1628 only support @code{Patched}.
1629
1630 @item Edit-file @var{pathname} \n
1631 Do the client-side portion of editing a file.
1632
1633 @item Mode @var{mode} \n
1634 This @var{mode} applies to the next file mentioned in
1635 @code{Checked-in}.  @code{Mode} is a file update modifying response
1636 as described in @ref{Response intro}.
1637
1638 @item Mod-time @var{time} \n
1639 Set the modification time of the next file sent to @var{time}.
1640 @code{Mod-time} is a file update modifying response
1641 as described in @ref{Response intro}.
1642 The
1643 @var{time} is in the format specified by RFC822 as modified by RFC1123.
1644 The server may specify any timezone it chooses; clients will want to
1645 convert that to their own timezone as appropriate.  An example of this
1646 format is:
1647
1648 @example
1649 26 May 1997 13:01:40 -0400
1650 @end example
1651
1652 There is no requirement that the client and server clocks be
1653 synchronized.  The server just sends its recommendation for a timestamp
1654 (based on its own clock, presumably), and the client should just believe
1655 it (this means that the time might be in the future, for example).
1656
1657 If the server does not send @code{Mod-time} for a given file, the client
1658 should pick a modification time in the usual way (usually, just let the
1659 operating system set the modification time to the time that the CVS
1660 command is running).
1661
1662 @item Checksum @var{checksum}\n
1663 The @var{checksum} applies to the next file sent (that is,
1664 @code{Checksum} is a file update modifying response
1665 as described in @ref{Response intro}).
1666 In the case of
1667 @code{Patched}, the checksum applies to the file after being patched,
1668 not to the patch itself.  The client should compute the checksum itself,
1669 after receiving the file or patch, and signal an error if the checksums
1670 do not match.  The checksum is the 128 bit MD5 checksum represented as
1671 32 hex digits (MD5 is described in RFC1321).
1672 This response is optional, and is only used if the
1673 client supports it (as judged by the @code{Valid-responses} request).
1674
1675 @item Copy-file @var{pathname} \n
1676 Additional data: @var{newname} \n.  Copy file @var{pathname} to
1677 @var{newname} in the same directory where it already is.  This does not
1678 affect @code{CVS/Entries}.
1679
1680 This can optionally be implemented as a rename instead of a copy.  The
1681 only use for it which currently has been identified is prior to a
1682 @code{Merged} response as described under @code{Merged}.  Clients can
1683 probably assume that is how it is being used, if they want to worry
1684 about things like how long to keep the @var{newname} file around.
1685
1686 @item Removed @var{pathname} \n
1687 The file has been removed from the repository (this is the case where
1688 cvs prints @samp{file foobar.c is no longer pertinent}).
1689
1690 @item Remove-entry @var{pathname} \n
1691 The file needs its entry removed from @code{CVS/Entries}, but the file
1692 itself is already gone (this happens in response to a @code{ci} request
1693 which involves committing the removal of a file).
1694
1695 @item Set-static-directory @var{pathname} \n
1696 This instructs the client to set the @code{Entries.Static} flag, which
1697 it should then send back to the server in a @code{Static-directory}
1698 request whenever the directory is operated on.  @var{pathname} ends in a
1699 slash; its purpose is to specify a directory, not a file within a
1700 directory.
1701
1702 @item Clear-static-directory @var{pathname} \n
1703 Like @code{Set-static-directory}, but clear, not set, the flag.
1704
1705 @item Set-sticky @var{pathname} \n
1706 Additional data: @var{tagspec} \n.  Tell the client to set a sticky tag
1707 or date, which should be supplied with the @code{Sticky} request for
1708 future operations.  @var{pathname} ends in a slash; its purpose is to
1709 specify a directory, not a file within a directory.  The client should
1710 store @var{tagspec} and pass it back to the server as-is, to allow for
1711 future expansion.  The first character of @var{tagspec} is @samp{T} for
1712 a tag, @samp{D} for a date, or something else for future expansion.  The
1713 remainder of @var{tagspec} contains the actual tag or date.
1714
1715 @item Clear-sticky @var{pathname} \n
1716 Clear any sticky tag or date set by @code{Set-sticky}.
1717
1718 @item Template @var{pathname} \n
1719 Additional data: file transmission (note: compressed file transmissions
1720 are not supported).  @var{pathname} ends in a slash; its purpose is to
1721 specify a directory, not a file within a directory.  Tell the client to
1722 store the file transmission as the template log message, and then use
1723 that template in the future when prompting the user for a log message.
1724
1725 @item Set-checkin-prog @var{dir} \n
1726 Additional data: @var{prog} \n.  Tell the client to set a checkin
1727 program, which should be supplied with the @code{Checkin-prog} request
1728 for future operations.
1729
1730 @item Set-update-prog @var{dir} \n
1731 Additional data: @var{prog} \n.  Tell the client to set an update
1732 program, which should be supplied with the @code{Update-prog} request
1733 for future operations.
1734
1735 @item Notified @var{pathname} \n
1736 Indicate to the client that the notification for @var{pathname} has been
1737 done.  There should be one such response for every @code{Notify}
1738 request; if there are several @code{Notify} requests for a single file,
1739 the requests should be processed in order; the first @code{Notified}
1740 response pertains to the first @code{Notify} request, etc.
1741
1742 @item Module-expansion @var{pathname} \n
1743 Return a file or directory
1744 which is included in a particular module.  @var{pathname} is relative
1745 to cvsroot, unlike most pathnames in responses.  @var{pathname} should
1746 be used to look and see whether some or all of the module exists on
1747 the client side; it is not necessarily suitable for passing as an
1748 argument to a @code{co} request (for example, if the modules file
1749 contains the @samp{-d} option, it will be the directory specified with
1750 @samp{-d}, not the name of the module).
1751
1752 @item Wrapper-rcsOption @var{pattern} -k '@var{option}' \n
1753 Transmit to the client a filename pattern which implies a certain
1754 keyword expansion mode.  The @var{pattern} is a wildcard pattern (for
1755 example, @samp{*.exe}.  The @var{option} is @samp{b} for binary, and so
1756 on.  Note that although the syntax happens to resemble the syntax in
1757 certain CVS configuration files, it is more constrained; there must be
1758 exactly one space between @var{pattern} and @samp{-k} and exactly one
1759 space between @samp{-k} and @samp{'}, and no string is permitted in
1760 place of @samp{-k} (extensions should be done with new responses, not by
1761 extending this one, for graceful handling of @code{Valid-responses}).
1762
1763 @item M @var{text} \n
1764 A one-line message for the user.
1765 Note that the format of @var{text} is not designed for machine parsing.
1766 Although sometimes scripts and clients will have little choice, the
1767 exact text which is output is subject to vary at the discretion of the
1768 server and the example output given in this document is just that,
1769 example output.  Servers are encouraged to use the @samp{MT} response,
1770 and future versions of this document will hopefully standardize more of
1771 the @samp{MT} tags; see @ref{Text tags}.
1772
1773 @item Mbinary \n
1774 Additional data: file transmission (note: compressed file transmissions
1775 are not supported).  This is like @samp{M}, except the contents of the
1776 file transmission are binary and should be copied to standard output
1777 without translation to local text file conventions.  To transmit a text
1778 file to standard output, servers should use a series of @samp{M} requests.
1779
1780 @item E @var{text} \n
1781 Same as @code{M} but send to stderr not stdout.
1782
1783 @item F \n
1784 @c FIXME: The second sentence, defining "flush", is somewhat off the top
1785 @c of my head.  Is there some text we can steal from ANSI C or someplace
1786 @c which is more carefully thought out?
1787 Flush stderr.  That is, make it possible for the user to see what has
1788 been written to stderr (it is up to the implementation to decide exactly
1789 how far it should go to ensure this).
1790
1791 @item MT @var{tagname} @var{data} \n
1792
1793 This response provides for tagged text.  It is similar to
1794 SGML/HTML/XML in that the data is structured and a naive application
1795 can also make some sense of it without understanding the structure.
1796 The syntax is not SGML-like, however, in order to fit into the CVS
1797 protocol better and (more importantly) to make it easier to parse,
1798 especially in a language like perl or awk.
1799
1800 The @var{tagname} can have several forms.  If it starts with @samp{a}
1801 to @samp{z} or @samp{A} to @samp{Z}, then it represents tagged text.
1802 If the implementation recognizes @var{tagname}, then it may interpret
1803 @var{data} in some particular fashion.  If the implementation does not
1804 recognize @var{tagname}, then it should simply treat @var{data} as
1805 text to be sent to the user (similar to an @samp{M} response).  There
1806 are two tags which are general purpose.  The @samp{text} tag is
1807 similar to an unrecognized tag in that it provides text which will
1808 ordinarily be sent to the user.  The @samp{newline} tag is used
1809 without @var{data} and indicates that a newline will ordinarily be
1810 sent to the user (there is no provision for embedding newlines in the
1811 @var{data} of other tagged text responses).
1812
1813 If @var{tagname} starts with @samp{+} it indicates a start tag and if
1814 it starts with @samp{-} it indicates an end tag.  The remainder of
1815 @var{tagname} should be the same for matching start and end tags, and
1816 tags should be nested (for example one could have tags in the
1817 following order @code{+bold} @code{+italic} @code{text} @code{-italic}
1818 @code{-bold} but not @code{+bold} @code{+italic} @code{text}
1819 @code{-bold} @code{-italic}).  A particular start and end tag may be
1820 documented to constrain the tagged text responses which are valid
1821 between them.
1822
1823 Note that if @var{data} is present there will always be exactly one
1824 space between @var{tagname} and @var{data}; if there is more than one
1825 space, then the spaces beyond the first are part of @var{data}.
1826
1827 Here is an example of some tagged text responses.  Note that there is
1828 a trailing space after @samp{Checking in} and @samp{initial revision:}
1829 and there are two trailing spaces after @samp{<--}.  Such trailing
1830 spaces are, of course, part of @var{data}.
1831
1832 @example
1833 MT +checking-in
1834 MT text Checking in 
1835 MT fname gz.tst
1836 MT text ;
1837 MT newline
1838 MT rcsfile /home/kingdon/zwork/cvsroot/foo/gz.tst,v
1839 MT text   <--  
1840 MT fname gz.tst
1841 MT newline
1842 MT text initial revision: 
1843 MT init-rev 1.1
1844 MT newline
1845 MT text done
1846 MT newline
1847 MT -checking-in
1848 @end example
1849
1850 If the client does not support the @samp{MT} response, the same
1851 responses might be sent as:
1852
1853 @example
1854 M Checking in gz.tst;
1855 M /home/kingdon/zwork/cvsroot/foo/gz.tst,v  <--  gz.tst
1856 M initial revision: 1.1
1857 M done
1858 @end example
1859
1860 For a list of specific tags, see @ref{Text tags}.
1861
1862 @item error @var{errno-code} @samp{ } @var{text} \n
1863 The command completed with an error.  @var{errno-code} is a symbolic
1864 error code (e.g. @code{ENOENT}); if the server doesn't support this
1865 feature, or if it's not appropriate for this particular message, it just
1866 omits the errno-code (in that case there are two spaces after
1867 @samp{error}).  Text is an error message such as that provided by
1868 strerror(), or any other message the server wants to use.
1869 The @var{text} is like the @code{M} response, in the sense that it is
1870 not particularly intended to be machine-parsed; servers may wish to
1871 print an error message with @code{MT} responses, and then issue a
1872 @code{error} response without @var{text} (although it should be noted
1873 that @code{MT} currently has no way of flagging the output as intended
1874 for standard error, the way that the @code{E} response does).
1875
1876 @item ok \n
1877 The command completed successfully.
1878 @end table
1879
1880 @node Text tags
1881 @section Tags for the MT tagged text response
1882
1883 The @code{MT} response, as described in @ref{Responses}, offers a
1884 way for the server to send tagged text to the client.  This section
1885 describes specific tags.  The intention is to update this section as
1886 servers add new tags.
1887
1888 In the following descriptions, @code{text} and @code{newline} tags are
1889 omitted.  Such tags contain information which is intended for users (or
1890 to be discarded), and are subject to change at the whim of the server.
1891 To avoid being vulnerable to such whim, clients should look for the tags
1892 listed here, not @code{text}, @code{newline}, or other tags.
1893
1894 The following tag means to indicate to the user that a file has been
1895 updated.  It is more or less redundant with the @code{Created} and
1896 @code{Update-existing} responses, but we don't try to specify here
1897 whether it occurs in exactly the same circumstances as @code{Created}
1898 and @code{Update-existing}.  The @var{name} is the pathname of the file
1899 being updated relative to the directory in which the command is
1900 occurring (that is, the last @code{Directory} request which is sent
1901 before the command).
1902
1903 @example
1904 MT +updated
1905 MT fname @var{name}
1906 MT -updated
1907 @end example
1908
1909 The @code{importmergecmd} tag is used when doing an import which has
1910 conflicts, or when doing an import with the @samp{-X} flag.
1911 The client can use it to report how to merge in the newly
1912 imported changes.  The @var{count} is the number of conflicts, or the
1913 string @code{No} if no conflicts occurred.  (The latter will only be
1914 sent for imports run with the @samp{-X} flag.)  The
1915 newly imported changes can be merged by running the following command:
1916 @smallexample
1917 cvs checkout -j @var{tag1} -j @var{tag2} @var{repository}
1918 @end smallexample
1919
1920 @example
1921 MT +importmergecmd
1922 MT conflicts @var{count}
1923 MT mergetag1 @var{tag1}
1924 MT mergetag2 @var{tag2}
1925 MT repository @var{repository}
1926 MT -importmergecmd
1927 @end example
1928
1929 @node Example
1930 @section Example
1931
1932 @c The C:/S: convention is in imitation of RFC1869 (and presumably
1933 @c other RFC's).  In other formatting concerns, we might want to think
1934 @c about whether there is an easy way to provide RFC1543 formatting
1935 @c (without negating the advantages of texinfo), and whether we should
1936 @c use RFC2234 BNF (I fear that would be less clear than
1937 @c what we do now, however).  Plus what about RFC2119 terminology (MUST,
1938 @c SHOULD, &c) or ISO terminology (shall, should, or whatever they are)?
1939 Here is an example; lines are prefixed by @samp{C: } to indicate the
1940 client sends them or @samp{S: } to indicate the server sends them.
1941
1942 The client starts by connecting, sending the root, and completing the
1943 protocol negotiation.  In actual practice the lists of valid responses
1944 and requests would be longer.
1945 @c The reason that we artificially shorten the lists is to avoid phony
1946 @c line breaks.  Any better solutions?
1947 @c Other than that, this exchange is taken verbatim from the data
1948 @c exchanged by CVS (as of Nov 1996).  That is why some of the requests and
1949 @c reponses are not quite what you would pick for pedagogical purposes.
1950
1951 @example
1952 C: Root /u/cvsroot
1953 C: Valid-responses ok error Checked-in M E
1954 C: valid-requests
1955 S: Valid-requests Root Directory Entry Modified Argument Argumentx ci co
1956 S: ok
1957 C: UseUnchanged
1958 @end example
1959
1960 The client wants to check out the @code{supermunger} module into a fresh
1961 working directory.  Therefore it first expands the @code{supermunger}
1962 module; this step would be omitted if the client was operating on a
1963 directory rather than a module.
1964 @c Why does it send Directory here?  The description of expand-modules
1965 @c doesn't really say much of anything about what use, if any, it makes of
1966 @c Directory and similar requests sent previously.
1967
1968 @example
1969 C: Argument supermunger
1970 C: Directory .
1971 C: .
1972 C: expand-modules
1973 @end example
1974
1975 The server replies that the @code{supermunger} module expands to the
1976 directory @code{supermunger} (the simplest case):
1977
1978 @example
1979 S: Module-expansion supermunger
1980 S: ok
1981 @end example
1982
1983 The client then proceeds to check out the directory.  The fact that it
1984 sends only a single @code{Directory} request which specifies @samp{.}
1985 for the working directory means that there is not already a
1986 @code{supermunger} directory on the client.
1987 @c What is -N doing here?
1988
1989 @example
1990 C: Argument -N
1991 C: Argument supermunger
1992 C: Directory .
1993 C: .
1994 C: co
1995 @end example
1996
1997 The server replies with the requested files.  In this example, there is
1998 only one file, @file{mungeall.c}.  The @code{Clear-sticky} and
1999 @code{Clear-static-directory} requests are sent by the current
2000 implementation but they have no effect because the default is for those
2001 settings to be clear when a directory is newly created.
2002
2003 @example
2004 S: Clear-sticky supermunger/
2005 S: /u/cvsroot/supermunger/
2006 S: Clear-static-directory supermunger/
2007 S: /u/cvsroot/supermunger/
2008 S: E cvs server: Updating supermunger
2009 S: M U supermunger/mungeall.c
2010 S: Created supermunger/
2011 S: /u/cvsroot/supermunger/mungeall.c
2012 S: /mungeall.c/1.1///
2013 S: u=rw,g=r,o=r
2014 S: 26
2015 S: int mein () @{ abort (); @}
2016 S: ok
2017 @end example
2018
2019 The current client implementation would break the connection here and make a
2020 new connection for the next command.  However, the protocol allows it
2021 to keep the connection open and continue, which is what we show here.
2022
2023 After the user modifies the file and instructs the client to check it
2024 back in.  The client sends arguments to specify the log message and file
2025 to check in:
2026
2027 @example
2028 C: Argument -m
2029 C: Argument Well, you see, it took me hours and hours to find
2030 C: Argumentx this typo and I searched and searched and eventually
2031 C: Argumentx had to ask John for help.
2032 C: Argument mungeall.c
2033 @end example
2034
2035 It also sends information about the contents of the working directory,
2036 including the new contents of the modified file.  Note that the user has
2037 changed into the @file{supermunger} directory before executing this
2038 command; the top level directory is a user-visible concept because the
2039 server should print filenames in @code{M} and @code{E} responses
2040 relative to that directory.
2041 @c We are waving our hands about the order of the requests.  "Directory"
2042 @c and "Argument" can be in any order, but this probably isn't specified
2043 @c very well.
2044
2045 @example
2046 C: Directory .
2047 C: supermunger
2048 C: Entry /mungeall.c/1.1///
2049 C: Modified mungeall.c
2050 C: u=rw,g=r,o=r
2051 C: 26
2052 C: int main () @{ abort (); @}
2053 @end example
2054
2055 And finally, the client issues the checkin command (which makes use of
2056 the data just sent):
2057
2058 @example
2059 C: ci
2060 @end example
2061
2062 And the server tells the client that the checkin succeeded:
2063
2064 @example
2065 S: M Checking in mungeall.c;
2066 S: E /u/cvsroot/supermunger/mungeall.c,v  <--  mungeall.c
2067 S: E new revision: 1.2; previous revision: 1.1
2068 S: E done
2069 S: Mode u=rw,g=r,o=r
2070 S: Checked-in ./
2071 S: /u/cvsroot/supermunger/mungeall.c
2072 S: /mungeall.c/1.2///
2073 S: ok
2074 @end example
2075
2076 @node Requirements
2077 @section Required versus optional parts of the protocol
2078
2079 The following are part of every known implementation of the CVS protocol
2080 (except obsolete, pre-1.5, versions of CVS) and it is considered
2081 reasonable behavior to completely fail to work if you are connected with
2082 an implementation which attempts to not support them.  Requests:
2083 @code{Root}, @code{Valid-responses}, @code{valid-requests},
2084 @code{Directory}, @code{Entry}, @code{Modified}, @code{Unchanged},
2085 @code{Argument}, @code{Argumentx}, @code{ci}, @code{co}, @code{update}.
2086 Responses: @code{ok}, @code{error}, @code{Valid-requests},
2087 @code{Checked-in}, @code{Updated}, @code{Merged}, @code{Removed},
2088 @code{M}, @code{E}.
2089
2090 A server need not implement @code{Repository}, but in order to interoperate
2091 with CVS 1.5 through 1.9 it must claim to implement it (in
2092 @code{Valid-requests}).  The client will not actually send the request.
2093
2094 @node Obsolete
2095 @section Obsolete protocol elements
2096
2097 This section briefly describes protocol elements which are obsolete.
2098 There is no attempt to document them in full detail.
2099
2100 There was a @code{Repository} request which was like @code{Directory}
2101 except it only provided @var{repository}, and the local directory was
2102 assumed to be similarly named.
2103
2104 If the @code{UseUnchanged} request was not sent, there was a @code{Lost}
2105 request which was sent to indicate that a file did not exist in the
2106 working directory, and the meaning of sending @code{Entries} without
2107 @code{Lost} or @code{Modified} was different.  All current clients (CVS
2108 1.5 and later) will send @code{UseUnchanged} if it is supported.
2109
2110 @node Protocol Notes
2111 @chapter Notes on the Protocol
2112
2113 A number of enhancements are possible.  Also see the file @sc{todo} in
2114 the @sc{cvs} source distribution, which has further ideas concerning
2115 various aspects of @sc{cvs}, some of which impact the protocol.
2116 Similarly, the @url{http://www.nongnu.org/cvs/} site, in particular the
2117 @cite{Development} pages.
2118
2119 @itemize @bullet
2120 @item
2121 The @code{Modified} request could be speeded up by sending diffs rather
2122 than entire files.  The client would need some way to keep the version
2123 of the file which was originally checked out; probably requiring the use
2124 of "cvs edit" in this case is the most sensible course (the "cvs edit"
2125 could be handled by a package like VC for emacs).  This would also allow
2126 local operation of @code{cvs diff} without arguments.
2127
2128 @item
2129 The fact that @code{pserver} requires an extra network turnaround in
2130 order to perform authentication would be nice to avoid.  This relates to
2131 the issue of reporting errors; probably the clean solution is to defer
2132 the error until the client has issued a request which expects a
2133 response.  To some extent this might relate to the next item (in terms
2134 of how easy it is to skip a whole bunch of requests until we get to one
2135 that expects a response).  I know that the kerberos code doesn't wait in
2136 this fashion, but that probably can cause network deadlocks and perhaps
2137 future problems running over a transport which is more transaction
2138 oriented than TCP.  On the other hand I'm not sure it is wise to make
2139 the client conduct a lengthy upload only to find there is an
2140 authentication failure.
2141
2142 @item
2143 The protocol uses an extra network turnaround for protocol negotiation
2144 (@code{valid-requests}).  It might be nice to avoid this by having the
2145 client be able to send requests and tell the server to ignore them if
2146 they are unrecognized (different requests could produce a fatal error if
2147 unrecognized).  To do this there should be a standard syntax for
2148 requests.  For example, perhaps all future requests should be a single
2149 line, with mechanisms analogous to @code{Argumentx}, or several requests
2150 working together, to provide greater amounts of information.  Or there
2151 might be a standard mechanism for counted data (analogous to that used
2152 by @code{Modified}) or continuation lines (like a generalized
2153 @code{Argumentx}).  It would be useful to compare what HTTP is planning
2154 in this area; last I looked they were contemplating something called
2155 Protocol Extension Protocol but I haven't looked at the relevant IETF
2156 documents in any detail.  Obviously, we want something as simple as
2157 possible (but no simpler).
2158
2159 @item
2160 The scrambling algorithm in the CVS client and server actually support
2161 more characters than those documented in @ref{Password scrambling}.
2162 Someday we are going to either have to document them all (but this is
2163 not as easy as it may look, see below), or (gradually and with adequate
2164 process) phase out the support for other characters in the CVS
2165 implementation.  This business of having the feature partly undocumented
2166 isn't a desirable state long-term.
2167
2168 The problem with documenting other characters is that unless we know
2169 what character set is in use, there is no way to make a password
2170 portable from one system to another.  For example, a with a circle on
2171 top might have different encodings in different character sets.
2172
2173 It @emph{almost} works to say that the client picks an arbitrary,
2174 unknown character set (indeed, having the CVS client know what character
2175 set the user has in mind is a hard problem otherwise), and scrambles
2176 according to a certain octet<->octet mapping.  There are two problems
2177 with this.  One is that the protocol has no way to transmit character 10
2178 decimal (linefeed), and the current server and clients have no way to
2179 handle 0 decimal (NUL).  This may cause problems with certain multibyte
2180 character sets, in which octets 10 and 0 will appear in the middle of
2181 other characters.  The other problem, which is more minor and possibly
2182 not worth worrying about, is that someone can type a password on one
2183 system and then go to another system which uses a different encoding for
2184 the same characters, and have their password not work.
2185
2186 The restriction to the ISO646 invariant subset is the best approach for
2187 strings which are not particularly significant to users.  Passwords are
2188 visible enough that this is somewhat doubtful as applied here.  ISO646
2189 does, however, have the virtue (!?) of offending everyone.  It is easy
2190 to say "But the $ is right on people's keyboards!  Surely we can't
2191 forbid that".  From a human factors point of view, that makes quite a
2192 bit of sense.  The contrary argument, of course, is that a with a circle
2193 on top, or some of the characters poorly handled by Unicode, are on
2194 @emph{someone}'s keyboard.
2195
2196 @end itemize
2197
2198 @bye