1This is cvsclient.info, produced by makeinfo version 4.0 from 2cvsclient.texi. 3 4INFO-DIR-SECTION Programming 5START-INFO-DIR-ENTRY 6* cvsclient: (cvsclient). The CVS client/server protocol. 7END-INFO-DIR-ENTRY 8 9 10File: cvsclient.info, Node: Requests, Next: Response intro, Prev: Request intro, Up: Protocol 11 12Requests 13======== 14 15 Here are the requests: 16 17`Root PATHNAME \n' 18 Response expected: no. Tell the server which `CVSROOT' to use. 19 Note that PATHNAME is a local directory and _not_ a fully 20 qualified `CVSROOT' variable. PATHNAME must already exist; if 21 creating a new root, use the `init' request, not `Root'. PATHNAME 22 does not include the hostname of the server, how to access the 23 server, etc.; by the time the CVS protocol is in use, connection, 24 authentication, etc., are already taken care of. 25 26 The `Root' request must be sent only once, and it must be sent 27 before any requests other than `Valid-responses', 28 `valid-requests', `UseUnchanged', `Set', `Global_option', `init', 29 `noop', or `version'. 30 31`Valid-responses REQUEST-LIST \n' 32 Response expected: no. Tell the server what responses the client 33 will accept. request-list is a space separated list of tokens. 34 The `Root' request need not have been previously sent. 35 36`valid-requests \n' 37 Response expected: yes. Ask the server to send back a 38 `Valid-requests' response. The `Root' request need not have been 39 previously sent. 40 41`Directory LOCAL-DIRECTORY \n' 42 Additional data: REPOSITORY \n. Response expected: no. Tell the 43 server what directory to use. The REPOSITORY should be a 44 directory name from a previous server response. Note that this 45 both gives a default for `Entry' and `Modified' and also for `ci' 46 and the other commands; normal usage is to send `Directory' for 47 each directory in which there will be an `Entry' or `Modified', 48 and then a final `Directory' for the original directory, then the 49 command. The LOCAL-DIRECTORY is relative to the top level at 50 which the command is occurring (i.e. the last `Directory' which is 51 sent before the command); to indicate that top level, `.' should 52 be sent for LOCAL-DIRECTORY. 53 54 Here is an example of where a client gets REPOSITORY and 55 LOCAL-DIRECTORY. Suppose that there is a module defined by 56 57 moddir 1dir 58 59 That is, one can check out `moddir' and it will take `1dir' in the 60 repository and check it out to `moddir' in the working directory. 61 Then an initial check out could proceed like this: 62 63 C: Root /home/kingdon/zwork/cvsroot 64 . . . 65 C: Argument moddir 66 C: Directory . 67 C: /home/kingdon/zwork/cvsroot 68 C: co 69 S: Clear-sticky moddir/ 70 S: /home/kingdon/zwork/cvsroot/1dir/ 71 . . . 72 S: ok 73 74 In this example the response shown is `Clear-sticky', but it could 75 be another response instead. Note that it returns two pathnames. 76 The first one, `moddir/', indicates the working directory to check 77 out into. The second one, ending in `1dir/', indicates the 78 directory to pass back to the server in a subsequent `Directory' 79 request. For example, a subsequent `update' request might look 80 like: 81 82 C: Directory moddir 83 C: /home/kingdon/zwork/cvsroot/1dir 84 . . . 85 C: update 86 87 For a given LOCAL-DIRECTORY, the repository will be the same for 88 each of the responses, so one can use the repository from whichever 89 response is most convenient. Typically a client will store the 90 repository along with the sources for each LOCAL-DIRECTORY, use 91 that same setting whenever operating on that LOCAL-DIRECTORY, and 92 not update the setting as long as the LOCAL-DIRECTORY exists. 93 94 A client is free to rename a LOCAL-DIRECTORY at any time (for 95 example, in response to an explicit user request). While it is 96 true that the server supplies a LOCAL-DIRECTORY to the client, as 97 noted above, this is only the default place to put the directory. 98 Of course, the various `Directory' requests for a single command 99 (for example, `update' or `ci' request) should name a particular 100 directory with the same LOCAL-DIRECTORY. 101 102 Each `Directory' request specifies a brand-new LOCAL-DIRECTORY and 103 REPOSITORY; that is, LOCAL-DIRECTORY and REPOSITORY are never 104 relative to paths specified in any previous `Directory' request. 105 106 Here's a more complex example, in which we request an update of a 107 working directory which has been checked out from multiple places 108 in the repository. 109 110 C: Argument dir1 111 C: Directory dir1 112 C: /home/foo/repos/mod1 113 . . . 114 C: Argument dir2 115 C: Directory dir2 116 C: /home/foo/repos/mod2 117 . . . 118 C: Argument dir3 119 C: Directory dir3/subdir3 120 C: /home/foo/repos/mod3 121 . . . 122 C: update 123 124 While directories `dir1' and `dir2' will be handled in similar 125 fashion to the other examples given above, `dir3' is slightly 126 different from the server's standpoint. Notice that module `mod3' 127 is actually checked out into `dir3/subdir3', meaning that directory 128 `dir3' is either empty or does not contain data checked out from 129 this repository. 130 131 The above example will work correctly in CVS 1.10.1 and later. The 132 server will descend the tree starting from all directories 133 mentioned in `Argument' requests and update those directories 134 specifically mentioned in `Directory' requests. 135 136 Previous versions of CVS (1.10 and earlier) do not behave the same 137 way. While the descent of the tree begins at all directories 138 mentioned in `Argument' requests, descent into subdirectories only 139 occurs if a directory has been mentioned in a `Directory' request. 140 Therefore, the above example would succeed in updating `dir1' and 141 `dir2', but would skip `dir3' because that directory was not 142 specifically mentioned in a `Directory' request. A functional 143 version of the above that would run on a 1.10 or earlier server is 144 as follows: 145 146 C: Argument dir1 147 C: Directory dir1 148 C: /home/foo/repos/mod1 149 . . . 150 C: Argument dir2 151 C: Directory dir2 152 C: /home/foo/repos/mod2 153 . . . 154 C: Argument dir3 155 C: Directory dir3 156 C: /home/foo/repos/. 157 . . . 158 C: Directory dir3/subdir3 159 C: /home/foo/repos/mod3 160 . . . 161 C: update 162 163 Note the extra `Directory dir3' request. It might be better to use 164 `Emptydir' as the repository for the `dir3' directory, but the 165 above will certainly work. 166 167 One more peculiarity of the 1.10 and earlier protocol is the 168 ordering of `Directory' arguments. In order for a subdirectory to 169 be registered correctly for descent by the recursion processor, 170 its parent must be sent first. For example, the following would 171 not work to update `dir3/subdir3': 172 173 . . . 174 C: Argument dir3 175 C: Directory dir3/subdir3 176 C: /home/foo/repos/mod3 177 . . . 178 C: Directory dir3 179 C: /home/foo/repos/. 180 . . . 181 C: update 182 183 The implementation of the server in 1.10 and earlier writes the 184 administration files for a given directory at the time of the 185 `Directory' request. It also tries to register the directory with 186 its parent to mark it for recursion. In the above example, at the 187 time `dir3/subdir3' is created, the physical directory for `dir3' 188 will be created on disk, but the administration files will not 189 have been created. Therefore, when the server tries to register 190 `dir3/subdir3' for recursion, the operation will silently fail 191 because the administration files do not yet exist for `dir3'. 192 193`Max-dotdot LEVEL \n' 194 Response expected: no. Tell the server that LEVEL levels of 195 directories above the directory which `Directory' requests are 196 relative to will be needed. For example, if the client is 197 planning to use a `Directory' request for `../../foo', it must 198 send a `Max-dotdot' request with a LEVEL of at least 2. 199 `Max-dotdot' must be sent before the first `Directory' request. 200 201`Static-directory \n' 202 Response expected: no. Tell the server that the directory most 203 recently specified with `Directory' should not have additional 204 files checked out unless explicitly requested. The client sends 205 this if the `Entries.Static' flag is set, which is controlled by 206 the `Set-static-directory' and `Clear-static-directory' responses. 207 208`Sticky TAGSPEC \n' 209 Response expected: no. Tell the server that the directory most 210 recently specified with `Directory' has a sticky tag or date 211 TAGSPEC. The first character of TAGSPEC is `T' for a tag, `D' for 212 a date, or some other character supplied by a Set-sticky response 213 from a previous request to the server. The remainder of TAGSPEC 214 contains the actual tag or date, again as supplied by Set-sticky. 215 216 The server should remember `Static-directory' and `Sticky' 217 requests for a particular directory; the client need not resend 218 them each time it sends a `Directory' request for a given 219 directory. However, the server is not obliged to remember them 220 beyond the context of a single command. 221 222`Checkin-prog PROGRAM \n' 223 Response expected: no. Tell the server that the directory most 224 recently specified with `Directory' has a checkin program PROGRAM. 225 Such a program would have been previously set with the 226 `Set-checkin-prog' response. 227 228`Update-prog PROGRAM \n' 229 Response expected: no. Tell the server that the directory most 230 recently specified with `Directory' has an update program PROGRAM. 231 Such a program would have been previously set with the 232 `Set-update-prog' response. 233 234`Entry ENTRY-LINE \n' 235 Response expected: no. Tell the server what version of a file is 236 on the local machine. The name in ENTRY-LINE is a name relative 237 to the directory most recently specified with `Directory'. If the 238 user is operating on only some files in a directory, `Entry' 239 requests for only those files need be included. If an `Entry' 240 request is sent without `Modified', `Is-modified', or `Unchanged', 241 it means the file is lost (does not exist in the working 242 directory). If both `Entry' and one of `Modified', `Is-modified', 243 or `Unchanged' are sent for the same file, `Entry' must be sent 244 first. For a given file, one can send `Modified', `Is-modified', 245 or `Unchanged', but not more than one of these three. 246 247`Kopt OPTION \n' 248 This indicates to the server which keyword expansion options to 249 use for the file specified by the next `Modified' or `Is-modified' 250 request (for example `-kb' for a binary file). This is similar to 251 `Entry', but is used for a file for which there is no entries line. 252 Typically this will be a file being added via an `add' or `import' 253 request. The client may not send both `Kopt' and `Entry' for the 254 same file. 255 256`Checkin-time TIME \n' 257 For the file specified by the next `Modified' request, use TIME as 258 the time of the checkin. The TIME is in the format specified by 259 RFC822 as modified by RFC1123. The client may specify any 260 timezone it chooses; servers will want to convert that to their own 261 timezone as appropriate. An example of this format is: 262 263 26 May 1997 13:01:40 -0400 264 265 There is no requirement that the client and server clocks be 266 synchronized. The client just sends its recommendation for a 267 timestamp (based on file timestamps or whatever), and the server 268 should just believe it (this means that the time might be in the 269 future, for example). 270 271 Note that this is not a general-purpose way to tell the server 272 about the timestamp of a file; that would be a separate request 273 (if there are servers which can maintain timestamp and time of 274 checkin separately). 275 276 This request should affect the `import' request, and may optionally 277 affect the `ci' request or other relevant requests if any. 278 279`Modified FILENAME \n' 280 Response expected: no. Additional data: mode, \n, file 281 transmission. Send the server a copy of one locally modified 282 file. FILENAME is a file within the most recent directory sent 283 with `Directory'; it must not contain `/'. If the user is 284 operating on only some files in a directory, only those files need 285 to be included. This can also be sent without `Entry', if there 286 is no entry for the file. 287 288`Is-modified FILENAME \n' 289 Response expected: no. Additional data: none. Like `Modified', 290 but used if the server only needs to know whether the file is 291 modified, not the contents. 292 293 The commands which can take `Is-modified' instead of `Modified' 294 with no known change in behavior are: `admin', `diff' (if and only 295 if two `-r' or `-D' options are specified), `watch-on', 296 `watch-off', `watch-add', `watch-remove', `watchers', `editors', 297 `log', and `annotate'. 298 299 For the `status' command, one can send `Is-modified' but if the 300 client is using imperfect mechanisms such as timestamps to 301 determine whether to consider a file modified, then the behavior 302 will be different. That is, if one sends `Modified', then the 303 server will actually compare the contents of the file sent and the 304 one it derives from to determine whether the file is genuinely 305 modified. But if one sends `Is-modified', then the server takes 306 the client's word for it. A similar situation exists for `tag', 307 if the `-c' option is specified. 308 309 Commands for which `Modified' is necessary are `co', `ci', 310 `update', and `import'. 311 312 Commands which do not need to inform the server about a working 313 directory, and thus should not be sending either `Modified' or 314 `Is-modified': `rdiff', `rtag', `history', `init', and `release'. 315 316 Commands for which further investigation is warranted are: 317 `remove', `add', and `export'. Pending such investigation, the 318 more conservative course of action is to stick to `Modified'. 319 320`Unchanged FILENAME \n' 321 Response expected: no. Tell the server that FILENAME has not been 322 modified in the checked out directory. The FILENAME is a file 323 within the most recent directory sent with `Directory'; it must 324 not contain `/'. 325 326`UseUnchanged \n' 327 Response expected: no. To specify the version of the protocol 328 described in this document, servers must support this request 329 (although it need not do anything) and clients must issue it. The 330 `Root' request need not have been previously sent. 331 332`Notify FILENAME \n' 333 Response expected: no. Tell the server that an `edit' or `unedit' 334 command has taken place. The server needs to send a `Notified' 335 response, but such response is deferred until the next time that 336 the server is sending responses. The FILENAME is a file within 337 the most recent directory sent with `Directory'; it must not 338 contain `/'. Additional data: 339 NOTIFICATION-TYPE \t TIME \t CLIENTHOST \t 340 WORKING-DIR \t WATCHES \n 341 where NOTIFICATION-TYPE is `E' for edit, `U' for unedit, undefined 342 behavior if `C', and all other letters should be silently ignored 343 for future expansion. TIME is the time at which the edit or 344 unedit took place, in a user-readable format of the client's 345 choice (the server should treat the time as an opaque string 346 rather than interpreting it). CLIENTHOST is the name of the host 347 on which the edit or unedit took place, and WORKING-DIR is the 348 pathname of the working directory where the edit or unedit took 349 place. WATCHES are the temporary watches, zero or more of the 350 following characters in the following order: `E' for edit, `U' for 351 unedit, `C' for commit, and all other letters should be silently 352 ignored for future expansion. If NOTIFICATION-TYPE is `E' the 353 temporary watches are set; if it is `U' they are cleared. If 354 WATCHES is followed by \t then the \t and the rest of the line 355 should be ignored, for future expansion. 356 357 The TIME, CLIENTHOST, and WORKING-DIR fields may not contain the 358 characters `+', `,', `>', `;', or `='. 359 360 Note that a client may be capable of performing an `edit' or 361 `unedit' operation without connecting to the server at that time, 362 and instead connecting to the server when it is convenient (for 363 example, when a laptop is on the net again) to send the `Notify' 364 requests. Even if a client is capable of deferring notifications, 365 it should attempt to send them immediately (one can send `Notify' 366 requests together with a `noop' request, for example), unless 367 perhaps if it can know that a connection would be impossible. 368 369`Questionable FILENAME \n' 370 Response expected: no. Additional data: no. Tell the server to 371 check whether FILENAME should be ignored, and if not, next time the 372 server sends responses, send (in a `M' response) `?' followed by 373 the directory and filename. FILENAME must not contain `/'; it 374 needs to be a file in the directory named by the most recent 375 `Directory' request. 376 377`Case \n' 378 Response expected: no. Tell the server that filenames should be 379 matched in a case-insensitive fashion. Note that this is not the 380 primary mechanism for achieving case-insensitivity; for the most 381 part the client keeps track of the case which the server wants to 382 use and takes care to always use that case regardless of what the 383 user specifies. For example the filenames given in `Entry' and 384 `Modified' requests for the same file must match in case 385 regardless of whether the `Case' request is sent. The latter 386 mechanism is more general (it could also be used for 8.3 387 filenames, VMS filenames with more than one `.', and any other 388 situation in which there is a predictable mapping between 389 filenames in the working directory and filenames in the protocol), 390 but there are some situations it cannot handle (ignore patterns, or 391 situations where the user specifies a filename and the client does 392 not know about that file). 393 394`Argument TEXT \n' 395 Response expected: no. Save argument for use in a subsequent 396 command. Arguments accumulate until an argument-using command is 397 given, at which point they are forgotten. 398 399`Argumentx TEXT \n' 400 Response expected: no. Append \n followed by text to the current 401 argument being saved. 402 403`Global_option OPTION \n' 404 Response expected: no. Transmit one of the global options `-q', 405 `-Q', `-l', `-t', `-r', or `-n'. OPTION must be one of those 406 strings, no variations (such as combining of options) are allowed. 407 For graceful handling of `valid-requests', it is probably better 408 to make new global options separate requests, rather than trying 409 to add them to this request. The `Root' request need not have 410 been previously sent. 411 412`Gzip-stream LEVEL \n' 413 Response expected: no. Use zlib (RFC 1950/1951) compression to 414 compress all further communication between the client and the 415 server. After this request is sent, all further communication 416 must be compressed. All further data received from the server 417 will also be compressed. The LEVEL argument suggests to the 418 server the level of compression that it should apply; it should be 419 an integer between 1 and 9, inclusive, where a higher number 420 indicates more compression. 421 422`Kerberos-encrypt \n' 423 Response expected: no. Use Kerberos encryption to encrypt all 424 further communication between the client and the server. This 425 will only work if the connection was made over Kerberos in the 426 first place. If both the `Gzip-stream' and the `Kerberos-encrypt' 427 requests are used, the `Kerberos-encrypt' request should be used 428 first. This will make the client and server encrypt the 429 compressed data, as opposed to compressing the encrypted data. 430 Encrypted data is generally incompressible. 431 432 Note that this request does not fully prevent an attacker from 433 hijacking the connection, in the sense that it does not prevent 434 hijacking the connection between the initial authentication and the 435 `Kerberos-encrypt' request. 436 437`Gssapi-encrypt \n' 438 Response expected: no. Use GSSAPI encryption to encrypt all 439 further communication between the client and the server. This 440 will only work if the connection was made over GSSAPI in the first 441 place. See `Kerberos-encrypt', above, for the relation between 442 `Gssapi-encrypt' and `Gzip-stream'. 443 444 Note that this request does not fully prevent an attacker from 445 hijacking the connection, in the sense that it does not prevent 446 hijacking the connection between the initial authentication and the 447 `Gssapi-encrypt' request. 448 449`Gssapi-authenticate \n' 450 Response expected: no. Use GSSAPI authentication to authenticate 451 all further communication between the client and the server. This 452 will only work if the connection was made over GSSAPI in the first 453 place. Encrypted data is automatically authenticated, so using 454 both `Gssapi-authenticate' and `Gssapi-encrypt' has no effect 455 beyond that of `Gssapi-encrypt'. Unlike encrypted data, it is 456 reasonable to compress authenticated data. 457 458 Note that this request does not fully prevent an attacker from 459 hijacking the connection, in the sense that it does not prevent 460 hijacking the connection between the initial authentication and the 461 `Gssapi-authenticate' request. 462 463`Set VARIABLE=VALUE \n' 464 Response expected: no. Set a user variable VARIABLE to VALUE. 465 The `Root' request need not have been previously sent. 466 467`expand-modules \n' 468 Response expected: yes. Expand the modules which are specified in 469 the arguments. Returns the data in `Module-expansion' responses. 470 Note that the server can assume that this is checkout or export, 471 not rtag or rdiff; the latter do not access the working directory 472 and thus have no need to expand modules on the client side. 473 474 Expand may not be the best word for what this request does. It 475 does not necessarily tell you all the files contained in a module, 476 for example. Basically it is a way of telling you which working 477 directories the server needs to know about in order to handle a 478 checkout of the specified modules. 479 480 For example, suppose that the server has a module defined by 481 482 aliasmodule -a 1dir 483 484 That is, one can check out `aliasmodule' and it will take `1dir' 485 in the repository and check it out to `1dir' in the working 486 directory. Now suppose the client already has this module checked 487 out and is planning on using the `co' request to update it. 488 Without using `expand-modules', the client would have two bad 489 choices: it could either send information about _all_ working 490 directories under the current directory, which could be 491 unnecessarily slow, or it could be ignorant of the fact that 492 `aliasmodule' stands for `1dir', and neglect to send information 493 for `1dir', which would lead to incorrect operation. 494 495 With `expand-modules', the client would first ask for the module to 496 be expanded: 497 498 C: Root /home/kingdon/zwork/cvsroot 499 . . . 500 C: Argument aliasmodule 501 C: Directory . 502 C: /home/kingdon/zwork/cvsroot 503 C: expand-modules 504 S: Module-expansion 1dir 505 S: ok 506 507 and then it knows to check the `1dir' directory and send requests 508 such as `Entry' and `Modified' for the files in that directory. 509 510`ci \n' 511`diff \n' 512`tag \n' 513`status \n' 514`admin \n' 515`history \n' 516`watchers \n' 517`editors \n' 518`annotate \n' 519 Response expected: yes. Actually do a cvs command. This uses any 520 previous `Argument', `Directory', `Entry', or `Modified' requests, 521 if they have been sent. The last `Directory' sent specifies the 522 working directory at the time of the operation. No provision is 523 made for any input from the user. This means that `ci' must use a 524 `-m' argument if it wants to specify a log message. 525 526`log \n' 527 Response expected: yes. Show information for past revisions. 528 This uses any previous `Directory', `Entry', or `Modified' 529 requests, if they have been sent. The last `Directory' sent 530 specifies the working directory at the time of the operation. 531 Also uses previous `Argument''s of which the canonical forms are 532 the following (CVS 1.10 and older clients sent what the user 533 specified, but clients are encouraged to use the canonical forms 534 and other forms are deprecated): 535 536 `-b, -h, -l, -N, -R, -t' 537 These options go by themselves, one option per `Argument' 538 request. 539 540 `-d DATE1<DATE2' 541 Select revisions between DATE1 and DATE2. Either date may be 542 omitted in which case there is no date limit at that end of 543 the range (clients may specify dates such as 1 Jan 1970 or 1 544 Jan 2038 for similar purposes but this is problematic as it 545 makes assumptions about what dates the server supports). 546 Dates are in RFC822/1123 format. The `-d' is one `Argument' 547 request and the date range is a second one. 548 549 `-d DATE1<=DATE2' 550 Likewise but compare dates for equality. 551 552 `-d SINGLEDATE' 553 Select the single, latest revision dated SINGLEDATE or 554 earlier. 555 556 To include several date ranges and/or singledates, repeat the 557 `-d' option as many times as necessary. 558 559 `-rREV1:REV2' 560 `-rBRANCH' 561 `-rBRANCH.' 562 `-r' 563 Specify revisions (note that REV1 or REV2 can be omitted, or 564 can refer to branches). Send both the `-r' and the revision 565 information in a single `Argument' request. To include 566 several revision selections, repeat the `-r' option. 567 568 `-s STATE' 569 `-w' 570 `-wLOGIN' 571 Select on states or users. To include more than one state or 572 user, repeat the option. Send the `-s' option as a separate 573 argument from the state being selected. Send the `-w' option 574 as part of the same argument as the user being selected. 575 576`co \n' 577 Response expected: yes. Get files from the repository. This uses 578 any previous `Argument', `Directory', `Entry', or `Modified' 579 requests, if they have been sent. Arguments to this command are 580 module names; the client cannot know what directories they 581 correspond to except by (1) just sending the `co' request, and then 582 seeing what directory names the server sends back in its 583 responses, and (2) the `expand-modules' request. 584 585`export \n' 586 Response expected: yes. Get files from the repository. This uses 587 any previous `Argument', `Directory', `Entry', or `Modified' 588 requests, if they have been sent. Arguments to this command are 589 module names, as described for the `co' request. The intention 590 behind this command is that a client can get sources from a server 591 without storing CVS information about those sources. That is, a 592 client probably should not count on being able to take the entries 593 line returned in the `Created' response from an `export' request 594 and send it in a future `Entry' request. Note that the entries 595 line in the `Created' response must indicate whether the file is 596 binary or text, so the client can create it correctly. 597 598`rannotate \n' 599`rdiff \n' 600`rlog \n' 601`rtag \n' 602 Response expected: yes. Actually do a cvs command. This uses any 603 previous `Argument' requests, if they have been sent. The client 604 should not send `Directory', `Entry', or `Modified' requests for 605 these commands; they are not used. Arguments to these commands 606 are module names, as described for `co'. 607 608`init ROOT-NAME \n' 609 Response expected: yes. If it doesn't already exist, create a CVS 610 repository ROOT-NAME. Note that ROOT-NAME is a local directory 611 and _not_ a fully qualified `CVSROOT' variable. The `Root' 612 request need not have been previously sent. 613 614`update \n' 615 Response expected: yes. Actually do a `cvs update' command. This 616 uses any previous `Argument', `Directory', `Entry', or `Modified' 617 requests, if they have been sent. The last `Directory' sent 618 specifies the working directory at the time of the operation. The 619 `-I' option is not used-files which the client can decide whether 620 to ignore are not mentioned and the client sends the 621 `Questionable' request for others. 622 623`import \n' 624 Response expected: yes. Actually do a `cvs import' command. This 625 uses any previous `Argument', `Directory', `Entry', or `Modified' 626 requests, if they have been sent. The last `Directory' sent 627 specifies the working directory at the time of the operation - 628 unlike most commands, the repository field of each `Directory' 629 request is ignored (it merely must point somewhere within the 630 root). The files to be imported are sent in `Modified' requests 631 (files which the client knows should be ignored are not sent; the 632 server must still process the CVSROOT/cvsignore file unless -I ! is 633 sent). A log message must have been specified with a `-m' 634 argument. 635 636`add \n' 637 Response expected: yes. Add a file or directory. This uses any 638 previous `Argument', `Directory', `Entry', or `Modified' requests, 639 if they have been sent. The last `Directory' sent specifies the 640 working directory at the time of the operation. 641 642 To add a directory, send the directory to be added using 643 `Directory' and `Argument' requests. For example: 644 645 C: Root /u/cvsroot 646 . . . 647 C: Argument nsdir 648 C: Directory nsdir 649 C: /u/cvsroot/1dir/nsdir 650 C: Directory . 651 C: /u/cvsroot/1dir 652 C: add 653 S: M Directory /u/cvsroot/1dir/nsdir added to the repository 654 S: ok 655 656 You will notice that the server does not signal to the client in 657 any particular way that the directory has been successfully added. 658 The client is supposed to just assume that the directory has been 659 added and update its records accordingly. Note also that adding a 660 directory is immediate; it does not wait until a `ci' request as 661 files do. 662 663 To add a file, send the file to be added using a `Modified' 664 request. For example: 665 666 C: Argument nfile 667 C: Directory . 668 C: /u/cvsroot/1dir 669 C: Modified nfile 670 C: u=rw,g=r,o=r 671 C: 6 672 C: hello 673 C: add 674 S: E cvs server: scheduling file `nfile' for addition 675 S: Mode u=rw,g=r,o=r 676 S: Checked-in ./ 677 S: /u/cvsroot/1dir/nfile 678 S: /nfile/0/// 679 S: E cvs server: use 'cvs commit' to add this file permanently 680 S: ok 681 682 Note that the file has not been added to the repository; the only 683 effect of a successful `add' request, for a file, is to supply the 684 client with a new entries line containing `0' to indicate an added 685 file. In fact, the client probably could perform this operation 686 without contacting the server, although using `add' does cause the 687 server to perform a few more checks. 688 689 The client sends a subsequent `ci' to actually add the file to the 690 repository. 691 692 Another quirk of the `add' request is that with CVS 1.9 and older, 693 a pathname specified in an `Argument' request cannot contain `/'. 694 There is no good reason for this restriction, and in fact more 695 recent CVS servers don't have it. But the way to interoperate 696 with the older servers is to ensure that all `Directory' requests 697 for `add' (except those used to add directories, as described 698 above), use `.' for LOCAL-DIRECTORY. Specifying another string for 699 LOCAL-DIRECTORY may not get an error, but it will get you strange 700 `Checked-in' responses from the buggy servers. 701 702`remove \n' 703 Response expected: yes. Remove a file. This uses any previous 704 `Argument', `Directory', `Entry', or `Modified' requests, if they 705 have been sent. The last `Directory' sent specifies the working 706 directory at the time of the operation. 707 708 Note that this request does not actually do anything to the 709 repository; the only effect of a successful `remove' request is to 710 supply the client with a new entries line containing `-' to 711 indicate a removed file. In fact, the client probably could 712 perform this operation without contacting the server, although 713 using `remove' may cause the server to perform a few more checks. 714 715 The client sends a subsequent `ci' request to actually record the 716 removal in the repository. 717 718`watch-on \n' 719`watch-off \n' 720`watch-add \n' 721`watch-remove \n' 722 Response expected: yes. Actually do the `cvs watch on', `cvs 723 watch off', `cvs watch add', and `cvs watch remove' commands, 724 respectively. This uses any previous `Argument', `Directory', 725 `Entry', or `Modified' requests, if they have been sent. The last 726 `Directory' sent specifies the working directory at the time of 727 the operation. 728 729`release \n' 730 Response expected: yes. Note that a `cvs release' command has 731 taken place and update the history file accordingly. 732 733`noop \n' 734 Response expected: yes. This request is a null command in the 735 sense that it doesn't do anything, but merely (as with any other 736 requests expecting a response) sends back any responses pertaining 737 to pending errors, pending `Notified' responses, etc. The `Root' 738 request need not have been previously sent. 739 740`update-patches \n' 741 Response expected: yes. This request does not actually do 742 anything. It is used as a signal that the server is able to 743 generate patches when given an `update' request. The client must 744 issue the `-u' argument to `update' in order to receive patches. 745 746`gzip-file-contents LEVEL \n' 747 Response expected: no. Note that this request does not follow the 748 response convention stated above. `Gzip-stream' is suggested 749 instead of `gzip-file-contents' as it gives better compression; the 750 only reason to implement the latter is to provide compression with 751 CVS 1.8 and earlier. The `gzip-file-contents' request asks the 752 server to compress files it sends to the client using `gzip' 753 (RFC1952/1951) compression, using the specified level of 754 compression. If this request is not made, the server must not 755 compress files. 756 757 This is only a hint to the server. It may still decide (for 758 example, in the case of very small files, or files that already 759 appear to be compressed) not to do the compression. Compression 760 is indicated by a `z' preceding the file length. 761 762 Availability of this request in the server indicates to the client 763 that it may compress files sent to the server, regardless of 764 whether the client actually uses this request. 765 766`wrapper-sendme-rcsOptions \n' 767 Response expected: yes. Request that the server transmit mappings 768 from filenames to keyword expansion modes in `Wrapper-rcsOption' 769 responses. 770 771`version \n' 772 Response expected: yes. Request that the server transmit its 773 version message. The `Root' request need not have been previously 774 sent. 775 776`OTHER-REQUEST TEXT \n' 777 Response expected: yes. Any unrecognized request expects a 778 response, and does not contain any additional data. The response 779 will normally be something like `error unrecognized request', but 780 it could be a different error if a previous request which doesn't 781 expect a response produced an error. 782 783 When the client is done, it drops the connection. 784 785 786File: cvsclient.info, Node: Response intro, Next: Response pathnames, Prev: Requests, Up: Protocol 787 788Introduction to Responses 789========================= 790 791 After a command which expects a response, the server sends however 792many of the following responses are appropriate. The server should not 793send data at other times (the current implementation may violate this 794principle in a few minor places, where the server is printing an error 795message and exiting--this should be investigated further). 796 797 Any set of responses always ends with `error' or `ok'. This 798indicates that the response is over. 799 800 The responses `Checked-in', `New-entry', `Updated', `Created', 801`Update-existing', `Merged', and `Patched' are refered to as "file 802updating" responses, because they change the status of a file in the 803working directory in some way. The responses `Mode', `Mod-time', and 804`Checksum' are referred to as "file update modifying" responses because 805they modify the next file updating response. In no case shall a file 806update modifying response apply to a file updating response other than 807the next one. Nor can the same file update modifying response occur 808twice for a given file updating response (if servers diagnose this 809problem, it may aid in detecting the case where clients send an update 810modifying response without following it by a file updating response). 811 812 813File: cvsclient.info, Node: Response pathnames, Next: Responses, Prev: Response intro, Up: Protocol 814 815The "pathname" in responses 816=========================== 817 818 Many of the responses contain something called PATHNAME. The name 819is somewhat misleading; it actually indicates a pair of pathnames. 820First, a local directory name relative to the directory in which the 821command was given (i.e. the last `Directory' before the command). Then 822a linefeed and a repository name. Then a slash and the filename 823(without a `,v' ending). For example, for a file `i386.mh' which is in 824the local directory `gas.clean/config' and for which the repository is 825`/rel/cvsfiles/devo/gas/config': 826 827 gas.clean/config/ 828 /rel/cvsfiles/devo/gas/config/i386.mh 829 830 If the server wants to tell the client to create a directory, then it 831merely uses the directory in any response, as described above, and the 832client should create the directory if it does not exist. Note that this 833should only be done one directory at a time, in order to permit the 834client to correctly store the repository for each directory. Servers 835can use requests such as `Clear-sticky', `Clear-static-directory', or 836any other requests, to create directories. 837 838 Some server implementations may poorly distinguish between a 839directory which should not exist and a directory which contains no 840files; in order to refrain from creating empty directories a client 841should both send the `-P' option to `update' or `co', and should also 842detect the case in which the server asks to create a directory but not 843any files within it (in that case the client should remove the 844directory or refrain from creating it in the first place). Note that 845servers could clean this up greatly by only telling the client to 846create directories if the directory in question should exist, but until 847servers do this, clients will need to offer the `-P' behavior described 848above. 849 850