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