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