1This is Info file cvsclient.info, produced by Makeinfo version 1.67 2from the input file ../../work/ccvs/doc/cvsclient.texi. 3 4 5File: cvsclient.info, Node: Top, Next: Introduction, Up: (dir) 6 7CVS Client/Server 8***************** 9 10 This document describes the client/server protocol used by CVS. It 11does not describe how to use or administer client/server CVS; see the 12regular CVS manual for that. This is version 1.9.26 of the protocol 13specification--*Note Introduction::, for more on what this version 14number means. 15 16* Menu: 17 18* Introduction:: What is CVS and what is the client/server protocol for? 19* Goals:: Basic design decisions, requirements, scope, etc. 20* Connection and Authentication:: Various ways to connect to the server 21* Password scrambling:: Scrambling used by pserver 22* Protocol:: Complete description of the protocol 23* Protocol Notes:: Possible enhancements, limitations, etc. of the protocol 24 25 26File: cvsclient.info, Node: Introduction, Next: Goals, Prev: Top, Up: Top 27 28Introduction 29************ 30 31 CVS is a version control system (with some additional configuration 32management functionality). It maintains a central "repository" which 33stores files (often source code), including past versions, information 34about who modified them and when, and so on. People who wish to look 35at or modify those files, known as "developers", use CVS to "check out" 36a "working directory" from the repository, to "check in" new versions 37of files to the repository, and other operations such as viewing the 38modification history of a file. If developers are connected to the 39repository by a network, particularly a slow or flaky one, the most 40efficient way to use the network is with the CVS-specific protocol 41described in this document. 42 43 Developers, using the machine on which they store their working 44directory, run the CVS "client" program. To perform operations which 45cannot be done locally, it connects to the CVS "server" program, which 46maintains the repository. For more information on how to connect see 47*Note Connection and Authentication::. 48 49 This document describes the CVS protocol. Unfortunately, it does not 50yet completely document one aspect of the protocol--the detailed 51operation of each CVS command and option--and one must look at the CVS 52user documentation, `cvs.texinfo', for that information. The protocol 53is non-proprietary (anyone who wants to is encouraged to implement it) 54and an implementation, known as CVS, is available under the GNU Public 55License. The CVS distribution, containing this implementation, 56`cvs.texinfo', and a copy (possibly more or less up to date than what 57you are reading now) of this document, `cvsclient.texi', can be found 58at the usual GNU FTP sites, with a filename such as 59`cvs-VERSION.tar.gz'. 60 61 This is version 1.9.26 of the protocol specification. This version 62number is intended only to aid in distinguishing different versions of 63this specification. Although the specification is currently maintained 64in conjunction with the CVS implementation, and carries the same 65version number, it also intends to document what is involved with 66interoperating with other implementations (such as other versions of 67CVS); see *Note Requirements::. This version number should not be used 68by clients or servers to determine what variant of the protocol to 69speak; they should instead use the `valid-requests' and 70`Valid-responses' mechanism (*note Protocol::.), which is more flexible. 71 72 73File: cvsclient.info, Node: Goals, Next: Connection and Authentication, Prev: Introduction, Up: Top 74 75Goals 76***** 77 78 * Do not assume any access to the repository other than via this 79 protocol. It does not depend on NFS, rdist, etc. 80 81 * Providing a reliable transport is outside this protocol. The 82 protocol expects a reliable transport that is transparent (that 83 is, there is no translation of characters, including characters 84 such as such as linefeeds or carriage returns), and can transmit 85 all 256 octets (for example for proper handling of binary files, 86 compression, and encryption). The encoding of characters 87 specified by the protocol (the names of requests and so on) is the 88 invariant ISO 646 character set (a subset of most popular 89 character sets including ASCII and others). For more details on 90 running the protocol over the TCP reliable transport, see *Note 91 Connection and Authentication::. 92 93 * Security and authentication are handled outside this protocol (but 94 see below about `cvs kserver' and `cvs pserver'). 95 96 * The protocol makes it possible for updates to be atomic with 97 respect to checkins; that is if someone commits changes to several 98 files in one cvs command, then an update by someone else would 99 either get all the changes, or none of them. The current CVS 100 server can't do this, but that isn't the protocol's fault. 101 102 * The protocol is, with a few exceptions, transaction-based. That 103 is, the client sends all its requests (without waiting for server 104 responses), and then waits for the server to send back all 105 responses (without waiting for further client requests). This has 106 the advantage of minimizing network turnarounds and the 107 disadvantage of sometimes transferring more data than would be 108 necessary if there were a richer interaction. Another, more 109 subtle, advantage is that there is no need for the protocol to 110 provide locking for features such as making checkins atomic with 111 respect to updates. Any such locking can be handled entirely by 112 the server. A good server implementation (such as the current CVS 113 server) will make sure that it does not have any such locks in 114 place whenever it is waiting for communication with the client; 115 this prevents one client on a slow or flaky network from 116 interfering with the work of others. 117 118 * It is a general design goal to provide only one way to do a given 119 operation (where possible). For example, implementations have no 120 choice about whether to terminate lines with linefeeds or some 121 other character(s), and request and response names are 122 case-sensitive. This is to enhance interoperability. If a 123 protocol allows more than one way to do something, it is all too 124 easy for some implementations to support only some of them 125 (perhaps accidentally). 126 127 128File: cvsclient.info, Node: Connection and Authentication, Next: Password scrambling, Prev: Goals, Up: Top 129 130How to Connect to and Authenticate Oneself to the CVS server 131************************************************************ 132 133 Connection and authentication occurs before the CVS protocol itself 134is started. There are several ways to connect. 135 136server 137 If the client has a way to execute commands on the server, and 138 provide input to the commands and output from them, then it can 139 connect that way. This could be the usual rsh (port 514) 140 protocol, Kerberos rsh, SSH, or any similar mechanism. The client 141 may allow the user to specify the name of the server program; the 142 default is `cvs'. It is invoked with one argument, `server'. 143 Once it invokes the server, the client proceeds to start the cvs 144 protocol. 145 146kserver 147 The kerberized server listens on a port (in the current 148 implementation, by having inetd call "cvs kserver") which defaults 149 to 1999. The client connects, sends the usual kerberos 150 authentication information, and then starts the cvs protocol. 151 Note: port 1999 is officially registered for another use, and in 152 any event one cannot register more than one port for CVS, so 153 GSS-API (see below) is recommended instead of kserver as a way to 154 support kerberos. 155 156pserver 157 The name "pserver" is somewhat confusing. It refers to both a 158 generic framework which allows the CVS protocol to support several 159 authentication mechanisms, and a name for a specific mechanism 160 which transfers a username and a cleartext password. Servers need 161 not support all mechanisms, and in fact servers will typically 162 want to support only those mechanisms which meet the relevant 163 security needs. 164 165 The pserver server listens on a port (in the current 166 implementation, by having inetd call "cvs pserver") which defaults 167 to 2401 (this port is officially registered). The client 168 connects, and sends the following: 169 170 * the string `BEGIN AUTH REQUEST', a linefeed, 171 172 * the cvs root, a linefeed, 173 174 * the username, a linefeed, 175 176 * the password trivially encoded (see *Note Password 177 scrambling::), a linefeed, 178 179 * the string `END AUTH REQUEST', and a linefeed. 180 181 The client must send the identical string for cvs root both here 182 and later in the `Root' request of the cvs protocol itself. 183 Servers are encouraged to enforce this restriction. The possible 184 server responses (each of which is followed by a linefeed) are the 185 following. Note that although there is a small similarity between 186 this authentication protocol and the cvs protocol, they are 187 separate. 188 189 `I LOVE YOU' 190 The authentication is successful. The client proceeds with 191 the cvs protocol itself. 192 193 `I HATE YOU' 194 The authentication fails. After sending this response, the 195 server may close the connection. It is up to the server to 196 decide whether to give this response, which is generic, or a 197 more specific response using `E' and/or `error'. 198 199 `E TEXT' 200 Provide a message for the user. After this reponse, the 201 authentication protocol continues with another response. 202 Typically the server will provide a series of `E' responses 203 followed by `error'. Compatibility note: CVS 1.9.10 and 204 older clients will print `unrecognized auth response' and 205 TEXT, and then exit, upon receiving this response. 206 207 `error CODE TEXT' 208 The authentication fails. After sending this response, the 209 server may close the connection. The CODE is a code 210 describing why it failed, intended for computer consumption. 211 The only code currently defined is `0' which is nonspecific, 212 but clients must silently treat any unrecognized codes as 213 nonspecific. The TEXT should be supplied to the user. 214 Compatibility note: CVS 1.9.10 and older clients will print 215 `unrecognized auth response' and TEXT, and then exit, upon 216 receiving this response. 217 218 If the client wishes to merely authenticate without starting the 219 cvs protocol, the procedure is the same, except BEGIN AUTH REQUEST 220 is replaced with BEGIN VERIFICATION REQUEST, END AUTH REQUEST is 221 replaced with END VERIFICATION REQUEST, and upon receipt of I LOVE 222 YOU the connection is closed rather than continuing. 223 224 Another mechanism is GSSAPI authentication. GSSAPI is a generic 225 interface to security services such as kerberos. GSSAPI is 226 specified in RFC2078 (GSSAPI version 2) and RFC1508 (GSSAPI 227 version 1); we are not aware of differences between the two which 228 affect the protocol in incompatible ways, so we make no attempt to 229 specify one version or the other. The procedure here is to start 230 with `BEGIN GSSAPI REQUEST'. GSSAPI authentication information is 231 then exchanged between the client and the server. Each packet of 232 information consists of a two byte big endian length, followed by 233 that many bytes of data. After the GSSAPI authentication is 234 complete, the server continues with the responses described above 235 (`I LOVE YOU', etc.). 236 237future possibilities 238 There are a nearly unlimited number of ways to connect and 239 authenticate. One might want to allow access based on IP address 240 (similar to the usual rsh protocol but with different/no 241 restrictions on ports < 1024), to adopt mechanisms such as 242 Pluggable Authentication Modules (PAM), to allow users to run 243 their own servers under their own usernames without root access, 244 or any number of other possibilities. The way to add future 245 mechanisms, for the most part, should be to continue to use port 246 2401, but to use different strings in place of `BEGIN AUTH 247 REQUEST'. 248 249 250File: cvsclient.info, Node: Password scrambling, Next: Protocol, Prev: Connection and Authentication, Up: Top 251 252Password scrambling algorithm 253***************************** 254 255 The pserver authentication protocol, as described in *Note 256Connection and Authentication::, trivially encodes the passwords. This 257is only to prevent inadvertent compromise; it provides no protection 258against even a relatively unsophisticated attacker. For comparison, 259HTTP Basic Authentication (as described in RFC2068) uses BASE64 for a 260similar purpose. CVS uses its own algorithm, described here. 261 262 The scrambled password starts with `A', which serves to identify the 263scrambling algorithm in use. After that follows a single octet for 264each character in the password, according to a fixed encoding. The 265values are shown here, with the encoded values in decimal. Control 266characters, space, and characters outside the invariant ISO 646 267character set are not shown; such characters are not recommended for use 268in passwords. There is a long discussion of character set issues in 269*Note Protocol Notes::. 270 271 0 111 P 125 p 58 272 ! 120 1 52 A 57 Q 55 a 121 q 113 273 " 53 2 75 B 83 R 54 b 117 r 32 274 3 119 C 43 S 66 c 104 s 90 275 4 49 D 46 T 124 d 101 t 44 276 % 109 5 34 E 102 U 126 e 100 u 98 277 & 72 6 82 F 40 V 59 f 69 v 60 278 ' 108 7 81 G 89 W 47 g 73 w 51 279 ( 70 8 95 H 38 X 92 h 99 x 33 280 ) 64 9 65 I 103 Y 71 i 63 y 97 281 * 76 : 112 J 45 Z 115 j 94 z 62 282 + 67 ; 86 K 50 k 93 283 , 116 < 118 L 42 l 39 284 - 74 = 110 M 123 m 37 285 . 68 > 122 N 91 n 61 286 / 87 ? 105 O 35 _ 56 o 48 287 288 289File: cvsclient.info, Node: Protocol, Next: Protocol Notes, Prev: Password scrambling, Up: Top 290 291The CVS client/server protocol 292****************************** 293 294 In the following, `\n' refers to a linefeed and `\t' refers to a 295horizontal tab; "requests" are what the client sends and "responses" 296are what the server sends. In general, the connection is governed by 297the client--the server does not send responses without first receiving 298requests to do so; see *Note Response intro:: for more details of this 299convention. 300 301 It is typical, early in the connection, for the client to transmit a 302`Valid-responses' request, containing all the responses it supports, 303followed by a `valid-requests' request, which elicits from the server a 304`Valid-requests' response containing all the requests it understands. 305In this way, the client and server each find out what the other 306supports before exchanging large amounts of data (such as file 307contents). 308 309* Menu: 310 311 312General protocol conventions: 313 314* Entries Lines:: Transmitting RCS data 315* File Modes:: Read, write, execute, and possibly more... 316* Filenames:: Conventions regarding filenames 317* File transmissions:: How file contents are transmitted 318* Strings:: Strings in various requests and responses 319 320The protocol itself: 321 322* Request intro:: General conventions relating to requests 323* Requests:: List of requests 324* Response intro:: General conventions relating to responses 325* Response pathnames:: The "pathname" in responses 326* Responses:: List of responses 327* Text tags:: More details about the MT response 328 329An example session, and some further observations: 330 331* Example:: A conversation between client and server 332* Requirements:: Things not to omit from an implementation 333* Obsolete:: Former protocol features 334 335 336File: cvsclient.info, Node: Entries Lines, Next: File Modes, Up: Protocol 337 338Entries Lines 339============= 340 341 Entries lines are transmitted as: 342 343 / NAME / VERSION / CONFLICT / OPTIONS / TAG_OR_DATE 344 345 TAG_OR_DATE is either `T' TAG or `D' DATE or empty. If it is 346followed by a slash, anything after the slash shall be silently ignored. 347 348 VERSION can be empty, or start with `0' or `-', for no user file, 349new user file, or user file to be removed, respectively. 350 351 CONFLICT, if it starts with `+', indicates that the file had 352conflicts in it. The rest of CONFLICT is `=' if the timestamp matches 353the file, or anything else if it doesn't. If CONFLICT does not start 354with a `+', it is silently ignored. 355 356 OPTIONS signifies the keyword expansion options (for example `-ko'). 357In an `Entry' request, this indicates the options that were specified 358with the file from the previous file updating response (*note Response 359intro::., for a list of file updating responses); if the client is 360specifying the `-k' or `-A' option to `update', then it is the server 361which figures out what overrides what. 362 363 364File: cvsclient.info, Node: File Modes, Next: Filenames, Prev: Entries Lines, Up: Protocol 365 366File Modes 367========== 368 369 A mode is any number of repetitions of 370 371 MODE-TYPE = DATA 372 373 separated by `,'. 374 375 MODE-TYPE is an identifier composed of alphanumeric characters. 376Currently specified: `u' for user, `g' for group, `o' for other (see 377below for discussion of whether these have their POSIX meaning or are 378more loose). Unrecognized values of MODE-TYPE are silently ignored. 379 380 DATA consists of any data not containing `,', `\0' or `\n'. For 381`u', `g', and `o' mode types, data consists of alphanumeric characters, 382where `r' means read, `w' means write, `x' means execute, and 383unrecognized letters are silently ignored. 384 385 The two most obvious ways in which the mode matters are: (1) is it 386writeable? This is used by the developer communication features, and 387is implemented even on OS/2 (and could be implemented on DOS), whose 388notion of mode is limited to a readonly bit. (2) is it executable? 389Unix CVS users need CVS to store this setting (for shell scripts and 390the like). The current CVS implementation on unix does a little bit 391more than just maintain these two settings, but it doesn't really have 392a nice general facility to store or version control the mode, even on 393unix, much less across operating systems with diverse protection 394features. So all the ins and outs of what the mode means across 395operating systems haven't really been worked out (e.g. should the VMS 396port use ACLs to get POSIX semantics for groups?). 397 398 399File: cvsclient.info, Node: Filenames, Next: File transmissions, Prev: File Modes, Up: Protocol 400 401Conventions regarding transmission of file names 402================================================ 403 404 In most contexts, `/' is used to separate directory and file names 405in filenames, and any use of other conventions (for example, that the 406user might type on the command line) is converted to that form. The 407only exceptions might be a few cases in which the server provides a 408magic cookie which the client then repeats verbatim, but as the server 409has not yet been ported beyond unix, the two rules provide the same 410answer (and what to do if future server ports are operating on a 411repository like e:/foo or CVS_ROOT:[FOO.BAR] has not been carefully 412thought out). 413 414 Characters outside the invariant ISO 646 character set should be 415avoided in filenames. This restriction may need to be relaxed to allow 416for characters such as `[' and `]' (see above about non-unix servers); 417this has not been carefully considered (and currently implementations 418probably use whatever character sets that the operating systems they 419are running on allow, and/or that users specify). Of course the most 420portable practice is to restrict oneself further, to the POSIX portable 421filename character set as specified in POSIX.1. 422 423 424File: cvsclient.info, Node: File transmissions, Next: Strings, Prev: Filenames, Up: Protocol 425 426File transmissions 427================== 428 429 File contents (noted below as FILE TRANSMISSION) can be sent in one 430of two forms. The simpler form is a number of bytes, followed by a 431linefeed, followed by the specified number of bytes of file contents. 432These are the entire contents of the specified file. Second, if both 433client and server support `gzip-file-contents', a `z' may precede the 434length, and the `file contents' sent are actually compressed with 435`gzip' (RFC1952/1951) compression. The length specified is that of the 436compressed version of the file. 437 438 In neither case are the file content followed by any additional data. 439The transmission of a file will end with a linefeed iff that file (or 440its compressed form) ends with a linefeed. 441 442 The encoding of file contents depends on the value for the `-k' 443option. If the file is binary (as specified by the `-kb' option in the 444appropriate place), then it is just a certain number of octets, and the 445protocol contributes nothing towards determining the encoding (using 446the file name is one widespread, if not universally popular, mechanism). 447If the file is text (not binary), then the file is sent as a series of 448lines, separated by linefeeds. If the keyword expansion is set to 449something other than `-ko', then it is expected that the file conform 450to the RCS expectations regarding keyword expansion--in particular, 451that it is in a character set such as ASCII in which 0x24 is a dollar 452sign (`$'). 453 454 455File: cvsclient.info, Node: Strings, Next: Request intro, Prev: File transmissions, Up: Protocol 456 457Strings 458======= 459 460 In various contexts, for example the `Argument' request and the `M' 461response, one transmits what is essentially an arbitrary string. Often 462this will have been supplied by the user (for example, the `-m' option 463to the `ci' request). The protocol has no mechanism to specify the 464character set of such strings; it would be fairly safe to stick to the 465invariant ISO 646 character set but the existing practice is probably 466to just transmit whatever the user specifies, and hope that everyone 467involved agrees which character set is in use, or sticks to a common 468subset. 469 470 471File: cvsclient.info, Node: Request intro, Next: Requests, Prev: Strings, Up: Protocol 472 473Request intro 474============= 475 476 By convention, requests which begin with a capital letter do not 477elicit a response from the server, while all others do - save one. The 478exception is `gzip-file-contents'. Unrecognized requests will always 479elicit a response from the server, even if that request begins with a 480capital letter. 481 482 483File: cvsclient.info, Node: Requests, Next: Response intro, Prev: Request intro, Up: Protocol 484 485Requests 486======== 487 488 Here are the requests: 489 490`Root PATHNAME \n' 491 Response expected: no. Tell the server which `CVSROOT' to use. 492 Note that PATHNAME is a local directory and *not* a fully 493 qualified `CVSROOT' variable. PATHNAME must already exist; if 494 creating a new root, use the `init' request, not `Root'. PATHNAME 495 does not include the hostname of the server, how to access the 496 server, etc.; by the time the CVS protocol is in use, connection, 497 authentication, etc., are already taken care of. 498 499 The `Root' request must be sent only once, and it must be sent 500 before any requests other than `Valid-responses', 501 `valid-requests', `UseUnchanged', or `init'. 502 503`Valid-responses REQUEST-LIST \n' 504 Response expected: no. Tell the server what responses the client 505 will accept. request-list is a space separated list of tokens. 506 507`valid-requests \n' 508 Response expected: yes. Ask the server to send back a 509 `Valid-requests' response. 510 511`Directory LOCAL-DIRECTORY \n' 512 Additional data: REPOSITORY \n. Response expected: no. Tell the 513 server what directory to use. The REPOSITORY should be a 514 directory name from a previous server response. Note that this 515 both gives a default for `Entry' and `Modified' and also for `ci' 516 and the other commands; normal usage is to send `Directory' for 517 each directory in which there will be an `Entry' or `Modified', 518 and then a final `Directory' for the original directory, then the 519 command. The LOCAL-DIRECTORY is relative to the top level at 520 which the command is occurring (i.e. the last `Directory' which is 521 sent before the command); to indicate that top level, `.' should 522 be send for LOCAL-DIRECTORY. 523 524 Here is an example of where a client gets REPOSITORY and 525 LOCAL-DIRECTORY. Suppose that there is a module defined by 526 527 moddir 1dir 528 529 That is, one can check out `moddir' and it will take `1dir' in the 530 repository and check it out to `moddir' in the working directory. 531 Then an initial check out could proceed like this: 532 533 C: Root /home/kingdon/zwork/cvsroot 534 . . . 535 C: Argument moddir 536 C: Directory . 537 C: /home/kingdon/zwork/cvsroot 538 C: co 539 S: Clear-sticky moddir/ 540 S: /home/kingdon/zwork/cvsroot/1dir/ 541 . . . 542 S: ok 543 544 In this example the response shown is `Clear-sticky', but it could 545 be another response instead. Note that it returns two pathnames. 546 The first one, `moddir/', indicates the working directory to check 547 out into. The second one, ending in `1dir/', indicates the 548 directory to pass back to the server in a subsequent `Directory' 549 request. For example, a subsequent `update' request might look 550 like: 551 552 C: Directory moddir 553 C: /home/kingdon/zwork/cvsroot/1dir 554 . . . 555 C: update 556 557 For a given LOCAL-DIRECTORY, the repository will be the same for 558 each of the responses, so one can use the repository from whichever 559 response is most convenient. Typically a client will store the 560 repository along with the sources for each LOCAL-DIRECTORY, use 561 that same setting whenever operating on that LOCAL-DIRECTORY, and 562 not update the setting as long as the LOCAL-DIRECTORY exists. 563 564 A client is free to rename a LOCAL-DIRECTORY at any time (for 565 example, in response to an explicit user request). While it is 566 true that the server supplies a LOCAL-DIRECTORY to the client, as 567 noted above, this is only the default place to put the directory. 568 Of course, the various `Directory' requests for a single command 569 (for example, `update' or `ci' request) should name a particular 570 directory with the same LOCAL-DIRECTORY. 571 572 Each `Directory' request specifies a brand-new LOCAL-DIRECTORY and 573 REPOSITORY; that is, LOCAL-DIRECTORY and REPOSITORY are never 574 relative to paths specified in any previous `Directory' request. 575 576`Max-dotdot LEVEL \n' 577 Response expected: no. Tell the server that LEVEL levels of 578 directories above the directory which `Directory' requests are 579 relative to will be needed. For example, if the client is 580 planning to use a `Directory' request for `../../foo', it must 581 send a `Max-dotdot' request with a LEVEL of at least 2. 582 `Max-dotdot' must be sent before the first `Directory' request. 583 584`Static-directory \n' 585 Response expected: no. Tell the server that the directory most 586 recently specified with `Directory' should not have additional 587 files checked out unless explicitly requested. The client sends 588 this if the `Entries.Static' flag is set, which is controlled by 589 the `Set-static-directory' and `Clear-static-directory' responses. 590 591`Sticky TAGSPEC \n' 592 Response expected: no. Tell the server that the directory most 593 recently specified with `Directory' has a sticky tag or date 594 TAGSPEC. The first character of TAGSPEC is `T' for a tag, or `D' 595 for a date. The remainder of TAGSPEC contains the actual tag or 596 date. 597 598 The server should remember `Static-directory' and `Sticky' 599 requests for a particular directory; the client need not resend 600 them each time it sends a `Directory' request for a given 601 directory. However, the server is not obliged to remember them 602 beyond the context of a single command. 603 604`Checkin-prog PROGRAM \n' 605 Response expected: no. Tell the server that the directory most 606 recently specified with `Directory' has a checkin program PROGRAM. 607 Such a program would have been previously set with the 608 `Set-checkin-prog' response. 609 610`Update-prog PROGRAM \n' 611 Response expected: no. Tell the server that the directory most 612 recently specified with `Directory' has an update program PROGRAM. 613 Such a program would have been previously set with the 614 `Set-update-prog' response. 615 616`Entry ENTRY-LINE \n' 617 Response expected: no. Tell the server what version of a file is 618 on the local machine. The name in ENTRY-LINE is a name relative 619 to the directory most recently specified with `Directory'. If the 620 user is operating on only some files in a directory, `Entry' 621 requests for only those files need be included. If an `Entry' 622 request is sent without `Modified', `Is-modified', or `Unchanged', 623 it means the file is lost (does not exist in the working 624 directory). If both `Entry' and one of `Modified', `Is-modified', 625 or `Unchanged' are sent for the same file, `Entry' must be sent 626 first. For a given file, one can send `Modified', `Is-modified', 627 or `Unchanged', but not more than one of these three. 628 629`Kopt OPTION \n' 630 This indicates to the server which keyword expansion options to 631 use for the file specified by the next `Modified' or `Is-modified' 632 request (for example `-kb' for a binary file). This is similar to 633 `Entry', but is used for a file for which there is no entries line. 634 Typically this will be a file being added via an `add' or `import' 635 request. The client may not send both `Kopt' and `Entry' for the 636 same file. 637 638`Modified FILENAME \n' 639 Response expected: no. Additional data: mode, \n, file 640 transmission. Send the server a copy of one locally modified 641 file. FILENAME is relative to the most recent repository sent 642 with `Directory'. If the user is operating on only some files in 643 a directory, only those files need to be included. This can also 644 be sent without `Entry', if there is no entry for the file. 645 646`Is-modified FILENAME \n' 647 Response expected: no. Additional data: none. Like `Modified', 648 but used if the server only needs to know whether the file is 649 modified, not the contents. 650 651 The commands which can take `Is-modified' instead of `Modified' 652 with no known change in behavior are: `admin', `diff' (if and only 653 if two `-r' or `-D' options are specified), `watch-on', 654 `watch-off', `watch-add', `watch-remove', `watchers', `editors', 655 `log', and `annotate'. 656 657 For the `status' command, one can send `Is-modified' but if the 658 client is using imperfect mechanisms such as timestamps to 659 determine whether to consider a file modified, then the behavior 660 will be different. That is, if one sends `Modified', then the 661 server will actually compare the contents of the file sent and the 662 one it derives from to determine whether the file is genuinely 663 modified. But if one sends `Is-modified', then the server takes 664 the client's word for it. A similar situation exists for `tag', 665 if the `-c' option is specified. 666 667 Commands for which `Modified' is necessary are `co', `ci', 668 `update', and `import'. 669 670 Commands which do not need to inform the server about a working 671 directory, and thus should not be sending either `Modified' or 672 `Is-modified': `rdiff', `rtag', `history', `init', and `release'. 673 674 Commands for which further investigation is warranted are: 675 `remove', `add', and `export'. Pending such investigation, the 676 more conservative course of action is to stick to `Modified'. 677 678`Unchanged FILENAME \n' 679 Response expected: no. Tell the server that FILENAME has not been 680 modified in the checked out directory. The name is relative to 681 the most recent repository sent with `Directory'. 682 683`UseUnchanged \n' 684 Response expected: no. To specify the version of the protocol 685 described in this document, servers must support this request 686 (although it need not do anything) and clients must issue it. 687 688`Notify FILENAME \n' 689 Response expected: no. Tell the server that a `edit' or `unedit' 690 command has taken place. The server needs to send a `Notified' 691 response, but such response is deferred until the next time that 692 the server is sending responses. Response expected: no. 693 Additional data: 694 NOTIFICATION-TYPE \t TIME \t CLIENTHOST \t 695 WORKING-DIR \t WATCHES \n 696 where NOTIFICATION-TYPE is `E' for edit, `U' for unedit, undefined 697 behavior if `C', and all other letters should be silently ignored 698 for future expansion. TIME is the time at which the edit or 699 unedit took place, in a user-readable format of the client's 700 choice (the server should treat the time as an opaque string 701 rather than interpreting it). CLIENTHOST is the name of the host 702 on which the edit or unedit took place, and WORKING-DIR is the 703 pathname of the working directory where the edit or unedit took 704 place. WATCHES are the temporary watches to set. If WATCHES is 705 followed by \t then the \t and the rest of the line should be 706 ignored, for future expansion. 707 708 Note that a client may be capable of performing an `edit' or 709 `unedit' operation without connecting to the server at that time, 710 and instead connecting to the server when it is convenient (for 711 example, when a laptop is on the net again) to send the `Notify' 712 requests. Even if a client is capable of deferring notifications, 713 it should attempt to send them immediately (one can send `Notify' 714 requests together with a `noop' request, for example), unless 715 perhaps if it can know that a connection would be impossible. 716 717`Questionable FILENAME \n' 718 Response expected: no. Additional data: no. Tell the server to 719 check whether FILENAME should be ignored, and if not, next time the 720 server sends responses, send (in a `M' response) `?' followed by 721 the directory and filename. FILENAME must not contain `/'; it 722 needs to be a file in the directory named by the most recent 723 `Directory' request. 724 725`Case \n' 726 Response expected: no. Tell the server that filenames should be 727 matched in a case-insensitive fashion. Note that this is not the 728 primary mechanism for achieving case-insensitivity; for the most 729 part the client keeps track of the case which the server wants to 730 use and takes care to always use that case regardless of what the 731 user specifies. For example the filenames given in `Entry' and 732 `Modified' requests for the same file must match in case 733 regardless of whether the `Case' request is sent. The latter 734 mechanism is more general (it could also be used for 8.3 735 filenames, VMS filenames with more than one `.', and any other 736 situation in which there is a predictable mapping between 737 filenames in the working directory and filenames in the protocol), 738 but there are some situations it cannot handle (ignore patterns, or 739 situations where the user specifies a filename and the client does 740 not know about that file). 741 742`Argument TEXT \n' 743 Response expected: no. Save argument for use in a subsequent 744 command. Arguments accumulate until an argument-using command is 745 given, at which point they are forgotten. 746 747`Argumentx TEXT \n' 748 Response expected: no. Append \n followed by text to the current 749 argument being saved. 750 751`Global_option OPTION \n' 752 Response expected: no. Transmit one of the global options `-q', 753 `-Q', `-l', `-t', `-r', or `-n'. OPTION must be one of those 754 strings, no variations (such as combining of options) are allowed. 755 For graceful handling of `valid-requests', it is probably better 756 to make new global options separate requests, rather than trying 757 to add them to this request. 758 759`Gzip-stream LEVEL \n' 760 Response expected: no. Use zlib (RFC 1950/1951) compression to 761 compress all further communication between the client and the 762 server. After this request is sent, all further communication 763 must be compressed. All further data received from the server 764 will also be compressed. The LEVEL argument suggests to the 765 server the level of compression that it should apply; it should be 766 an integer between 1 and 9, inclusive, where a higher number 767 indicates more compression. 768 769`Kerberos-encrypt \n' 770 Response expected: no. Use Kerberos encryption to encrypt all 771 further communication between the client and the server. This 772 will only work if the connection was made over Kerberos in the 773 first place. If both the `Gzip-stream' and the `Kerberos-encrypt' 774 requests are used, the `Kerberos-encrypt' request should be used 775 first. This will make the client and server encrypt the 776 compressed data, as opposed to compressing the encrypted data. 777 Encrypted data is generally incompressible. 778 779 Note that this request does not fully prevent an attacker from 780 hijacking the connection, in the sense that it does not prevent 781 hijacking the connection between the initial authentication and the 782 `Kerberos-encrypt' request. 783 784`Gssapi-encrypt \n' 785 Response expected: no. Use GSSAPI encryption to encrypt all 786 further communication between the client and the server. This 787 will only work if the connection was made over GSSAPI in the first 788 place. See `Kerberos-encrypt', above, for the relation between 789 `Gssapi-encrypt' and `Gzip-stream'. 790 791 Note that this request does not fully prevent an attacker from 792 hijacking the connection, in the sense that it does not prevent 793 hijacking the connection between the initial authentication and the 794 `Gssapi-encrypt' request. 795 796`Gssapi-authenticate \n' 797 Response expected: no. Use GSSAPI authentication to authenticate 798 all further communication between the client and the server. This 799 will only work if the connection was made over GSSAPI in the first 800 place. Encrypted data is automatically authenticated, so using 801 both `Gssapi-authenticate' and `Gssapi-encrypt' has no effect 802 beyond that of `Gssapi-encrypt'. Unlike encrypted data, it is 803 reasonable to compress authenticated data. 804 805 Note that this request does not fully prevent an attacker from 806 hijacking the connection, in the sense that it does not prevent 807 hijacking the connection between the initial authentication and the 808 `Gssapi-authenticate' request. 809 810`Set VARIABLE=VALUE \n' 811 Response expected: no. Set a user variable VARIABLE to VALUE. 812 813`expand-modules \n' 814 Response expected: yes. Expand the modules which are specified in 815 the arguments. Returns the data in `Module-expansion' responses. 816 Note that the server can assume that this is checkout or export, 817 not rtag or rdiff; the latter do not access the working directory 818 and thus have no need to expand modules on the client side. 819 820 Expand may not be the best word for what this request does. It 821 does not necessarily tell you all the files contained in a module, 822 for example. Basically it is a way of telling you which working 823 directories the server needs to know about in order to handle a 824 checkout of the specified modules. 825 826 For example, suppose that the server has a module defined by 827 828 aliasmodule -a 1dir 829 830 That is, one can check out `aliasmodule' and it will take `1dir' 831 in the repository and check it out to `1dir' in the working 832 directory. Now suppose the client already has this module checked 833 out and is planning on using the `co' request to update it. 834 Without using `expand-modules', the client would have two bad 835 choices: it could either send information about *all* working 836 directories under the current directory, which could be 837 unnecessarily slow, or it could be ignorant of the fact that 838 `aliasmodule' stands for `1dir', and neglect to send information 839 for `1dir', which would lead to incorrect operation. 840 841 With `expand-modules', the client would first ask for the module to 842 be expanded: 843 844 C: Root /home/kingdon/zwork/cvsroot 845 . . . 846 C: Argument aliasmodule 847 C: Directory . 848 C: /home/kingdon/zwork/cvsroot 849 C: expand-modules 850 S: Module-expansion 1dir 851 S: ok 852 853 and then it knows to check the `1dir' directory and send requests 854 such as `Entry' and `Modified' for the files in that directory. 855 856`ci \n' 857`diff \n' 858`tag \n' 859`status \n' 860`log \n' 861`remove \n' 862`admin \n' 863`history \n' 864`watchers \n' 865`editors \n' 866`annotate \n' 867 Response expected: yes. Actually do a cvs command. This uses any 868 previous `Argument', `Directory', `Entry', or `Modified' requests, 869 if they have been sent. The last `Directory' sent specifies the 870 working directory at the time of the operation. No provision is 871 made for any input from the user. This means that `ci' must use a 872 `-m' argument if it wants to specify a log message. 873 874`co \n' 875 Response expected: yes. Get files from the repository. This uses 876 any previous `Argument', `Directory', `Entry', or `Modified' 877 requests, if they have been sent. Arguments to this command are 878 module names; the client cannot know what directories they 879 correspond to except by (1) just sending the `co' request, and then 880 seeing what directory names the server sends back in its 881 responses, and (2) the `expand-modules' request. 882 883`export \n' 884 Response expected: yes. Get files from the repository. This uses 885 any previous `Argument', `Directory', `Entry', or `Modified' 886 requests, if they have been sent. Arguments to this command are 887 module names, as described for the `co' request. The intention 888 behind this command is that a client can get sources from a server 889 without storing CVS information about those sources. That is, a 890 client probably should not count on being able to take the entries 891 line returned in the `Created' response from an `export' request 892 and send it in a future `Entry' request. Note that the entries 893 line in the `Created' response must indicate whether the file is 894 binary or text, so the client can create it correctly. 895 896`rdiff \n' 897`rtag \n' 898 Response expected: yes. Actually do a cvs command. This uses any 899 previous `Argument' requests, if they have been sent. The client 900 should not send `Directory', `Entry', or `Modified' requests for 901 this command; they are not used. Arguments to these commands are 902 module names, as described for `co'. 903 904`init ROOT-NAME \n' 905 Response expected: yes. If it doesn't already exist, create a CVS 906 repository ROOT-NAME. Note that ROOT-NAME is a local directory 907 and *not* a fully qualified `CVSROOT' variable. The `Root' 908 request need not have been previously sent. 909 910`update \n' 911 Response expected: yes. Actually do a `cvs update' command. This 912 uses any previous `Argument', `Directory', `Entry', or `Modified' 913 requests, if they have been sent. The last `Directory' sent 914 specifies the working directory at the time of the operation. The 915 `-I' option is not used-files which the client can decide whether 916 to ignore are not mentioned and the client sends the 917 `Questionable' request for others. 918 919`import \n' 920 Response expected: yes. Actually do a `cvs import' command. This 921 uses any previous `Argument', `Directory', `Entry', or `Modified' 922 requests, if they have been sent. The last `Directory' sent 923 specifies the working directory at the time of the operation. The 924 files to be imported are sent in `Modified' requests (files which 925 the client knows should be ignored are not sent; the server must 926 still process the CVSROOT/cvsignore file unless -I ! is sent). A 927 log message must have been specified with a `-m' argument. 928 929`add \n' 930 Response expected: yes. Add a file or directory. This uses any 931 previous `Argument', `Directory', `Entry', or `Modified' requests, 932 if they have been sent. The last `Directory' sent specifies the 933 working directory at the time of the operation. 934 935 To add a directory, send the directory to be added using 936 `Directory' and `Argument' requests. For example: 937 938 C: Root /u/cvsroot 939 . . . 940 C: Argument nsdir 941 C: Directory nsdir 942 C: /u/cvsroot/1dir/nsdir 943 C: Directory . 944 C: /u/cvsroot/1dir 945 C: add 946 S: M Directory /u/cvsroot/1dir/nsdir added to the repository 947 S: ok 948 949 You will notice that the server does not signal to the client in 950 any particular way that the directory has been successfully added. 951 The client is supposed to just assume that the directory has been 952 added and update its records accordingly. Note also that adding a 953 directory is immediate; it does not wait until a `ci' request as 954 files do. 955 956 To add a file, send the file to be added using a `Modified' 957 request. For example: 958 959 C: Argument nfile 960 C: Directory . 961 C: /u/cvsroot/1dir 962 C: Modified nfile 963 C: u=rw,g=r,o=r 964 C: 6 965 C: hello 966 C: add 967 S: E cvs server: scheduling file `nfile' for addition 968 S: Mode u=rw,g=r,o=r 969 S: Checked-in ./ 970 S: /u/cvsroot/1dir/nfile 971 S: /nfile/0/// 972 S: E cvs server: use 'cvs commit' to add this file permanently 973 S: ok 974 975 Note that the file has not been added to the repository; the only 976 effect of a successful `add' request, for a file, is to supply the 977 client with a new entries line containing `0' to indicate an added 978 file. In fact, the client probably could perform this operation 979 without contacting the server, although using `add' does cause the 980 server to perform a few more checks. 981 982 The client sends a subsequent `ci' to actually add the file to the 983 repository. 984 985 Another quirk of the `add' request is that with CVS 1.9 and older, 986 a pathname specified in an `Argument' request cannot contain `/'. 987 There is no good reason for this restriction, and in fact more 988 recent CVS servers don't have it. But the way to interoperate 989 with the older servers is to ensure that all `Directory' requests 990 for `add' (except those used to add directories, as described 991 above), use `.' for LOCAL-DIRECTORY. Specifying another string for 992 LOCAL-DIRECTORY may not get an error, but it will get you strange 993 `Checked-in' responses from the buggy servers. 994 995`watch-on \n' 996`watch-off \n' 997`watch-add \n' 998`watch-remove \n' 999 Response expected: yes. Actually do the `cvs watch on', `cvs 1000 watch off', `cvs watch add', and `cvs watch remove' commands, 1001 respectively. This uses any previous `Argument', `Directory', 1002 `Entry', or `Modified' requests, if they have been sent. The last 1003 `Directory' sent specifies the working directory at the time of 1004 the operation. 1005 1006`release \n' 1007 Response expected: yes. Note that a `cvs release' command has 1008 taken place and update the history file accordingly. 1009 1010`noop \n' 1011 Response expected: yes. This request is a null command in the 1012 sense that it doesn't do anything, but merely (as with any other 1013 requests expecting a response) sends back any responses pertaining 1014 to pending errors, pending `Notified' responses, etc. 1015 1016`update-patches \n' 1017 Response expected: yes. This request does not actually do 1018 anything. It is used as a signal that the server is able to 1019 generate patches when given an `update' request. The client must 1020 issue the `-u' argument to `update' in order to receive patches. 1021 1022`gzip-file-contents LEVEL \n' 1023 Response expected: no. Note that this request does not follow the 1024 response convention stated above. `Gzip-stream' is suggested 1025 instead of `gzip-file-contents' as it gives better compression; the 1026 only reason to implement the latter is to provide compression with 1027 CVS 1.8 and earlier. The `gzip-file-contents' request asks the 1028 server to compress files it sends to the client using `gzip' 1029 (RFC1952/1951) compression, using the specified level of 1030 compression. If this request is not made, the server must not 1031 compress files. 1032 1033 This is only a hint to the server. It may still decide (for 1034 example, in the case of very small files, or files that already 1035 appear to be compressed) not to do the compression. Compression 1036 is indicated by a `z' preceding the file length. 1037 1038 Availability of this request in the server indicates to the client 1039 that it may compress files sent to the server, regardless of 1040 whether the client actually uses this request. 1041 1042`wrapper-sendme-rcsOptions \n' 1043 Response expected: yes. Request that the server transmit mappings 1044 from filenames to keyword expansion modes in `Wrapper-rcsOption' 1045 responses. 1046 1047`OTHER-REQUEST TEXT \n' 1048 Response expected: yes. Any unrecognized request expects a 1049 response, and does not contain any additional data. The response 1050 will normally be something like `error unrecognized request', but 1051 it could be a different error if a previous command which doesn't 1052 expect a response produced an error. 1053 1054 When the client is done, it drops the connection. 1055 1056