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