1 .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
9 .de Vb \" Begin verbatim text
14 .de Ve \" End verbatim text
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
49 .\" If the F register is turned on, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
54 .\" Avoid warning from groff about undefined register 'F'.
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{
62 . tm Index:\\$1\t\\n%\t"\\$2"
72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
73 .\" Fear. Run. Save yourself. No user-serviceable parts.
74 . \" fudge factors for nroff and troff
83 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
89 . \" simple accents for nroff and troff
99 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
100 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
101 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
102 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
103 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
104 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
106 . \" troff and (daisy-wheel) nroff accents
107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
114 .ds ae a\h'-(\w'a'u*4/10)'e
115 .ds Ae A\h'-(\w'A'u*4/10)'E
116 . \" corrections for vroff
117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
119 . \" for low resolution devices (crt and lpr)
120 .if \n(.H>23 .if \n(.V>19 \
133 .\" ========================================================================
135 .IX Title "CVSCLIENT 7"
136 .TH CVSCLIENT 7 "2015-04-03" "perl v5.18.4" "DragonFly Miscellaneous Information Manual"
137 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
138 .\" way too many mistakes in technical documents.
142 CVS Client/Server Reference Manual \- Conversion of cvsclient.info
143 .SH "CVS Client/Server"
144 .IX Header "CVS Client/Server"
145 This document describes the client/server protocol used by \s-1CVS. \s0 It does
146 not describe how to use or administer client/server \s-1CVS\s0; see the regular
147 \&\s-1CVS\s0 manual for that. This is version 1.12.13 of the protocol
148 specification\*(--see \*(L"Introduction\*(R", for more on what this version
153 What is \s-1CVS\s0 and what is the client/server protocol for?: see \*(L"Introduction\*(R"
155 Basic design decisions, requirements, scope, etc.: see \*(L"Goals\*(R"
157 Various ways to connect to the server: see \*(L"Connection and Authentication\*(R"
159 Scrambling used by pserver: see \*(L"Password scrambling\*(R"
161 Complete description of the protocol: see \*(L"Protocol\*(R"
163 Possible enhancements, limitations, etc. of the protocol: see \*(L"Protocol Notes\*(R"
165 .IX Subsection "1 Introduction"
166 \&\s-1CVS\s0 is a version control system (with some additional configuration
167 management functionality). It maintains a central \*(L"repository\*(R" which
168 stores files (often source code), including past versions, information
169 about who modified them and when, and so on. People who wish to look
170 at or modify those files, known as \*(L"developers\*(R", use \s-1CVS\s0 to \*(L"check out\*(R"
171 a \*(L"working directory\*(R" from the repository, to \*(L"check in\*(R" new versions
172 of files to the repository, and other operations such as viewing the
173 modification history of a file. If developers are connected to the
174 repository by a network, particularly a slow or flaky one, the most
175 efficient way to use the network is with the CVS-specific protocol
176 described in this document.
178 Developers, using the machine on which they store their working
179 directory, run the \s-1CVS \s0\*(L"client\*(R" program. To perform operations which
180 cannot be done locally, it connects to the \s-1CVS \s0\*(L"server\*(R" program, which
181 maintains the repository. For more information on how to connect see
182 see \*(L"Connection and Authentication\*(R".
184 This document describes the \s-1CVS\s0 protocol. Unfortunately, it does not
185 yet completely document one aspect of the protocol\*(--the detailed
186 operation of each \s-1CVS\s0 command and option\*(--and one must look at the \s-1CVS\s0
187 user documentation, `\fBcvs.texinfo\fR', for that information. The protocol
188 is non-proprietary (anyone who wants to is encouraged to implement it)
189 and an implementation, known as \s-1CVS,\s0 is available under the \s-1GNU\s0 Public
190 License. The \s-1CVS\s0 distribution, containing this implementation,
191 `\fBcvs.texinfo\fR', and a copy (possibly more or less up to date than what
192 you are reading now) of this document, `\fBcvsclient.texi\fR', can be found
193 at the usual \s-1GNU FTP\s0 sites, with a filename such as
194 `\fBcvs\-VERSION.tar.gz\fR'.
196 This is version 1.12.13 of the protocol specification. This version
197 number is intended only to aid in distinguishing different versions of
198 this specification. Although the specification is currently maintained
199 in conjunction with the \s-1CVS\s0 implementation, and carries the same
200 version number, it also intends to document what is involved with
201 interoperating with other implementations (such as other versions of
202 \&\s-1CVS\s0); see see \*(L"Requirements\*(R". This version number should not be used
203 by clients or servers to determine what variant of the protocol to
204 speak; they should instead use the `\fBvalid-requests\fR' and
205 `\fBValid-responses\fR' mechanism (see \*(L"Protocol\*(R"), which is more flexible.
207 .IX Subsection "2 Goals"
208 * Do not assume any access to the repository other than via this
209 protocol. It does not depend on \s-1NFS,\s0 rdist, etc.
211 * Providing a reliable transport is outside this protocol. The
212 protocol expects a reliable transport that is transparent (that
213 is, there is no translation of characters, including characters
214 such as linefeeds or carriage returns), and can transmit all 256
215 octets (for example for proper handling of binary files,
216 compression, and encryption). The encoding of characters
217 specified by the protocol (the names of requests and so on) is the
218 invariant \s-1ISO 646\s0 character set (a subset of most popular
219 character sets including \s-1ASCII\s0 and others). For more details on
220 running the protocol over the \s-1TCP\s0 reliable transport, see *note
221 Connection and Authentication::.
223 * Security and authentication are handled outside this protocol (but
224 see below about `\fBcvs kserver\fR' and `\fBcvs pserver\fR').
226 * The protocol makes it possible for updates to be atomic with
227 respect to checkins; that is if someone commits changes to several
228 files in one cvs command, then an update by someone else would
229 either get all the changes, or none of them. The current \s-1CVS\s0
230 server can't do this, but that isn't the protocol's fault.
232 * The protocol is, with a few exceptions, transaction-based. That
233 is, the client sends all its requests (without waiting for server
234 responses), and then waits for the server to send back all
235 responses (without waiting for further client requests). This has
236 the advantage of minimizing network turnarounds and the
237 disadvantage of sometimes transferring more data than would be
238 necessary if there were a richer interaction. Another, more
239 subtle, advantage is that there is no need for the protocol to
240 provide locking for features such as making checkins atomic with
241 respect to updates. Any such locking can be handled entirely by
242 the server. A good server implementation (such as the current \s-1CVS\s0
243 server) will make sure that it does not have any such locks in
244 place whenever it is waiting for communication with the client;
245 this prevents one client on a slow or flaky network from
246 interfering with the work of others.
248 * It is a general design goal to provide only one way to do a given
249 operation (where possible). For example, implementations have no
250 choice about whether to terminate lines with linefeeds or some
251 other character(s), and request and response names are
252 case-sensitive. This is to enhance interoperability. If a
253 protocol allows more than one way to do something, it is all too
254 easy for some implementations to support only some of them
255 (perhaps accidentally).
256 .SS "3 How to Connect to and Authenticate Oneself to the \s-1CVS\s0 server"
257 .IX Subsection "3 How to Connect to and Authenticate Oneself to the CVS server"
258 Connection and authentication occurs before the \s-1CVS\s0 protocol itself is
259 started. There are several ways to connect.
262 If the client has a way to execute commands on the server, and
263 provide input to the commands and output from them, then it can
264 connect that way. This could be the usual rsh (port 514)
265 protocol, Kerberos rsh, \s-1SSH,\s0 or any similar mechanism. The client
266 may allow the user to specify the name of the server program; the
267 default is `\fBcvs\fR'. It is invoked with one argument, `\fBserver\fR'.
268 Once it invokes the server, the client proceeds to start the cvs
272 The kerberized server listens on a port (in the current
273 implementation, by having inetd call \*(L"cvs kserver\*(R") which defaults
274 to 1999. The client connects, sends the usual kerberos
275 authentication information, and then starts the cvs protocol.
276 Note: port 1999 is officially registered for another use, and in
277 any event one cannot register more than one port for \s-1CVS,\s0 so
278 GSS-API (see below) is recommended instead of kserver as a way to
282 The name \*(L"pserver\*(R" is somewhat confusing. It refers to both a
283 generic framework which allows the \s-1CVS\s0 protocol to support several
284 authentication mechanisms, and a name for a specific mechanism
285 which transfers a username and a cleartext password. Servers need
286 not support all mechanisms, and in fact servers will typically
287 want to support only those mechanisms which meet the relevant
290 The pserver server listens on a port (in the current
291 implementation, by having inetd call \*(L"cvs pserver\*(R") which defaults
292 to 2401 (this port is officially registered). The client
293 connects, and sends the following:
295 * the string `\fB\s-1BEGIN AUTH REQUEST\s0\fR', a linefeed,
297 * the cvs root, a linefeed,
299 * the username, a linefeed,
301 * the password trivially encoded (see *note Password
302 scrambling::), a linefeed,
304 * the string `\fB\s-1END AUTH REQUEST\s0\fR', and a linefeed.
306 The client must send the identical string for cvs root both here
307 and later in the `\fBRoot\fR' request of the cvs protocol itself.
308 Servers are encouraged to enforce this restriction. The possible
309 server responses (each of which is followed by a linefeed) are the
310 following. Note that although there is a small similarity between
311 this authentication protocol and the cvs protocol, they are
314 `\fBI \s-1LOVE YOU\s0\fR'
315 The authentication is successful. The client proceeds with
316 the cvs protocol itself.
318 `\fBI \s-1HATE YOU\s0\fR'
319 The authentication fails. After sending this response, the
320 server may close the connection. It is up to the server to
321 decide whether to give this response, which is generic, or a
322 more specific response using `\fBE\fR' and/or `\fBerror\fR'.
324 `\fBE \s-1TEXT\s0\fR'
325 Provide a message for the user. After this reponse, the
326 authentication protocol continues with another response.
327 Typically the server will provide a series of `\fBE\fR' responses
328 followed by `\fBerror\fR'. Compatibility note: \s-1CVS 1.9.10\s0 and
329 older clients will print `\fBunrecognized auth response\fR' and
330 \&\s-1TEXT,\s0 and then exit, upon receiving this response.
332 `\fBerror \s-1CODE TEXT\s0\fR'
333 The authentication fails. After sending this response, the
334 server may close the connection. The \s-1CODE\s0 is a code
335 describing why it failed, intended for computer consumption.
336 The only code currently defined is `\fB0\fR' which is nonspecific,
337 but clients must silently treat any unrecognized codes as
338 nonspecific. The \s-1TEXT\s0 should be supplied to the user.
339 Compatibility note: \s-1CVS 1.9.10\s0 and older clients will print
340 `\fBunrecognized auth response\fR' and \s-1TEXT,\s0 and then exit, upon
341 receiving this response. Note that \s-1TEXT\s0 for this response,
342 or the \s-1TEXT\s0 in an `\fBE\fR' response, is not designed for machine
343 parsing. More vigorous use of \s-1CODE,\s0 or future extensions,
344 will be needed to prove a cleaner machine-parseable
345 indication of what the error was.
347 If the client wishes to merely authenticate without starting the
348 cvs protocol, the procedure is the same, except \s-1BEGIN AUTH REQUEST\s0
349 is replaced with \s-1BEGIN VERIFICATION REQUEST, END AUTH REQUEST\s0 is
350 replaced with \s-1END VERIFICATION REQUEST,\s0 and upon receipt of I \s-1LOVE
351 YOU\s0 the connection is closed rather than continuing.
353 Another mechanism is \s-1GSSAPI\s0 authentication. \s-1GSSAPI\s0 is a generic
354 interface to security services such as kerberos. \s-1GSSAPI\s0 is
355 specified in \s-1RFC2078 \s0(\s-1GSSAPI\s0 version 2) and \s-1RFC1508 \s0(\s-1GSSAPI\s0
356 version 1); we are not aware of differences between the two which
357 affect the protocol in incompatible ways, so we make no attempt to
358 specify one version or the other. The procedure here is to start
359 with `\fB\s-1BEGIN GSSAPI REQUEST\s0\fR'. \s-1GSSAPI\s0 authentication information is
360 then exchanged between the client and the server. Each packet of
361 information consists of a two byte big endian length, followed by
362 that many bytes of data. After the \s-1GSSAPI\s0 authentication is
363 complete, the server continues with the responses described above
364 (`\fBI \s-1LOVE YOU\s0\fR', etc.).
367 There are a nearly unlimited number of ways to connect and
368 authenticate. One might want to allow access based on \s-1IP\s0 address
369 (similar to the usual rsh protocol but with different/no
370 restrictions on ports < 1024), to adopt mechanisms such as
371 Pluggable Authentication Modules (\s-1PAM\s0), to allow users to run
372 their own servers under their own usernames without root access,
373 or any number of other possibilities. The way to add future
374 mechanisms, for the most part, should be to continue to use port
375 2401, but to use different strings in place of `\s-1BEGIN AUTH
377 .SS "4 Password scrambling algorithm"
378 .IX Subsection "4 Password scrambling algorithm"
379 The pserver authentication protocol, as described in *note Connection
380 and Authentication::, trivially encodes the passwords. This is only to
381 prevent inadvertent compromise; it provides no protection against even a
382 relatively unsophisticated attacker. For comparison, \s-1HTTP\s0 Basic
383 Authentication (as described in \s-1RFC2068\s0) uses \s-1BASE64\s0 for a similar
384 purpose. \s-1CVS\s0 uses its own algorithm, described here.
386 The scrambled password starts with `\fBA\fR', which serves to identify the
387 scrambling algorithm in use. After that follows a single octet for
388 each character in the password, according to a fixed encoding. The
389 values are shown here, with the encoded values in decimal. Control
390 characters, space, and characters outside the invariant \s-1ISO 646\s0
391 character set are not shown; such characters are not recommended for use
392 in passwords. There is a long discussion of character set issues in
393 see \*(L"Protocol Notes\*(R".
396 ! 120 1 52 A 57 Q 55 a 121 q 113
397 " 53 2 75 B 83 R 54 b 117 r 32
398 3 119 C 43 S 66 c 104 s 90
399 4 49 D 46 T 124 d 101 t 44
400 % 109 5 34 E 102 U 126 e 100 u 98
401 & 72 6 82 F 40 V 59 f 69 v 60
402 \&' 108 7 81 G 89 W 47 g 73 w 51
403 ( 70 8 95 H 38 X 92 h 99 x 33
404 ) 64 9 65 I 103 Y 71 i 63 y 97
405 76 : see \*(L"112 J 45 Z 115 j 94 z 62\*(R"
408 , 116 < 118 L 42 l 39
409 \&\- 74 = 110 M 123 m 37
410 \&. 68 > 122 N 91 n 61
411 / 87 ? 105 O 35 _ 56 o 48
412 .SS "5 The \s-1CVS\s0 client/server protocol"
413 .IX Subsection "5 The CVS client/server protocol"
414 In the following, `\fB\en\fR' refers to a linefeed and `\fB\et\fR' refers to a
415 horizontal tab; \*(L"requests\*(R" are what the client sends and \*(L"responses\*(R"
416 are what the server sends. In general, the connection is governed by
417 the client\*(--the server does not send responses without first receiving
418 requests to do so; see see \*(L"Response intro\*(R" for more details of this
421 It is typical, early in the connection, for the client to transmit a
422 `\fBValid-responses\fR' request, containing all the responses it supports,
423 followed by a `\fBvalid-requests\fR' request, which elicits from the server a
424 `\fBValid-requests\fR' response containing all the requests it understands.
425 In this way, the client and server each find out what the other
426 supports before exchanging large amounts of data (such as file
431 General protocol conventions:
433 Transmitting \s-1RCS\s0 data: see \*(L"Entries Lines\*(R"
435 Read, write, execute, and possibly more...: see \*(L"File Modes\*(R"
437 Conventions regarding filenames: see \*(L"Filenames\*(R"
439 How file contents are transmitted: see \*(L"File transmissions\*(R"
441 Strings in various requests and responses: see \*(L"Strings\*(R"
443 Times and dates: see \*(L"Dates\*(R"
447 General conventions relating to requests: see \*(L"Request intro\*(R"
449 List of requests: see \*(L"Requests\*(R"
451 General conventions relating to responses: see \*(L"Response intro\*(R"
453 The \*(L"pathname\*(R" in responses: see \*(L"Response pathnames\*(R"
455 List of responses: see \*(L"Responses\*(R"
457 More details about the \s-1MT\s0 response: see \*(L"Text tags\*(R"
459 An example session, and some further observations:
461 A conversation between client and server: see \*(L"Example\*(R"
463 Things not to omit from an implementation: see \*(L"Requirements\*(R"
465 Former protocol features: see \*(L"Obsolete\*(R"
467 \&\fB5.1 Entries Lines\fR
469 Entries lines are transmitted as:
471 / \s-1NAME / VERSION / CONFLICT / OPTIONS / TAG_OR_DATE\s0
473 \&\s-1TAG_OR_DATE\s0 is either `\fBT\fR' \s-1TAG\s0 or `\fBD\fR' \s-1DATE\s0 or empty. If it is
474 followed by a slash, anything after the slash shall be silently ignored.
476 \&\s-1VERSION\s0 can be empty, or start with `\fB0\fR' or `\fB\-\fR', for no user file,
477 new user file, or user file to be removed, respectively.
479 \&\s-1CONFLICT,\s0 if it starts with `\fB+\fR', indicates that the file had
480 conflicts in it. The rest of \s-1CONFLICT\s0 is `\fB=\fR' if the timestamp matches
481 the file, or anything else if it doesn't. If \s-1CONFLICT\s0 does not start
482 with a `\fB+\fR', it is silently ignored.
484 \&\s-1OPTIONS\s0 signifies the keyword expansion options (for example `\fB\-ko\fR').
485 In an `\fBEntry\fR' request, this indicates the options that were specified
486 with the file from the previous file updating response (*note Response
487 intro::, for a list of file updating responses); if the client is
488 specifying the `\fB\-k\fR' or `\fB\-A\fR' option to `\fBupdate\fR', then it is the server
489 which figures out what overrides what.
491 \&\fB5.2 File Modes\fR
493 A mode is any number of repetitions of
495 MODE-TYPE = \s-1DATA\s0
497 separated by `\fB,\fR'.
499 MODE-TYPE is an identifier composed of alphanumeric characters.
500 Currently specified: `\fBu\fR' for user, `\fBg\fR' for group, `\fBo\fR' for other (see
501 below for discussion of whether these have their \s-1POSIX\s0 meaning or are
502 more loose). Unrecognized values of MODE-TYPE are silently ignored.
504 \&\s-1DATA\s0 consists of any data not containing `\fB,\fR', `\fB\e0\fR' or `\fB\en\fR'. For
505 `\fBu\fR', `\fBg\fR', and `\fBo\fR' mode types, data consists of alphanumeric characters,
506 where `\fBr\fR' means read, `\fBw\fR' means write, `\fBx\fR' means execute, and
507 unrecognized letters are silently ignored.
509 The two most obvious ways in which the mode matters are: (1) is it
510 writeable? This is used by the developer communication features, and
511 is implemented even on \s-1OS/2 \s0(and could be implemented on \s-1DOS\s0), whose
512 notion of mode is limited to a readonly bit. (2) is it executable?
513 Unix \s-1CVS\s0 users need \s-1CVS\s0 to store this setting (for shell scripts and
514 the like). The current \s-1CVS\s0 implementation on unix does a little bit
515 more than just maintain these two settings, but it doesn't really have
516 a nice general facility to store or version control the mode, even on
517 unix, much less across operating systems with diverse protection
518 features. So all the ins and outs of what the mode means across
519 operating systems haven't really been worked out (e.g. should the \s-1VMS\s0
520 port use ACLs to get \s-1POSIX\s0 semantics for groups?).
522 \&\fB5.3 Conventions regarding transmission of file names\fR
524 In most contexts, `\fB/\fR' is used to separate directory and file names in
525 filenames, and any use of other conventions (for example, that the user
526 might type on the command line) is converted to that form. The only
527 exceptions might be a few cases in which the server provides a magic
528 cookie which the client then repeats verbatim, but as the server has
529 not yet been ported beyond unix, the two rules provide the same answer
530 (and what to do if future server ports are operating on a repository
531 like e:/foo or CVS_ROOT:[\s-1FOO.BAR\s0] has not been carefully thought out).
533 Characters outside the invariant \s-1ISO 646\s0 character set should be
534 avoided in filenames. This restriction may need to be relaxed to allow
535 for characters such as `\fB[\fR' and `\fB]\fR' (see above about non-unix servers);
536 this has not been carefully considered (and currently implementations
537 probably use whatever character sets that the operating systems they
538 are running on allow, and/or that users specify). Of course the most
539 portable practice is to restrict oneself further, to the \s-1POSIX\s0 portable
540 filename character set as specified in \s-1POSIX.1.\s0
542 \&\fB5.4 File transmissions\fR
544 File contents (noted below as \s-1FILE TRANSMISSION\s0) can be sent in one of
545 two forms. The simpler form is a number of bytes, followed by a
546 linefeed, followed by the specified number of bytes of file contents.
547 These are the entire contents of the specified file. Second, if both
548 client and server support `\fBgzip-file-contents\fR', a `\fBz\fR' may precede the
549 length, and the `\fBfile contents\fR' sent are actually compressed with
550 `\fBgzip\fR' (\s-1RFC1952/1951\s0) compression. The length specified is that of the
551 compressed version of the file.
553 In neither case are the file content followed by any additional data.
554 The transmission of a file will end with a linefeed iff that file (or
555 its compressed form) ends with a linefeed.
557 The encoding of file contents depends on the value for the `\fB\-k\fR'
558 option. If the file is binary (as specified by the `\fB\-kb\fR' option in the
559 appropriate place), then it is just a certain number of octets, and the
560 protocol contributes nothing towards determining the encoding (using
561 the file name is one widespread, if not universally popular, mechanism).
562 If the file is text (not binary), then the file is sent as a series of
563 lines, separated by linefeeds. If the keyword expansion is set to
564 something other than `\fB\-ko\fR', then it is expected that the file conform
565 to the \s-1RCS\s0 expectations regarding keyword expansion\*(--in particular,
566 that it is in a character set such as \s-1ASCII\s0 in which 0x24 is a dollar
571 In various contexts, for example the `\fBArgument\fR' request and the `\fBM\fR'
572 response, one transmits what is essentially an arbitrary string. Often
573 this will have been supplied by the user (for example, the `\fB\-m\fR' option
574 to the `\fBci\fR' request). The protocol has no mechanism to specify the
575 character set of such strings; it would be fairly safe to stick to the
576 invariant \s-1ISO 646\s0 character set but the existing practice is probably
577 to just transmit whatever the user specifies, and hope that everyone
578 involved agrees which character set is in use, or sticks to a common
583 The protocol contains times and dates in various places.
585 For the `\fB\-D\fR' option to the `\fBannotate\fR', `\fBco\fR', `\fBdiff\fR', `\fBexport\fR',
586 `\fBhistory\fR', `\fBrannotate\fR', `\fBrdiff\fR', `\fBrtag\fR', `\fBtag\fR', and `\fBupdate\fR' requests,
587 the server should support two formats:
589 26 May 1997 13:01:40 \-0000 ; \s-1RFC 822\s0 as modified by \s-1RFC 1123
590 5/26/1997 13:01:40 GMT \s0; traditional
592 The former format is preferred; the latter however is sent by the \s-1CVS\s0
593 command line client (versions 1.5 through at least 1.9).
595 For the `\fB\-d\fR' option to the `\fBlog\fR' and `\fBrlog\fR' requests, servers should
596 at least support \s-1RFC 822/1123\s0 format. Clients are encouraged to use
597 this format too (the command line \s-1CVS\s0 client, version 1.10 and older,
598 just passed along the date format specified by the user, however).
600 The `\fBMod-time\fR' response and `\fBCheckin-time\fR' request use \s-1RFC 822/1123\s0
601 format (see the descriptions of that response and request for details).
603 For `\fBNotify\fR', see the description of that request.
605 \&\fB5.7 Request intro\fR
607 By convention, requests which begin with a capital letter do not elicit
608 a response from the server, while all others do \- save one. The
609 exception is `\fBgzip-file-contents\fR'. Unrecognized requests will always
610 elicit a response from the server, even if that request begins with a
613 The term \*(L"command\*(R" means a request which expects a response (except
614 `\fBvalid-requests\fR'). The general model is that the client transmits a
615 great number of requests, but nothing happens until the very end when
616 the client transmits a command. Although the intention is that
617 transmitting several commands in one connection should be legal,
618 existing servers probably have some bugs with some combinations of more
619 than one command, and so clients may find it necessary to make several
620 connections in some cases. This should be thought of as a workaround
621 rather than a desired attribute of the protocol.
625 Here are the requests:
627 `\fBRoot \s-1PATHNAME\s0 \en\fR'
628 Response expected: no. Tell the server which `\fB\s-1CVSROOT\s0\fR' to use.
629 Note that \s-1PATHNAME\s0 is a local directory and _not_ a fully
630 qualified `\fB\s-1CVSROOT\s0\fR' variable. \s-1PATHNAME\s0 must already exist; if
631 creating a new root, use the `\fBinit\fR' request, not `\fBRoot\fR'. \s-1PATHNAME\s0
632 does not include the hostname of the server, how to access the
633 server, etc.; by the time the \s-1CVS\s0 protocol is in use, connection,
634 authentication, etc., are already taken care of.
636 The `\fBRoot\fR' request must be sent only once, and it must be sent
637 before any requests other than `\fBValid-responses\fR',
638 `\fBvalid-requests\fR', `\fBUseUnchanged\fR', `\fBSet\fR', `\fBGlobal_option\fR', `\fBinit\fR',
639 `\fBnoop\fR', or `\fBversion\fR'.
641 `\fBValid-responses REQUEST-LIST \en\fR'
642 Response expected: no. Tell the server what responses the client
643 will accept. request-list is a space separated list of tokens.
644 The `\fBRoot\fR' request need not have been previously sent.
646 `\fBvalid-requests \en\fR'
647 Response expected: yes. Ask the server to send back a
648 `\fBValid-requests\fR' response. The `\fBRoot\fR' request need not have been
651 `\fBCommand-prep \s-1COMMAND\s0 \en\fR'
652 Response expected: yes. Notify the server of the command that we
653 are leading up to. Intended to allow the server to send a
654 redirect for write operations. Requires either an `\fBok\fR' or
655 `\fBRedirect\fR' respnose.
657 `\fBReferrer \s-1CVSROOT\s0 \en\fR'
658 Response expected: no. Notify a primary server of a server which
659 referred us. Intended to allow a primary (write) server to update
660 the read-only mirror a client is using for reads to minimize races
661 on any subsequent updates from the client.
663 `\fBDirectory LOCAL-DIRECTORY \en\fR'
664 `\fBRelative-directory LOCAL-DIRECTORY \en\fR'
665 Additional data: \s-1REPOSITORY\s0 \en. Response expected: no. Tell the
666 server what directory to use.
668 The \s-1REPOSITORY\s0 should be a directory name from a previous server
669 response and may be specified either relative to the \s-1PATHNAME\s0
670 provided with the `\fBRoot\fR' request or absolute. Relative or
671 absolute, it must specify a path within \s-1PATHNAME.\s0
673 Prior to \s-1CVS\s0 version *FIXME \- release number 1.12.10?*, \s-1REPOSITORY\s0
674 had to be absolute and `\fBRelative-directory\fR' was not a valid
675 request. The `\fBRelative-directory\fR' request is synonymous with
676 `\fBDirectory\fR' and is provided to alert modern clients that a relative
677 \&\s-1REPOSITORY\s0 is acceptable.
679 Note that this both gives a default for `\fBEntry\fR' and `\fBModified\fR' and
680 also for `\fBci\fR' and the other commands; normal usage is to send
681 `\fBDirectory\fR' for each directory in which there will be an `\fBEntry\fR'
682 or `\fBModified\fR', and then a final `\fBDirectory\fR' for the original
683 directory, then the command. The LOCAL-DIRECTORY is relative to
684 the top level at which the command is occurring (i.e. the last
685 `\fBDirectory\fR' which is sent before the command); to indicate that
686 top level, `\fB.\fR' should be sent for LOCAL-DIRECTORY.
688 Here is an example of where a client gets \s-1REPOSITORY\s0 and
689 LOCAL-DIRECTORY. Suppose that there is a module defined by
693 That is, one can check out `\fBmoddir\fR' and it will take `\fB1dir\fR' in the
694 repository and check it out to `\fBmoddir\fR' in the working directory.
695 Then an initial check out could proceed like this:
697 C: Root /home/kingdon/zwork/cvsroot
703 S: Clear-sticky moddir/
708 In this example the response shown is `\fBClear-sticky\fR', but it could
709 be another response instead. Note that it returns two pathnames.
710 The first one, `\fBmoddir/\fR', indicates the working directory to check
711 out into. The second one, ending in `\fB1dir/\fR', indicates the
712 directory to pass back to the server in a subsequent `\fBDirectory\fR'
713 request. For example, a subsequent `\fBupdate\fR' request might look
721 For a given LOCAL-DIRECTORY, the repository will be the same for
722 each of the responses, so one can use the repository from whichever
723 response is most convenient. Typically a client will store the
724 repository along with the sources for each LOCAL-DIRECTORY, use
725 that same setting whenever operating on that LOCAL-DIRECTORY, and
726 not update the setting as long as the LOCAL-DIRECTORY exists.
728 A client is free to rename a LOCAL-DIRECTORY at any time (for
729 example, in response to an explicit user request). While it is
730 true that the server supplies a LOCAL-DIRECTORY to the client, as
731 noted above, this is only the default place to put the directory.
732 Of course, the various `\fBDirectory\fR' requests for a single command
733 (for example, `\fBupdate\fR' or `\fBci\fR' request) should name a particular
734 directory with the same LOCAL-DIRECTORY.
736 Each `\fBDirectory\fR' request specifies a brand-new LOCAL-DIRECTORY and
737 \&\s-1REPOSITORY\s0; that is, LOCAL-DIRECTORY and \s-1REPOSITORY\s0 are never
738 relative to paths specified in any previous `\fBDirectory\fR' request.
740 Here's a more complex example, in which we request an update of a
741 working directory which has been checked out from multiple places
753 C: Directory dir3/subdir3
758 While directories `\fBdir1\fR' and `\fBdir2\fR' will be handled in similar
759 fashion to the other examples given above, `\fBdir3\fR' is slightly
760 different from the server's standpoint. Notice that module `\fBmod3\fR'
761 is actually checked out into `\fBdir3/subdir3\fR', meaning that directory
762 `\fBdir3\fR' is either empty or does not contain data checked out from
765 The above example will work correctly in \s-1CVS 1.10.1\s0 and later. The
766 server will descend the tree starting from all directories
767 mentioned in `\fBArgument\fR' requests and update those directories
768 specifically mentioned in `\fBDirectory\fR' requests.
770 Previous versions of \s-1CVS \s0(1.10 and earlier) do not behave the same
771 way. While the descent of the tree begins at all directories
772 mentioned in `\fBArgument\fR' requests, descent into subdirectories only
773 occurs if a directory has been mentioned in a `\fBDirectory\fR' request.
774 Therefore, the above example would succeed in updating `\fBdir1\fR' and
775 `\fBdir2\fR', but would skip `\fBdir3\fR' because that directory was not
776 specifically mentioned in a `\fBDirectory\fR' request. A functional
777 version of the above that would run on a 1.10 or earlier server is
792 C: Directory dir3/subdir3
797 Note the extra `\fBDirectory dir3\fR' request. It might be better to use
798 `\fBEmptydir\fR' as the repository for the `\fBdir3\fR' directory, but the
799 above will certainly work.
801 One more peculiarity of the 1.10 and earlier protocol is the
802 ordering of `\fBDirectory\fR' arguments. In order for a subdirectory to
803 be registered correctly for descent by the recursion processor,
804 its parent must be sent first. For example, the following would
805 not work to update `\fBdir3/subdir3\fR':
809 C: Directory dir3/subdir3
817 The implementation of the server in 1.10 and earlier writes the
818 administration files for a given directory at the time of the
819 `\fBDirectory\fR' request. It also tries to register the directory with
820 its parent to mark it for recursion. In the above example, at the
821 time `\fBdir3/subdir3\fR' is created, the physical directory for `\fBdir3\fR'
822 will be created on disk, but the administration files will not
823 have been created. Therefore, when the server tries to register
824 `\fBdir3/subdir3\fR' for recursion, the operation will silently fail
825 because the administration files do not yet exist for `\fBdir3\fR'.
827 `\fBMax-dotdot \s-1LEVEL\s0 \en\fR'
828 Response expected: no. Tell the server that \s-1LEVEL\s0 levels of
829 directories above the directory which `\fBDirectory\fR' requests are
830 relative to will be needed. For example, if the client is
831 planning to use a `\fBDirectory\fR' request for `\fB../../foo\fR', it must
832 send a `\fBMax-dotdot\fR' request with a \s-1LEVEL\s0 of at least 2.
833 `\fBMax-dotdot\fR' must be sent before the first `\fBDirectory\fR' request.
835 `\fBStatic-directory \en\fR'
836 Response expected: no. Tell the server that the directory most
837 recently specified with `\fBDirectory\fR' should not have additional
838 files checked out unless explicitly requested. The client sends
839 this if the `\fBEntries.Static\fR' flag is set, which is controlled by
840 the `\fBSet-static-directory\fR' and `\fBClear-static-directory\fR' responses.
842 `\fBSticky \s-1TAGSPEC\s0 \en\fR'
843 Response expected: no. Tell the server that the directory most
844 recently specified with `\fBDirectory\fR' has a sticky tag or date
845 \&\s-1TAGSPEC. \s0 The first character of \s-1TAGSPEC\s0 is `\fBT\fR' for a tag, `\fBD\fR' for
846 a date, or some other character supplied by a Set-sticky response
847 from a previous request to the server. The remainder of \s-1TAGSPEC\s0
848 contains the actual tag or date, again as supplied by Set-sticky.
850 The server should remember `\fBStatic-directory\fR' and `\fBSticky\fR'
851 requests for a particular directory; the client need not resend
852 them each time it sends a `\fBDirectory\fR' request for a given
853 directory. However, the server is not obliged to remember them
854 beyond the context of a single command.
856 `\fBCheckin-prog \s-1PROGRAM\s0 \en\fR'
857 Response expected: no. Tell the server that the directory most
858 recently specified with `\fBDirectory\fR' has a checkin program \s-1PROGRAM.\s0
859 Such a program would have been previously set with the
860 `\fBSet-checkin-prog\fR' response.
862 `\fBUpdate-prog \s-1PROGRAM\s0 \en\fR'
863 Response expected: no. Tell the server that the directory most
864 recently specified with `\fBDirectory\fR' has an update program \s-1PROGRAM.\s0
865 Such a program would have been previously set with the
866 `\fBSet-update-prog\fR' response.
868 `\fBEntry ENTRY-LINE \en\fR'
869 Response expected: no. Tell the server what version of a file is
870 on the local machine. The name in ENTRY-LINE is a name relative
871 to the directory most recently specified with `\fBDirectory\fR'. If the
872 user is operating on only some files in a directory, `\fBEntry\fR'
873 requests for only those files need be included. If an `\fBEntry\fR'
874 request is sent without `\fBModified\fR', `\fBIs-modified\fR', or `\fBUnchanged\fR',
875 it means the file is lost (does not exist in the working
876 directory). If both `\fBEntry\fR' and one of `\fBModified\fR', `\fBIs-modified\fR',
877 or `\fBUnchanged\fR' are sent for the same file, `\fBEntry\fR' must be sent
878 first. For a given file, one can send `\fBModified\fR', `\fBIs-modified\fR',
879 or `\fBUnchanged\fR', but not more than one of these three.
881 `\fBKopt \s-1OPTION\s0 \en\fR'
882 This indicates to the server which keyword expansion options to
883 use for the file specified by the next `\fBModified\fR' or `\fBIs-modified\fR'
884 request (for example `\fB\-kb\fR' for a binary file). This is similar to
885 `\fBEntry\fR', but is used for a file for which there is no entries line.
886 Typically this will be a file being added via an `\fBadd\fR' or `\fBimport\fR'
887 request. The client may not send both `\fBKopt\fR' and `\fBEntry\fR' for the
890 `\fBCheckin-time \s-1TIME\s0 \en\fR'
891 For the file specified by the next `\fBModified\fR' request, use \s-1TIME\s0 as
892 the time of the checkin. The \s-1TIME\s0 is in the format specified by
893 \&\s-1RFC822\s0 as modified by \s-1RFC1123. \s0 The client may specify any
894 timezone it chooses; servers will want to convert that to their own
895 timezone as appropriate. An example of this format is:
897 26 May 1997 13:01:40 \-0400
899 There is no requirement that the client and server clocks be
900 synchronized. The client just sends its recommendation for a
901 timestamp (based on file timestamps or whatever), and the server
902 should just believe it (this means that the time might be in the
903 future, for example).
905 Note that this is not a general-purpose way to tell the server
906 about the timestamp of a file; that would be a separate request
907 (if there are servers which can maintain timestamp and time of
910 This request should affect the `\fBimport\fR' request, and may optionally
911 affect the `\fBci\fR' request or other relevant requests if any.
913 `\fBModified \s-1FILENAME\s0 \en\fR'
914 Response expected: no. Additional data: mode, \en, file
915 transmission. Send the server a copy of one locally modified
916 file. \s-1FILENAME\s0 is a file within the most recent directory sent
917 with `\fBDirectory\fR'; it must not contain `\fB/\fR'. If the user is
918 operating on only some files in a directory, only those files need
919 to be included. This can also be sent without `\fBEntry\fR', if there
920 is no entry for the file.
922 `\fBIs-modified \s-1FILENAME\s0 \en\fR'
923 Response expected: no. Additional data: none. Like `\fBModified\fR',
924 but used if the server only needs to know whether the file is
925 modified, not the contents.
927 The commands which can take `\fBIs-modified\fR' instead of `\fBModified\fR'
928 with no known change in behavior are: `\fBadmin\fR', `\fBdiff\fR' (if and only
929 if two `\fB\-r\fR' or `\fB\-D\fR' options are specified), `\fBwatch-on\fR',
930 `\fBwatch-off\fR', `\fBwatch-add\fR', `\fBwatch-remove\fR', `\fBwatchers\fR', `\fBeditors\fR',
931 `\fBlog\fR', and `\fBannotate\fR'.
933 For the `\fBstatus\fR' command, one can send `\fBIs-modified\fR' but if the
934 client is using imperfect mechanisms such as timestamps to
935 determine whether to consider a file modified, then the behavior
936 will be different. That is, if one sends `\fBModified\fR', then the
937 server will actually compare the contents of the file sent and the
938 one it derives from to determine whether the file is genuinely
939 modified. But if one sends `\fBIs-modified\fR', then the server takes
940 the client's word for it. A similar situation exists for `\fBtag\fR',
941 if the `\fB\-c\fR' option is specified.
943 Commands for which `\fBModified\fR' is necessary are `\fBco\fR', `\fBci\fR',
944 `\fBupdate\fR', and `\fBimport\fR'.
946 Commands which do not need to inform the server about a working
947 directory, and thus should not be sending either `\fBModified\fR' or
948 `\fBIs-modified\fR': `\fBrdiff\fR', `\fBrtag\fR', `\fBhistory\fR', `\fBinit\fR', and `\fBrelease\fR'.
950 Commands for which further investigation is warranted are:
951 `\fBremove\fR', `\fBadd\fR', and `\fBexport\fR'. Pending such investigation, the
952 more conservative course of action is to stick to `\fBModified\fR'.
954 `\fBUnchanged \s-1FILENAME\s0 \en\fR'
955 Response expected: no. Tell the server that \s-1FILENAME\s0 has not been
956 modified in the checked out directory. The \s-1FILENAME\s0 is a file
957 within the most recent directory sent with `\fBDirectory\fR'; it must
958 not contain `\fB/\fR'.
960 `\fBUseUnchanged \en\fR'
961 Response expected: no. To specify the version of the protocol
962 described in this document, servers must support this request
963 (although it need not do anything) and clients must issue it. The
964 `\fBRoot\fR' request need not have been previously sent.
966 `\fBNotify \s-1FILENAME\s0 \en\fR'
967 Response expected: no. Tell the server that an `\fBedit\fR' or `\fBunedit\fR'
968 command has taken place. The server needs to send a `\fBNotified\fR'
969 response, but such response is deferred until the next time that
970 the server is sending responses. The \s-1FILENAME\s0 is a file within
971 the most recent directory sent with `\fBDirectory\fR'; it must not
972 contain `\fB/\fR'. Additional data:
973 NOTIFICATION-TYPE \et \s-1TIME\s0 \et \s-1CLIENTHOST\s0 \et
974 WORKING-DIR \et \s-1WATCHES\s0 \en
975 where NOTIFICATION-TYPE is `\fBE\fR' for edit, `\fBU\fR' for unedit, undefined
976 behavior if `\fBC\fR', and all other letters should be silently ignored
977 for future expansion. \s-1TIME\s0 is the time at which the edit or
978 unedit took place, in a user-readable format of the client's
979 choice (the server should treat the time as an opaque string
980 rather than interpreting it). \s-1CLIENTHOST\s0 is the name of the host
981 on which the edit or unedit took place, and WORKING-DIR is the
982 pathname of the working directory where the edit or unedit took
983 place. \s-1WATCHES\s0 are the temporary watches, zero or more of the
984 following characters in the following order: `\fBE\fR' for edit, `\fBU\fR' for
985 unedit, `\fBC\fR' for commit, and all other letters should be silently
986 ignored for future expansion. If NOTIFICATION-TYPE is `\fBE\fR' the
987 temporary watches are set; if it is `\fBU\fR' they are cleared. If
988 \&\s-1WATCHES\s0 is followed by \et then the \et and the rest of the line
989 should be ignored, for future expansion.
991 The \s-1TIME, CLIENTHOST,\s0 and WORKING-DIR fields may not contain the
992 characters `\fB+\fR', `\fB,\fR', `\fB>\fR', `\fB;\fR', or `\fB=\fR'.
994 Note that a client may be capable of performing an `\fBedit\fR' or
995 `\fBunedit\fR' operation without connecting to the server at that time,
996 and instead connecting to the server when it is convenient (for
997 example, when a laptop is on the net again) to send the `\fBNotify\fR'
998 requests. Even if a client is capable of deferring notifications,
999 it should attempt to send them immediately (one can send `\fBNotify\fR'
1000 requests together with a `\fBnoop\fR' request, for example), unless
1001 perhaps if it can know that a connection would be impossible.
1003 `\fBQuestionable \s-1FILENAME\s0 \en\fR'
1004 Response expected: no. Additional data: no. Tell the server to
1005 check whether \s-1FILENAME\s0 should be ignored, and if not, next time the
1006 server sends responses, send (in a `\fBM\fR' response) `\fB?\fR' followed by
1007 the directory and filename. \s-1FILENAME\s0 must not contain `\fB/\fR'; it
1008 needs to be a file in the directory named by the most recent
1009 `\fBDirectory\fR' request.
1012 Response expected: no. Tell the server that filenames should be
1013 matched in a case-insensitive fashion. Note that this is not the
1014 primary mechanism for achieving case-insensitivity; for the most
1015 part the client keeps track of the case which the server wants to
1016 use and takes care to always use that case regardless of what the
1017 user specifies. For example the filenames given in `\fBEntry\fR' and
1018 `\fBModified\fR' requests for the same file must match in case
1019 regardless of whether the `\fBCase\fR' request is sent. The latter
1020 mechanism is more general (it could also be used for 8.3
1021 filenames, \s-1VMS\s0 filenames with more than one `\fB.\fR', and any other
1022 situation in which there is a predictable mapping between
1023 filenames in the working directory and filenames in the protocol),
1024 but there are some situations it cannot handle (ignore patterns, or
1025 situations where the user specifies a filename and the client does
1026 not know about that file).
1028 Though this request will be supported into the forseeable future,
1029 it has been the source of numerous bug reports in the past due to
1030 the complexity of testing this functionality via the test suite
1031 and client developers are encouraged not to use it. Instead,
1032 please consider munging conflicting names and maintaining a map
1033 for communicating with the server. For example, suppose the
1034 server sends files `\fBcase\fR', `\fB\s-1CASE\s0\fR', and `\fBCaSe\fR'. The client could
1035 write all three files to names such as, `\fBcase\fR',
1036 `\fBcase_prefix_case\fR', and `\fBcase_prefix_2_case\fR' and maintain a
1037 mapping between the file names in, for instance a new `\fBCVS/Map\fR'
1040 `\fBArgument \s-1TEXT\s0 \en\fR'
1041 Response expected: no. Save argument for use in a subsequent
1042 command. Arguments accumulate until an argument-using command is
1043 given, at which point they are forgotten.
1045 `\fBArgumentx \s-1TEXT\s0 \en\fR'
1046 Response expected: no. Append \en followed by text to the current
1047 argument being saved.
1049 `\fBGlobal_option \s-1OPTION\s0 \en\fR'
1050 Response expected: no. Transmit one of the global options `\fB\-q\fR',
1051 `\fB\-Q\fR', `\fB\-l\fR', `\fB\-t\fR', `\fB\-r\fR', or `\fB\-n\fR'. \s-1OPTION\s0 must be one of those
1052 strings, no variations (such as combining of options) are allowed.
1053 For graceful handling of `\fBvalid-requests\fR', it is probably better to
1054 make new global options separate requests, rather than trying to
1055 add them to this request. The `\fBRoot\fR' request need not have been
1058 `\fBGzip-stream \s-1LEVEL\s0 \en\fR'
1059 Response expected: no. Use zlib (\s-1RFC 1950/1951\s0) compression to
1060 compress all further communication between the client and the
1061 server. As of \s-1CVS 1.12.13,\s0 this request needs to be sent as the
1062 first non-rootless request if the server is configured with
1063 compression level restrictions and \s-1LEVEL\s0 is outside the restricted
1064 range. After this request is sent, all further communication must
1065 be compressed. All further data received from the server will
1066 also be compressed. The \s-1LEVEL\s0 argument suggests to the server the
1067 level of compression that it should apply; it should be an integer
1068 between 0 and 9, inclusive, where `\fB0\fR' means no compression and
1069 higher numbers indicate more compression.
1071 `\fBKerberos-encrypt \en\fR'
1072 Response expected: no. Use Kerberos encryption to encrypt all
1073 further communication between the client and the server. This
1074 will only work if the connection was made over Kerberos in the
1075 first place. If both the `\fBGzip-stream\fR' and the `\fBKerberos-encrypt\fR'
1076 requests are used, the `\fBKerberos-encrypt\fR' request should be used
1077 first. This will make the client and server encrypt the
1078 compressed data, as opposed to compressing the encrypted data.
1079 Encrypted data is generally incompressible.
1081 Note that this request does not fully prevent an attacker from
1082 hijacking the connection, in the sense that it does not prevent
1083 hijacking the connection between the initial authentication and the
1084 `\fBKerberos-encrypt\fR' request.
1086 `\fBGssapi-encrypt \en\fR'
1087 Response expected: no. Use \s-1GSSAPI\s0 encryption to encrypt all
1088 further communication between the client and the server. This
1089 will only work if the connection was made over \s-1GSSAPI\s0 in the first
1090 place. See `\fBKerberos-encrypt\fR', above, for the relation between
1091 `\fBGssapi-encrypt\fR' and `\fBGzip-stream\fR'.
1093 Note that this request does not fully prevent an attacker from
1094 hijacking the connection, in the sense that it does not prevent
1095 hijacking the connection between the initial authentication and the
1096 `\fBGssapi-encrypt\fR' request.
1098 `\fBGssapi-authenticate \en\fR'
1099 Response expected: no. Use \s-1GSSAPI\s0 authentication to authenticate
1100 all further communication between the client and the server. This
1101 will only work if the connection was made over \s-1GSSAPI\s0 in the first
1102 place. Encrypted data is automatically authenticated, so using
1103 both `\fBGssapi-authenticate\fR' and `\fBGssapi-encrypt\fR' has no effect
1104 beyond that of `\fBGssapi-encrypt\fR'. Unlike encrypted data, it is
1105 reasonable to compress authenticated data.
1107 Note that this request does not fully prevent an attacker from
1108 hijacking the connection, in the sense that it does not prevent
1109 hijacking the connection between the initial authentication and the
1110 `\fBGssapi-authenticate\fR' request.
1112 `\fBSet VARIABLE=VALUE \en\fR'
1113 Response expected: no. Set a user variable \s-1VARIABLE\s0 to \s-1VALUE.\s0
1114 The `\fBRoot\fR' request need not have been previously sent.
1116 `\fBHostname \s-1HOSTNAME\s0 \en\fR'
1117 Response expected: no. Set the client hostname for an upcoming
1118 `\fBedit\fR' request.
1120 `\fBLocalDir \s-1HOSTNAME\s0 \en\fR'
1121 Response expected: no. Set the local client directory name for an
1122 upcoming `\fBedit\fR' request.
1124 `\fBexpand-modules \en\fR'
1125 Response expected: yes. Expand the modules which are specified in
1126 the arguments. Returns the data in `\fBModule-expansion\fR' responses.
1127 Note that the server can assume that this is checkout or export,
1128 not rtag or rdiff; the latter do not access the working directory
1129 and thus have no need to expand modules on the client side.
1131 Expand may not be the best word for what this request does. It
1132 does not necessarily tell you all the files contained in a module,
1133 for example. Basically it is a way of telling you which working
1134 directories the server needs to know about in order to handle a
1135 checkout of the specified modules.
1137 For example, suppose that the server has a module defined by
1139 aliasmodule \-a 1dir
1141 That is, one can check out `\fBaliasmodule\fR' and it will take `\fB1dir\fR'
1142 in the repository and check it out to `\fB1dir\fR' in the working
1143 directory. Now suppose the client already has this module checked
1144 out and is planning on using the `\fBco\fR' request to update it.
1145 Without using `\fBexpand-modules\fR', the client would have two bad
1146 choices: it could either send information about _all_ working
1147 directories under the current directory, which could be
1148 unnecessarily slow, or it could be ignorant of the fact that
1149 `\fBaliasmodule\fR' stands for `\fB1dir\fR', and neglect to send information
1150 for `\fB1dir\fR', which would lead to incorrect operation.
1152 With `\fBexpand-modules\fR', the client would first ask for the module to
1155 C: Root /home/kingdon/zwork/cvsroot
1157 C: Argument aliasmodule
1161 S: Module-expansion 1dir
1164 and then it knows to check the `\fB1dir\fR' directory and send requests
1165 such as `\fBEntry\fR' and `\fBModified\fR' for the files in that directory.
1174 `\fBwatchers \en\fR'
1176 `\fBannotate \en\fR'
1177 Response expected: yes. Actually do a cvs command. This uses any
1178 previous `\fBArgument\fR', `\fBDirectory\fR', `\fBEntry\fR', or `\fBModified\fR' requests,
1179 if they have been sent. The last `\fBDirectory\fR' sent specifies the
1180 working directory at the time of the operation. No provision is
1181 made for any input from the user. This means that `\fBci\fR' must use a
1182 `\fB\-m\fR' argument if it wants to specify a log message.
1185 Response expected: yes. Show information for past revisions.
1186 This uses any previous `\fBDirectory\fR', `\fBEntry\fR', or `\fBModified\fR'
1187 requests, if they have been sent. The last `\fBDirectory\fR' sent
1188 specifies the working directory at the time of the operation.
1189 Also uses previous `\fBArgument\fR''s of which the canonical forms are
1190 the following (\s-1CVS 1.10\s0 and older clients sent what the user
1191 specified, but clients are encouraged to use the canonical forms
1192 and other forms are deprecated):
1194 `\fB\-b, \-h, \-l, \-N, \-R, \-t\fR'
1195 These options go by themselves, one option per `\fBArgument\fR'
1198 `\fB\-d DATE1<\s-1DATE2\s0\fR'
1199 Select revisions between \s-1DATE1\s0 and \s-1DATE2. \s0 Either date may be
1200 omitted in which case there is no date limit at that end of
1201 the range (clients may specify dates such as 1 Jan 1970 or 1
1202 Jan 2038 for similar purposes but this is problematic as it
1203 makes assumptions about what dates the server supports).
1204 Dates are in \s-1RFC822/1123\s0 format. The `\fB\-d\fR' is one `\fBArgument\fR'
1205 request and the date range is a second one.
1207 `\fB\-d DATE1<=DATE2\fR'
1208 Likewise but compare dates for equality.
1210 `\fB\-d \s-1SINGLEDATE\s0\fR'
1211 Select the single, latest revision dated \s-1SINGLEDATE\s0 or
1214 To include several date ranges and/or singledates, repeat the
1215 `\fB\-d\fR' option as many times as necessary.
1217 `\fB\-rREV1:REV2\fR'
1221 Specify revisions (note that \s-1REV1\s0 or \s-1REV2\s0 can be omitted, or
1222 can refer to branches). Send both the `\fB\-r\fR' and the revision
1223 information in a single `\fBArgument\fR' request. To include
1224 several revision selections, repeat the `\fB\-r\fR' option.
1226 `\fB\-s \s-1STATE\s0\fR'
1229 Select on states or users. To include more than one state or
1230 user, repeat the option. Send the `\fB\-s\fR' option as a separate
1231 argument from the state being selected. Send the `\fB\-w\fR' option
1232 as part of the same argument as the user being selected.
1235 Response expected: yes. Get files from the repository. This uses
1236 any previous `\fBArgument\fR', `\fBDirectory\fR', `\fBEntry\fR', or `\fBModified\fR'
1237 requests, if they have been sent. Arguments to this command are
1238 module names; the client cannot know what directories they
1239 correspond to except by (1) just sending the `\fBco\fR' request, and then
1240 seeing what directory names the server sends back in its
1241 responses, and (2) the `\fBexpand-modules\fR' request.
1244 Response expected: yes. Get files from the repository. This uses
1245 any previous `\fBArgument\fR', `\fBDirectory\fR', `\fBEntry\fR', or `\fBModified\fR'
1246 requests, if they have been sent. Arguments to this command are
1247 module names, as described for the `\fBco\fR' request. The intention
1248 behind this command is that a client can get sources from a server
1249 without storing \s-1CVS\s0 information about those sources. That is, a
1250 client probably should not count on being able to take the entries
1251 line returned in the `\fBCreated\fR' response from an `\fBexport\fR' request
1252 and send it in a future `\fBEntry\fR' request. Note that the entries
1253 line in the `\fBCreated\fR' response must indicate whether the file is
1254 binary or text, so the client can create it correctly.
1257 `\fBrannotate \en\fR'
1262 Response expected: yes. Actually do a cvs command. This uses any
1263 previous `\fBArgument\fR' requests, if they have been sent. The client
1264 should not send `\fBDirectory\fR', `\fBEntry\fR', or `\fBModified\fR' requests for
1265 these commands; they are not used. Arguments to these commands
1266 are module names, as described for `\fBco\fR'. `\fBls\fR' is a synonym for
1267 `\fBrlist\fR', for compatibility with \s-1CVSNT.\s0
1269 `\fBinit ROOT-NAME \en\fR'
1270 Response expected: yes. If it doesn't already exist, create a \s-1CVS\s0
1271 repository ROOT-NAME. Note that ROOT-NAME is a local directory
1272 and _not_ a fully qualified `\fB\s-1CVSROOT\s0\fR' variable. The `\fBRoot\fR'
1273 request need not have been previously sent.
1276 Response expected: yes. Actually do a `\fBcvs update\fR' command. This
1277 uses any previous `\fBArgument\fR', `\fBDirectory\fR', `\fBEntry\fR', or `\fBModified\fR'
1278 requests, if they have been sent. The last `\fBDirectory\fR' sent
1279 specifies the working directory at the time of the operation. The
1280 `\fB\-I\fR' option is not used-files which the client can decide whether
1281 to ignore are not mentioned and the client sends the
1282 `\fBQuestionable\fR' request for others.
1285 Response expected: yes. Actually do a `\fBcvs import\fR' command. This
1286 uses any previous `\fBArgument\fR', `\fBDirectory\fR', `\fBEntry\fR', or `\fBModified\fR'
1287 requests, if they have been sent. The last `\fBDirectory\fR' sent
1288 specifies the working directory at the time of the operation \-
1289 unlike most commands, the repository field of each `\fBDirectory\fR'
1290 request is ignored (it merely must point somewhere within the
1291 root). The files to be imported are sent in `\fBModified\fR' requests
1292 (files which the client knows should be ignored are not sent; the
1293 server must still process the CVSROOT/cvsignore file unless \-I ! is
1294 sent). A log message must have been specified with a `\fB\-m\fR'
1298 Response expected: yes. Add a file or directory. This uses any
1299 previous `\fBArgument\fR', `\fBDirectory\fR', `\fBEntry\fR', or `\fBModified\fR' requests,
1300 if they have been sent. The last `\fBDirectory\fR' sent specifies the
1301 working directory at the time of the operation.
1303 To add a directory, send the directory to be added using
1304 `\fBDirectory\fR' and `\fBArgument\fR' requests. For example:
1314 S: M Directory /u/cvsroot/1dir/nsdir added to the repository
1317 You will notice that the server does not signal to the client in
1318 any particular way that the directory has been successfully added.
1319 The client is supposed to just assume that the directory has been
1320 added and update its records accordingly. Note also that adding a
1321 directory is immediate; it does not wait until a `\fBci\fR' request as
1324 To add a file, send the file to be added using a `\fBModified\fR'
1325 request. For example:
1335 S: E cvs server: scheduling file `\fBnfile\fR' for addition
1336 S: Mode u=rw,g=r,o=r
1338 S: /u/cvsroot/1dir/nfile
1340 S: E cvs server: use 'cvs commit' to add this file permanently
1343 Note that the file has not been added to the repository; the only
1344 effect of a successful `\fBadd\fR' request, for a file, is to supply the
1345 client with a new entries line containing `\fB0\fR' to indicate an added
1346 file. In fact, the client probably could perform this operation
1347 without contacting the server, although using `\fBadd\fR' does cause the
1348 server to perform a few more checks.
1350 The client sends a subsequent `\fBci\fR' to actually add the file to the
1353 Another quirk of the `\fBadd\fR' request is that with \s-1CVS 1.9\s0 and older,
1354 a pathname specified in an `\fBArgument\fR' request cannot contain `\fB/\fR'.
1355 There is no good reason for this restriction, and in fact more
1356 recent \s-1CVS\s0 servers don't have it. But the way to interoperate
1357 with the older servers is to ensure that all `\fBDirectory\fR' requests
1358 for `\fBadd\fR' (except those used to add directories, as described
1359 above), use `\fB.\fR' for LOCAL-DIRECTORY. Specifying another string for
1360 LOCAL-DIRECTORY may not get an error, but it will get you strange
1361 `\fBChecked-in\fR' responses from the buggy servers.
1364 Response expected: yes. Remove a file. This uses any previous
1365 `\fBArgument\fR', `\fBDirectory\fR', `\fBEntry\fR', or `\fBModified\fR' requests, if they
1366 have been sent. The last `\fBDirectory\fR' sent specifies the working
1367 directory at the time of the operation.
1369 Note that this request does not actually do anything to the
1370 repository; the only effect of a successful `\fBremove\fR' request is to
1371 supply the client with a new entries line containing `\fB\-\fR' to
1372 indicate a removed file. In fact, the client probably could
1373 perform this operation without contacting the server, although
1374 using `\fBremove\fR' may cause the server to perform a few more checks.
1376 The client sends a subsequent `\fBci\fR' request to actually record the
1377 removal in the repository.
1380 Response expected: yes. Actually do the `\fBcvs edit\fR' command. This
1381 uses any previous `\fBArgument\fR', `\fBDirectory\fR', `\fBEntry\fR', `\fBLocalDir\fR', or
1382 `\fBHostname\fR' requests, if they have been sent. Unless the user has
1383 requested that edits not be granted unless no one else is editing
1384 a file, a local edit followed by an attempt to send `\fBNotify\fR'
1385 requests to the server is preferred.
1387 `\fBwatch-on \en\fR'
1388 `\fBwatch-off \en\fR'
1389 `\fBwatch-add \en\fR'
1390 `\fBwatch-remove \en\fR'
1391 Response expected: yes. Actually do the `\fBcvs watch on\fR', `cvs
1392 watch off', `\fBcvs watch add\fR', and `\fBcvs watch remove\fR' commands,
1393 respectively. This uses any previous `\fBArgument\fR', `\fBDirectory\fR',
1394 `\fBEntry\fR', or `\fBModified\fR' requests, if they have been sent. The last
1395 `\fBDirectory\fR' sent specifies the working directory at the time of
1399 Response expected: yes. Note that a `\fBcvs release\fR' command has
1400 taken place and update the history file accordingly.
1402 `\fBglobal-list-quiet \en\fR'
1403 Response expected: yes. This request is a synonym for noop, but
1404 its existance notifies the client that a `\fB\-q\fR' option to `\fBlist\fR' and
1405 `\fBrlist\fR' will be rejected. This, in a reverse-logic sort of way,
1406 is here so that when it _isn't_ received, as for instance from
1407 \&\s-1CVSNT,\s0 the client will know that the quiet option has to be sent
1408 as a command option rather than a global option.
1411 Response expected: yes. This request is a null command in the
1412 sense that it doesn't do anything, but merely (as with any other
1413 requests expecting a response) sends back any responses pertaining
1414 to pending errors, pending `\fBNotified\fR' responses, etc. The `\fBRoot\fR'
1415 request need not have been previously sent.
1417 `\fBupdate-patches \en\fR'
1418 Response expected: yes. This request does not actually do
1419 anything. It is used as a signal that the server is able to
1420 generate patches when given an `\fBupdate\fR' request. The client must
1421 issue the `\fB\-u\fR' argument to `\fBupdate\fR' in order to receive patches.
1423 `\fBgzip-file-contents \s-1LEVEL\s0 \en\fR'
1424 Response expected: no. Note that this request does not follow the
1425 response convention stated above. `\fBGzip-stream\fR' is suggested
1426 instead of `\fBgzip-file-contents\fR' as it gives better compression; the
1427 only reason to implement the latter is to provide compression with
1428 \&\s-1CVS 1.8\s0 and earlier. The `\fBgzip-file-contents\fR' request asks the
1429 server to compress files it sends to the client using `\fBgzip\fR'
1430 (\s-1RFC1952/1951\s0) compression, using the specified level of
1431 compression. If this request is not made, the server must not
1434 This is only a hint to the server. It may still decide (for
1435 example, in the case of very small files, or files that already
1436 appear to be compressed) not to do the compression. Compression
1437 is indicated by a `\fBz\fR' preceding the file length.
1439 Availability of this request in the server indicates to the client
1440 that it may compress files sent to the server, regardless of
1441 whether the client actually uses this request.
1443 `\fBwrapper-sendme-rcsOptions \en\fR'
1444 Response expected: yes. Request that the server transmit mappings
1445 from filenames to keyword expansion modes in `\fBWrapper-rcsOption\fR'
1449 Response expected: yes. Request that the server transmit its
1450 version message. The `\fBRoot\fR' request need not have been previously
1453 `\fBOTHER-REQUEST \s-1TEXT\s0 \en\fR'
1454 Response expected: yes. Any unrecognized request expects a
1455 response, and does not contain any additional data. The response
1456 will normally be something like `\fBerror unrecognized request\fR', but
1457 it could be a different error if a previous request which doesn't
1458 expect a response produced an error.
1460 When the client is done, it drops the connection.
1462 \&\fB5.9 Introduction to Responses\fR
1464 After a command which expects a response, the server sends however many
1465 of the following responses are appropriate. The server should not send
1466 data at other times (the current implementation may violate this
1467 principle in a few minor places, where the server is printing an error
1468 message and exiting\*(--this should be investigated further).
1470 Any set of responses always ends with `\fBerror\fR' or `\fBok\fR'. This
1471 indicates that the response is over.
1473 The responses `\fBChecked-in\fR', `\fBNew-entry\fR', `\fBUpdated\fR', `\fBCreated\fR',
1474 `\fBUpdate-existing\fR', `\fBMerged\fR', and `\fBPatched\fR' are refered to as \*(L"file
1475 updating\*(R" responses, because they change the status of a file in the
1476 working directory in some way. The responses `\fBMode\fR', `\fBMod-time\fR', and
1477 `\fBChecksum\fR' are referred to as \*(L"file update modifying\*(R" responses because
1478 they modify the next file updating response. In no case shall a file
1479 update modifying response apply to a file updating response other than
1480 the next one. Nor can the same file update modifying response occur
1481 twice for a given file updating response (if servers diagnose this
1482 problem, it may aid in detecting the case where clients send an update
1483 modifying response without following it by a file updating response).
1485 \&\fB5.10 The \*(L"pathname\*(R" in responses\fR
1487 Many of the responses contain something called \s-1PATHNAME. \s0 The name is
1488 somewhat misleading; it actually indicates a pair of pathnames. First,
1489 a local directory name relative to the directory in which the command
1490 was given (i.e. the last `\fBDirectory\fR' before the command). Then a
1491 linefeed and a repository name. Then a slash and the filename (without
1492 a `\fB,v\fR' ending).
1494 The repository name may be absolute or relative to the \s-1PATHNAME\s0 sent
1495 with the `\fBRoot\fR' request. If absolute, the repository name must begin
1496 with the \s-1PATHNAME\s0 sent with the `\fBRoot\fR' request. Relative or absolute,
1497 the repository name must specify a path underneath the `\fBRoot\fR' \s-1PATHNAME.\s0
1499 For example, for a file `\fBi386.mh\fR' which is in the local directory
1500 `\fBgas.clean/config\fR' and for which the repository name is
1501 `\fBdevo/gas/config\fR':
1504 devo/gas/config/i386.mh
1506 If the server wants to tell the client to create a directory, then it
1507 merely uses the directory in any response, as described above, and the
1508 client should create the directory if it does not exist. Note that this
1509 should only be done one directory at a time, in order to permit the
1510 client to correctly store the repository for each directory. Servers
1511 can use requests such as `\fBClear-sticky\fR', `\fBClear-static-directory\fR', or
1512 any other requests, to create directories.
1514 Some server implementations may poorly distinguish between a
1515 directory which should not exist and a directory which contains no
1516 files; in order to refrain from creating empty directories a client
1517 should both send the `\fB\-P\fR' option to `\fBupdate\fR' or `\fBco\fR', and should also
1518 detect the case in which the server asks to create a directory but not
1519 any files within it (in that case the client should remove the
1520 directory or refrain from creating it in the first place). Note that
1521 servers could clean this up greatly by only telling the client to
1522 create directories if the directory in question should exist, but until
1523 servers do this, clients will need to offer the `\fB\-P\fR' behavior described
1526 \&\fB5.11 Responses\fR
1528 Here are the responses:
1530 `\fBValid-requests REQUEST-LIST \en\fR'
1531 Indicate what requests the server will accept. REQUEST-LIST is a
1532 space separated list of tokens. If the server supports sending
1533 patches, it will include `\fBupdate-patches\fR' in this list. The
1534 `\fBupdate-patches\fR' request does not actually do anything.
1536 `\fBForce-gzip \en\fR'
1537 Response expected: no. Indicates that the server requires
1538 compression. The client must send a `\fBGzip-stream\fR' request, though
1539 the requested \s-1LEVEL\s0 may be `\fB0\fR'.
1541 `\fBReferrer \s-1CVSROOT\s0\fR'
1542 Request that the client store \s-1CVSROOT\s0 as the name of this server
1543 and that this name be passed via a `\fBReferrer\fR' _request_ to any
1544 subsequent servers contacted as a result of a `\fBRedirect\fR' response.
1545 This can be useful to allow the secondary administrator to
1546 configure the `\fB\s-1CVSROOT\s0\fR' the primary should use to update the
1547 secondary in case the client uses a non-standard name or even a
1548 name that is unique to the client for some reason.
1550 `\fBRedirect \s-1CVSROOT\s0\fR'
1551 Request that the client redirect its connection to \s-1CVSROOT\s0 and
1552 begin again. This response is only valid in response to a
1553 `\fBCommand-prep\fR' request. If a client receives this response, it is
1554 expected to notify the write server it subsequently contacts of
1555 the \s-1CVSROOT\s0 of the server which redirected it using the `\fBReferrer\fR'
1556 request. This information makes it possible for primary servers
1557 to update the client's mirror first, hopefully minimizing race
1558 conditions on subsequent updates from the same client.
1560 `\fBChecked-in \s-1PATHNAME\s0 \en\fR'
1561 Additional data: New Entries line, \en. This means a file \s-1PATHNAME\s0
1562 has been successfully operated on (checked in, added, etc.). name
1563 in the Entries line is the same as the last component of \s-1PATHNAME.\s0
1565 `\fBNew-entry \s-1PATHNAME\s0 \en\fR'
1566 Additional data: New Entries line, \en. Like `\fBChecked-in\fR', but the
1567 file is not up to date.
1569 `\fBUpdated \s-1PATHNAME\s0 \en\fR'
1570 Additional data: New Entries line, \en, mode, \en, file
1571 transmission. A new copy of the file is enclosed. This is used
1572 for a new revision of an existing file, or for a new file, or for
1573 any other case in which the local (client-side) copy of the file
1574 needs to be updated, and after being updated it will be up to
1575 date. If any directory in pathname does not exist, create it.
1576 This response is not used if `\fBCreated\fR' and `\fBUpdate-existing\fR' are
1579 `\fBCreated \s-1PATHNAME\s0 \en\fR'
1580 This is just like `\fBUpdated\fR' and takes the same additional data, but
1581 is used only if no `\fBEntry\fR', `\fBModified\fR', or `\fBUnchanged\fR' request has
1582 been sent for the file in question. The distinction between
1583 `\fBCreated\fR' and `\fBUpdate-existing\fR' is so that the client can give an
1584 error message in several cases: (1) there is a file in the working
1585 directory, but not one for which `\fBEntry\fR', `\fBModified\fR', or
1586 `\fBUnchanged\fR' was sent (for example, a file which was ignored, or a
1587 file for which `\fBQuestionable\fR' was sent), (2) there is a file in
1588 the working directory whose name differs from the one mentioned in
1589 `\fBCreated\fR' in ways that the client is unable to use to distinguish
1590 files. For example, the client is case-insensitive and the names
1591 differ only in case.
1593 `\fBUpdate-existing \s-1PATHNAME\s0 \en\fR'
1594 This is just like `\fBUpdated\fR' and takes the same additional data, but
1595 is used only if a `\fBEntry\fR', `\fBModified\fR', or `\fBUnchanged\fR' request has
1596 been sent for the file in question.
1598 This response, or `\fBMerged\fR', indicates that the server has
1599 determined that it is \s-1OK\s0 to overwrite the previous contents of the
1600 file specified by \s-1PATHNAME. \s0 Provided that the client has correctly
1601 sent `\fBModified\fR' or `\fBIs-modified\fR' requests for a modified file, and
1602 the file was not modified while \s-1CVS\s0 was running, the server can
1603 ensure that a user's modifications are not lost.
1605 `\fBMerged \s-1PATHNAME\s0 \en\fR'
1606 This is just like `\fBUpdated\fR' and takes the same additional data,
1607 with the one difference that after the new copy of the file is
1608 enclosed, it will still not be up to date. Used for the results
1609 of a merge, with or without conflicts.
1611 It is useful to preserve an copy of what the file looked like
1612 before the merge. This is basically handled by the server; before
1613 sending `\fBMerged\fR' it will send a `\fBCopy-file\fR' response. For
1614 example, if the file is `\fBaa\fR' and it derives from revision 1.3, the
1615 `\fBCopy-file\fR' response will tell the client to copy `\fBaa\fR' to
1616 `\fB.#aa.1.3\fR'. It is up to the client to decide how long to keep this
1617 file around; traditionally clients have left it around forever,
1618 thus letting the user clean it up as desired. But another answer,
1619 such as until the next commit, might be preferable.
1621 `\fBRcs-diff \s-1PATHNAME\s0 \en\fR'
1622 This is just like `\fBUpdated\fR' and takes the same additional data,
1623 with the one difference that instead of sending a new copy of the
1624 file, the server sends an \s-1RCS\s0 change text. This change text is
1625 produced by `\fBdiff \-n\fR' (the \s-1GNU\s0 diff `\fB\-a\fR' option may also be used).
1626 The client must apply this change text to the existing file. This
1627 will only be used when the client has an exact copy of an earlier
1628 revision of a file. This response is only used if the `\fBupdate\fR'
1629 command is given the `\fB\-u\fR' argument.
1631 `\fBPatched \s-1PATHNAME\s0 \en\fR'
1632 This is just like `\fBRcs-diff\fR' and takes the same additional data,
1633 except that it sends a standard patch rather than an \s-1RCS\s0 change
1634 text. The patch is produced by `\fBdiff \-c\fR' for \s-1CVS 1.6\s0 and later
1635 (see \s-1POSIX.2\s0 for a description of this format), or `\fBdiff \-u\fR' for
1636 previous versions of \s-1CVS\s0; clients are encouraged to accept either
1637 format. Like `\fBRcs-diff\fR', this response is only used if the
1638 `\fBupdate\fR' command is given the `\fB\-u\fR' argument.
1640 The `\fBPatched\fR' response is deprecated in favor of the `\fBRcs-diff\fR'
1641 response. However, older clients (\s-1CVS 1.9\s0 and earlier) only
1642 support `\fBPatched\fR'.
1644 `\fBEdit-file \s-1PATHNAME\s0 \en\fR'
1645 Do the client-side portion of editing a file.
1647 `\fBMode \s-1MODE\s0 \en\fR'
1648 This \s-1MODE\s0 applies to the next file mentioned in `\fBChecked-in\fR'.
1649 `\fBMode\fR' is a file update modifying response as described in *note
1652 `\fBMod-time \s-1TIME\s0 \en\fR'
1653 Set the modification time of the next file sent to \s-1TIME.\s0
1654 `\fBMod-time\fR' is a file update modifying response as described in
1655 see \*(L"Response intro\*(R". The \s-1TIME\s0 is in the format specified by
1656 \&\s-1RFC822\s0 as modified by \s-1RFC1123. \s0 The server may specify any
1657 timezone it chooses; clients will want to convert that to their
1658 own timezone as appropriate. An example of this format is:
1660 26 May 1997 13:01:40 \-0400
1662 There is no requirement that the client and server clocks be
1663 synchronized. The server just sends its recommendation for a
1664 timestamp (based on its own clock, presumably), and the client
1665 should just believe it (this means that the time might be in the
1666 future, for example).
1668 If the server does not send `\fBMod-time\fR' for a given file, the client
1669 should pick a modification time in the usual way (usually, just
1670 let the operating system set the modification time to the time
1671 that the \s-1CVS\s0 command is running).
1673 `\fBChecksum CHECKSUM\en\fR'
1674 The \s-1CHECKSUM\s0 applies to the next file sent (that is, `\fBChecksum\fR' is
1675 a file update modifying response as described in *note Response
1676 intro::). In the case of `\fBPatched\fR', the checksum applies to the
1677 file after being patched, not to the patch itself. The client
1678 should compute the checksum itself, after receiving the file or
1679 patch, and signal an error if the checksums do not match. The
1680 checksum is the 128 bit \s-1MD5\s0 checksum represented as 32 hex digits
1681 (\s-1MD5\s0 is described in \s-1RFC1321\s0). This response is optional, and is
1682 only used if the client supports it (as judged by the
1683 `\fBValid-responses\fR' request).
1685 `\fBCopy-file \s-1PATHNAME\s0 \en\fR'
1686 Additional data: \s-1NEWNAME\s0 \en. Copy file \s-1PATHNAME\s0 to \s-1NEWNAME\s0 in the
1687 same directory where it already is. This does not affect
1688 `\fBCVS/Entries\fR'.
1690 This can optionally be implemented as a rename instead of a copy.
1691 The only use for it which currently has been identified is prior
1692 to a `\fBMerged\fR' response as described under `\fBMerged\fR'. Clients can
1693 probably assume that is how it is being used, if they want to worry
1694 about things like how long to keep the \s-1NEWNAME\s0 file around.
1696 `\fBRemoved \s-1PATHNAME\s0 \en\fR'
1697 The file has been removed from the repository (this is the case
1698 where cvs prints `\fBfile foobar.c is no longer pertinent\fR').
1700 `\fBRemove-entry \s-1PATHNAME\s0 \en\fR'
1701 The file needs its entry removed from `\fBCVS/Entries\fR', but the file
1702 itself is already gone (this happens in response to a `\fBci\fR' request
1703 which involves committing the removal of a file).
1705 `\fBSet-static-directory \s-1PATHNAME\s0 \en\fR'
1706 This instructs the client to set the `\fBEntries.Static\fR' flag, which
1707 it should then send back to the server in a `\fBStatic-directory\fR'
1708 request whenever the directory is operated on. \s-1PATHNAME\s0 ends in a
1709 slash; its purpose is to specify a directory, not a file within a
1712 `\fBClear-static-directory \s-1PATHNAME\s0 \en\fR'
1713 Like `\fBSet-static-directory\fR', but clear, not set, the flag.
1715 `\fBSet-sticky \s-1PATHNAME\s0 \en\fR'
1716 Additional data: \s-1TAGSPEC\s0 \en. Tell the client to set a sticky tag
1717 or date, which should be supplied with the `\fBSticky\fR' request for
1718 future operations. \s-1PATHNAME\s0 ends in a slash; its purpose is to
1719 specify a directory, not a file within a directory. The client
1720 should store \s-1TAGSPEC\s0 and pass it back to the server as-is, to
1721 allow for future expansion. The first character of \s-1TAGSPEC\s0 is `\fBT\fR'
1722 for a tag, `\fBD\fR' for a date, or something else for future expansion.
1723 The remainder of \s-1TAGSPEC\s0 contains the actual tag or date.
1725 `\fBClear-sticky \s-1PATHNAME\s0 \en\fR'
1726 Clear any sticky tag or date set by `\fBSet-sticky\fR'.
1728 `\fBTemplate \s-1PATHNAME\s0 \en\fR'
1729 Additional data: file transmission (note: compressed file
1730 transmissions are not supported). \s-1PATHNAME\s0 ends in a slash; its
1731 purpose is to specify a directory, not a file within a directory.
1732 Tell the client to store the file transmission as the template log
1733 message, and then use that template in the future when prompting
1734 the user for a log message.
1736 `\fBSet-checkin-prog \s-1DIR\s0 \en\fR'
1737 Additional data: \s-1PROG\s0 \en. Tell the client to set a checkin
1738 program, which should be supplied with the `\fBCheckin-prog\fR' request
1739 for future operations.
1741 `\fBSet-update-prog \s-1DIR\s0 \en\fR'
1742 Additional data: \s-1PROG\s0 \en. Tell the client to set an update
1743 program, which should be supplied with the `\fBUpdate-prog\fR' request
1744 for future operations.
1746 `\fBNotified \s-1PATHNAME\s0 \en\fR'
1747 Indicate to the client that the notification for \s-1PATHNAME\s0 has been
1748 done. There should be one such response for every `\fBNotify\fR'
1749 request; if there are several `\fBNotify\fR' requests for a single file,
1750 the requests should be processed in order; the first `\fBNotified\fR'
1751 response pertains to the first `\fBNotify\fR' request, etc.
1753 `\fBModule-expansion \s-1PATHNAME\s0 \en\fR'
1754 Return a file or directory which is included in a particular
1755 module. \s-1PATHNAME\s0 is relative to cvsroot, unlike most pathnames in
1756 responses. \s-1PATHNAME\s0 should be used to look and see whether some
1757 or all of the module exists on the client side; it is not
1758 necessarily suitable for passing as an argument to a `\fBco\fR' request
1759 (for example, if the modules file contains the `\fB\-d\fR' option, it
1760 will be the directory specified with `\fB\-d\fR', not the name of the
1763 `\fBWrapper-rcsOption \s-1PATTERN\s0 \-k \fR'\s-1OPTION\s0' \en'
1764 Transmit to the client a filename pattern which implies a certain
1765 keyword expansion mode. The \s-1PATTERN\s0 is a wildcard pattern (for
1766 example, `\fB*.exe\fR'. The \s-1OPTION\s0 is `\fBb\fR' for binary, and so on. Note
1767 that although the syntax happens to resemble the syntax in certain
1768 \&\s-1CVS\s0 configuration files, it is more constrained; there must be
1769 exactly one space between \s-1PATTERN\s0 and `\fB\-k\fR' and exactly one space
1770 between `\fB\-k\fR' and `'', and no string is permitted in place of `\fB\-k\fR'
1771 (extensions should be done with new responses, not by extending
1772 this one, for graceful handling of `\fBValid-responses\fR').
1774 `\fBM \s-1TEXT\s0 \en\fR'
1775 A one-line message for the user. Note that the format of \s-1TEXT\s0 is
1776 not designed for machine parsing. Although sometimes scripts and
1777 clients will have little choice, the exact text which is output is
1778 subject to vary at the discretion of the server and the example
1779 output given in this document is just that, example output.
1780 Servers are encouraged to use the `\fB\s-1MT\s0\fR' response, and future
1781 versions of this document will hopefully standardize more of the
1782 `\fB\s-1MT\s0\fR' tags; see see \*(L"Text tags\*(R".
1785 Additional data: file transmission (note: compressed file
1786 transmissions are not supported). This is like `\fBM\fR', except the
1787 contents of the file transmission are binary and should be copied
1788 to standard output without translation to local text file
1789 conventions. To transmit a text file to standard output, servers
1790 should use a series of `\fBM\fR' requests.
1792 `\fBE \s-1TEXT\s0 \en\fR'
1793 Same as `\fBM\fR' but send to stderr not stdout.
1796 Flush stderr. That is, make it possible for the user to see what
1797 has been written to stderr (it is up to the implementation to
1798 decide exactly how far it should go to ensure this).
1800 `\fB\s-1MT TAGNAME DATA\s0 \en\fR'
1801 This response provides for tagged text. It is similar to
1802 \&\s-1SGML/HTML/XML\s0 in that the data is structured and a naive
1803 application can also make some sense of it without understanding
1804 the structure. The syntax is not SGML-like, however, in order to
1805 fit into the \s-1CVS\s0 protocol better and (more importantly) to make it
1806 easier to parse, especially in a language like perl or awk.
1808 The \s-1TAGNAME\s0 can have several forms. If it starts with `\fBa\fR' to `\fBz\fR'
1809 or `\fBA\fR' to `\fBZ\fR', then it represents tagged text. If the
1810 implementation recognizes \s-1TAGNAME,\s0 then it may interpret \s-1DATA\s0 in
1811 some particular fashion. If the implementation does not recognize
1812 \&\s-1TAGNAME,\s0 then it should simply treat \s-1DATA\s0 as text to be sent to
1813 the user (similar to an `\fBM\fR' response). There are two tags which
1814 are general purpose. The `\fBtext\fR' tag is similar to an unrecognized
1815 tag in that it provides text which will ordinarily be sent to the
1816 user. The `\fBnewline\fR' tag is used without \s-1DATA\s0 and indicates that a
1817 newline will ordinarily be sent to the user (there is no provision
1818 for embedding newlines in the \s-1DATA\s0 of other tagged text responses).
1820 If \s-1TAGNAME\s0 starts with `\fB+\fR' it indicates a start tag and if it
1821 starts with `\fB\-\fR' it indicates an end tag. The remainder of \s-1TAGNAME\s0
1822 should be the same for matching start and end tags, and tags
1823 should be nested (for example one could have tags in the following
1824 order `\fB+bold\fR' `\fB+italic\fR' `\fBtext\fR' `\fB\-italic\fR' `\fB\-bold\fR' but not `\fB+bold\fR'
1825 `\fB+italic\fR' `\fBtext\fR' `\fB\-bold\fR' `\fB\-italic\fR'). A particular start and end
1826 tag may be documented to constrain the tagged text responses which
1827 are valid between them.
1829 Note that if \s-1DATA\s0 is present there will always be exactly one
1830 space between \s-1TAGNAME\s0 and \s-1DATA\s0; if there is more than one space,
1831 then the spaces beyond the first are part of \s-1DATA.\s0
1833 Here is an example of some tagged text responses. Note that there
1834 is a trailing space after `\fBChecking in\fR' and `\fBinitial revision:\fR'
1835 and there are two trailing spaces after `\fB<\-\-\fR'. Such trailing
1836 spaces are, of course, part of \s-1DATA.\s0
1838 \&\s-1MT\s0 +checking\-in
1839 \&\s-1MT\s0 text Checking in
1840 \&\s-1MT\s0 fname gz.tst
1843 \&\s-1MT\s0 rcsfile /home/kingdon/zwork/cvsroot/foo/gz.tst,v
1844 \&\s-1MT\s0 text <\-\-
1845 \&\s-1MT\s0 fname gz.tst
1847 \&\s-1MT\s0 text initial revision:
1848 \&\s-1MT\s0 init-rev 1.1
1850 \&\s-1MT\s0 text done
1852 \&\s-1MT\s0 \-checking\-in
1854 If the client does not support the `\fB\s-1MT\s0\fR' response, the same
1855 responses might be sent as:
1857 M Checking in gz.tst;
1858 M /home/kingdon/zwork/cvsroot/foo/gz.tst,v <\-\- gz.tst
1859 M initial revision: 1.1
1862 For a list of specific tags, see see \*(L"Text tags\*(R".
1864 `error ERRNO-CODE `\fB \fR' \s-1TEXT\s0 \en'
1865 The command completed with an error. ERRNO-CODE is a symbolic
1866 error code (e.g. `\fB\s-1ENOENT\s0\fR'); if the server doesn't support this
1867 feature, or if it's not appropriate for this particular message,
1868 it just omits the errno-code (in that case there are two spaces
1869 after `\fBerror\fR'). Text is an error message such as that provided by
1870 \&\fIstrerror()\fR, or any other message the server wants to use. The
1871 \&\s-1TEXT\s0 is like the `\fBM\fR' response, in the sense that it is not
1872 particularly intended to be machine-parsed; servers may wish to
1873 print an error message with `\fB\s-1MT\s0\fR' responses, and then issue a
1874 `\fBerror\fR' response without \s-1TEXT \s0(although it should be noted that
1875 `\fB\s-1MT\s0\fR' currently has no way of flagging the output as intended for
1876 standard error, the way that the `\fBE\fR' response does).
1879 The command completed successfully.
1881 \&\fB5.12 Tags for the \s-1MT\s0 tagged text response\fR
1883 The `\fB\s-1MT\s0\fR' response, as described in see \*(L"Responses\*(R", offers a way for
1884 the server to send tagged text to the client. This section describes
1885 specific tags. The intention is to update this section as servers add
1888 In the following descriptions, `\fBtext\fR' and `\fBnewline\fR' tags are
1889 omitted. Such tags contain information which is intended for users (or
1890 to be discarded), and are subject to change at the whim of the server.
1891 To avoid being vulnerable to such whim, clients should look for the tags
1892 listed here, not `\fBtext\fR', `\fBnewline\fR', or other tags.
1894 The following tag means to indicate to the user that a file has been
1895 updated. It is more or less redundant with the `\fBCreated\fR' and
1896 `\fBUpdate-existing\fR' responses, but we don't try to specify here whether
1897 it occurs in exactly the same circumstances as `\fBCreated\fR' and
1898 `\fBUpdate-existing\fR'. The \s-1NAME\s0 is the pathname of the file being updated
1899 relative to the directory in which the command is occurring (that is,
1900 the last `\fBDirectory\fR' request which is sent before the command).
1902 \&\s-1MT\s0 +updated
1903 \&\s-1MT\s0 fname \s-1NAME
1906 The `\fBimportmergecmd\fR' tag is used when doing an import which has
1907 conflicts, or when doing an import with the `\fB\-X\fR' flag. The client can
1908 use it to report how to merge in the newly imported changes. The \s-1COUNT\s0
1909 is the number of conflicts, or the string `\fBNo\fR' if no conflicts
1910 occurred. (The latter will only be sent for imports run with the `\fB\-X\fR'
1911 flag.) The newly imported changes can be merged by running the
1913 cvs checkout \-j \s-1TAG1\s0 \-j \s-1TAG2 REPOSITORY\s0
1915 \&\s-1MT\s0 +importmergecmd
1916 \&\s-1MT\s0 conflicts \s-1COUNT
1917 MT\s0 mergetag1 \s-1TAG1
1918 MT\s0 mergetag2 \s-1TAG2
1919 MT\s0 repository \s-1REPOSITORY
1920 MT\s0 \-importmergecmd
1922 \&\fB5.13 Example\fR
1924 Here is an example; lines are prefixed by `\fBC: \fR' to indicate the client
1925 sends them or `\fBS: \fR' to indicate the server sends them.
1927 The client starts by connecting, sending the root, and completing the
1928 protocol negotiation. In actual practice the lists of valid responses
1929 and requests would be longer.
1932 C: Valid-responses ok error Checked-in M E
1934 S: Valid-requests Root Directory Entry Modified Argument Argumentx ci co
1938 The client wants to check out the `\fBsupermunger\fR' module into a fresh
1939 working directory. Therefore it first expands the `\fBsupermunger\fR'
1940 module; this step would be omitted if the client was operating on a
1941 directory rather than a module.
1943 C: Argument supermunger
1948 The server replies that the `\fBsupermunger\fR' module expands to the
1949 directory `\fBsupermunger\fR' (the simplest case):
1951 S: Module-expansion supermunger
1954 The client then proceeds to check out the directory. The fact that
1955 it sends only a single `\fBDirectory\fR' request which specifies `\fB.\fR' for the
1956 working directory means that there is not already a `\fBsupermunger\fR'
1957 directory on the client.
1960 C: Argument supermunger
1965 The server replies with the requested files. In this example, there
1966 is only one file, `\fBmungeall.c\fR'. The `\fBClear-sticky\fR' and
1967 `\fBClear-static-directory\fR' requests are sent by the current
1968 implementation but they have no effect because the default is for those
1969 settings to be clear when a directory is newly created.
1971 S: Clear-sticky supermunger/
1972 S: /u/cvsroot/supermunger/
1973 S: Clear-static-directory supermunger/
1974 S: /u/cvsroot/supermunger/
1975 S: E cvs server: Updating supermunger
1976 S: M U supermunger/mungeall.c
1977 S: Created supermunger/
1978 S: /u/cvsroot/supermunger/mungeall.c
1979 S: /mungeall.c/1.1///
1982 S: int mein () { abort (); }
1985 The current client implementation would break the connection here
1986 and make a new connection for the next command. However, the protocol
1987 allows it to keep the connection open and continue, which is what we
1990 After the user modifies the file and instructs the client to check it
1991 back in. The client sends arguments to specify the log message and file
1995 C: Argument Well, you see, it took me hours and hours to find
1996 C: Argumentx this typo and I searched and searched and eventually
1997 C: Argumentx had to ask John for help.
1998 C: Argument mungeall.c
2000 It also sends information about the contents of the working
2001 directory, including the new contents of the modified file. Note that
2002 the user has changed into the `\fBsupermunger\fR' directory before executing
2003 this command; the top level directory is a user-visible concept because
2004 the server should print filenames in `\fBM\fR' and `\fBE\fR' responses relative to
2009 C: Entry /mungeall.c/1.1///
2010 C: Modified mungeall.c
2013 C: int main () { abort (); }
2015 And finally, the client issues the checkin command (which makes use
2016 of the data just sent):
2020 And the server tells the client that the checkin succeeded:
2022 S: M Checking in mungeall.c;
2023 S: E /u/cvsroot/supermunger/mungeall.c,v <\-\- mungeall.c
2024 S: E new revision: 1.2; previous revision: 1.1
2026 S: Mode u=rw,g=r,o=r
2028 S: /u/cvsroot/supermunger/mungeall.c
2029 S: /mungeall.c/1.2///
2032 \&\fB5.14 Required versus optional parts of the protocol\fR
2034 The following are part of every known implementation of the \s-1CVS\s0 protocol
2035 (except obsolete, pre\-1.5, versions of \s-1CVS\s0) and it is considered
2036 reasonable behavior to completely fail to work if you are connected with
2037 an implementation which attempts to not support them. Requests:
2038 `\fBRoot\fR', `\fBValid-responses\fR', `\fBvalid-requests\fR', `\fBDirectory\fR', `\fBEntry\fR',
2039 `\fBModified\fR', `\fBUnchanged\fR', `\fBArgument\fR', `\fBArgumentx\fR', `\fBci\fR', `\fBco\fR', `\fBupdate\fR'.
2040 Responses: `\fBok\fR', `\fBerror\fR', `\fBValid-requests\fR', `\fBChecked-in\fR', `\fBUpdated\fR',
2041 `\fBMerged\fR', `\fBRemoved\fR', `\fBM\fR', `\fBE\fR'.
2043 A server need not implement `\fBRepository\fR', but in order to
2044 interoperate with \s-1CVS 1.5\s0 through 1.9 it must claim to implement it (in
2045 `\fBValid-requests\fR'). The client will not actually send the request.
2047 \&\fB5.15 Obsolete protocol elements\fR
2049 This section briefly describes protocol elements which are obsolete.
2050 There is no attempt to document them in full detail.
2052 There was a `\fBRepository\fR' request which was like `\fBDirectory\fR' except
2053 it only provided \s-1REPOSITORY,\s0 and the local directory was assumed to be
2056 If the `\fBUseUnchanged\fR' request was not sent, there was a `\fBLost\fR'
2057 request which was sent to indicate that a file did not exist in the
2058 working directory, and the meaning of sending `\fBEntries\fR' without `\fBLost\fR'
2059 or `\fBModified\fR' was different. All current clients (\s-1CVS 1.5\s0 and later)
2060 will send `\fBUseUnchanged\fR' if it is supported.
2061 .SS "6 Notes on the Protocol"
2062 .IX Subsection "6 Notes on the Protocol"
2063 A number of enhancements are possible. Also see the file \s-1TODO\s0 in the
2064 \&\s-1CVS\s0 source distribution, which has further ideas concerning various
2065 aspects of \s-1CVS,\s0 some of which impact the protocol. Similarly, the
2066 `\fBhttp://www.nongnu.org/cvs/\fR' site, in particular the `\fBDevelopment\fR'
2069 * The `\fBModified\fR' request could be speeded up by sending diffs rather
2070 than entire files. The client would need some way to keep the
2071 version of the file which was originally checked out; probably
2072 requiring the use of \*(L"cvs edit\*(R" in this case is the most sensible
2073 course (the \*(L"cvs edit\*(R" could be handled by a package like \s-1VC\s0 for
2074 emacs). This would also allow local operation of `\fBcvs diff\fR'
2077 * The fact that `\fBpserver\fR' requires an extra network turnaround in
2078 order to perform authentication would be nice to avoid. This
2079 relates to the issue of reporting errors; probably the clean
2080 solution is to defer the error until the client has issued a
2081 request which expects a response. To some extent this might
2082 relate to the next item (in terms of how easy it is to skip a
2083 whole bunch of requests until we get to one that expects a
2084 response). I know that the kerberos code doesn't wait in this
2085 fashion, but that probably can cause network deadlocks and perhaps
2086 future problems running over a transport which is more transaction
2087 oriented than \s-1TCP. \s0 On the other hand I'm not sure it is wise to
2088 make the client conduct a lengthy upload only to find there is an
2089 authentication failure.
2091 * The protocol uses an extra network turnaround for protocol
2092 negotiation (`\fBvalid-requests\fR'). It might be nice to avoid this by
2093 having the client be able to send requests and tell the server to
2094 ignore them if they are unrecognized (different requests could
2095 produce a fatal error if unrecognized). To do this there should
2096 be a standard syntax for requests. For example, perhaps all
2097 future requests should be a single line, with mechanisms analogous
2098 to `\fBArgumentx\fR', or several requests working together, to provide
2099 greater amounts of information. Or there might be a standard
2100 mechanism for counted data (analogous to that used by `\fBModified\fR')
2101 or continuation lines (like a generalized `\fBArgumentx\fR'). It would
2102 be useful to compare what \s-1HTTP\s0 is planning in this area; last I
2103 looked they were contemplating something called Protocol Extension
2104 Protocol but I haven't looked at the relevant \s-1IETF\s0 documents in
2105 any detail. Obviously, we want something as simple as possible
2108 * The scrambling algorithm in the \s-1CVS\s0 client and server actually
2109 support more characters than those documented in *note Password
2110 scrambling::. Someday we are going to either have to document
2111 them all (but this is not as easy as it may look, see below), or
2112 (gradually and with adequate process) phase out the support for
2113 other characters in the \s-1CVS\s0 implementation. This business of
2114 having the feature partly undocumented isn't a desirable state
2117 The problem with documenting other characters is that unless we
2118 know what character set is in use, there is no way to make a
2119 password portable from one system to another. For example, a with
2120 a circle on top might have different encodings in different
2123 It _almost_ works to say that the client picks an arbitrary,
2124 unknown character set (indeed, having the \s-1CVS\s0 client know what
2125 character set the user has in mind is a hard problem otherwise),
2126 and scrambles according to a certain octet<\->octet mapping. There
2127 are two problems with this. One is that the protocol has no way
2128 to transmit character 10 decimal (linefeed), and the current
2129 server and clients have no way to handle 0 decimal (\s-1NUL\s0). This
2130 may cause problems with certain multibyte character sets, in which
2131 octets 10 and 0 will appear in the middle of other characters.
2132 The other problem, which is more minor and possibly not worth
2133 worrying about, is that someone can type a password on one system
2134 and then go to another system which uses a different encoding for
2135 the same characters, and have their password not work.
2137 The restriction to the \s-1ISO646\s0 invariant subset is the best
2138 approach for strings which are not particularly significant to
2139 users. Passwords are visible enough that this is somewhat
2140 doubtful as applied here. \s-1ISO646\s0 does, however, have the virtue
2141 (!?) of offending everyone. It is easy to say \*(L"But the $ is right
2142 on people's keyboards! Surely we can't forbid that\*(R". From a
2143 human factors point of view, that makes quite a bit of sense. The
2144 contrary argument, of course, is that a with a circle on top, or
2145 some of the characters poorly handled by Unicode, are on
2146 _someone_'s keyboard.
projects / dragonfly.git / blob