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