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