1\input texinfo @c -*- texinfo -*- 2 3@setfilename cvsclient.info 4@include CVSvn.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{CVSVN} 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{CVSVN} 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 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 reponse, 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 a local directory and @emph{not} a fully 539qualified @code{CVSROOT} variable. @var{pathname} must 540already exist; if creating a new root, use the @code{init} request, not 541@code{Root}. @var{pathname} does not include the hostname of the 542server, how to access the server, etc.; by the time the CVS protocol is 543in use, connection, authentication, etc., are already 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{init}, @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 Checkin-prog @var{program} \n 761Response expected: no. Tell the server that the directory most recently 762specified with @code{Directory} has a checkin program @var{program}. 763Such a program would have been previously set with the 764@code{Set-checkin-prog} response. 765 766@item Update-prog @var{program} \n 767Response expected: no. Tell the server that the directory most recently 768specified with @code{Directory} has an update program @var{program}. 769Such a program would have been previously set with the 770@code{Set-update-prog} response. 771 772@item Entry @var{entry-line} \n 773Response expected: no. Tell the server what version of a file is on the 774local machine. The name in @var{entry-line} is a name relative to the 775directory most recently specified with @code{Directory}. If the user 776is operating on only some files in a directory, @code{Entry} requests 777for only those files need be included. If an @code{Entry} request is 778sent without @code{Modified}, @code{Is-modified}, or @code{Unchanged}, 779it means the file is 780lost (does not exist in the working directory). If both @code{Entry} 781and one of @code{Modified}, @code{Is-modified}, or @code{Unchanged} are 782sent for the same file, @code{Entry} must be sent first. For a 783given file, one can send @code{Modified}, @code{Is-modified}, or 784@code{Unchanged}, but not more than one of these three. 785 786@item Kopt @var{option} \n 787This indicates to the server which keyword expansion options to use for 788the file specified by the next @code{Modified} or @code{Is-modified} 789request (for example @samp{-kb} for a binary file). This is similar to 790@code{Entry}, but is used for a file for which there is no entries line. 791Typically this will be a file being added via an @code{add} or 792@code{import} request. The client may not send both @code{Kopt} and 793@code{Entry} for the same file. 794 795@item Checkin-time @var{time} \n 796For the file specified by the next @code{Modified} request, use 797@var{time} as the time of the checkin. The @var{time} is in the format 798specified by RFC822 as modified by RFC1123. The client may specify any 799timezone it chooses; servers will want to convert that to their own 800timezone as appropriate. An example of this format is: 801 802@example 80326 May 1997 13:01:40 -0400 804@end example 805 806There is no requirement that the client and server clocks be 807synchronized. The client just sends its recommendation for a timestamp 808(based on file timestamps or whatever), and the server should just believe 809it (this means that the time might be in the future, for example). 810 811Note that this is not a general-purpose way to tell the server about the 812timestamp of a file; that would be a separate request (if there are 813servers which can maintain timestamp and time of checkin separately). 814 815This request should affect the @code{import} request, and may optionally 816affect the @code{ci} request or other relevant requests if any. 817 818@item Modified @var{filename} \n 819Response expected: no. Additional data: mode, \n, file transmission. 820Send the server a copy of one locally modified file. @var{filename} is 821a file within the most recent directory sent with @code{Directory}; it 822must not contain @samp{/}. If 823the user is operating on only some files in a directory, only those 824files need to be included. This can also be sent without @code{Entry}, 825if there is no entry for the file. 826 827@item Is-modified @var{filename} \n 828Response expected: no. Additional data: none. Like @code{Modified}, 829but used if the server only needs 830to know whether the file is modified, not the contents. 831 832The commands which can take @code{Is-modified} instead of 833@code{Modified} with no known change in behavior are: @code{admin}, 834@code{diff} (if and only if two @samp{-r} or @samp{-D} options are 835specified), @code{watch-on}, @code{watch-off}, @code{watch-add}, 836@code{watch-remove}, @code{watchers}, @code{editors}, 837@code{log}, and @code{annotate}. 838 839For the @code{status} command, one can send @code{Is-modified} but if 840the client is using imperfect mechanisms such as timestamps to determine 841whether to consider a file modified, then the behavior will be 842different. That is, if one sends @code{Modified}, then the server will 843actually compare the contents of the file sent and the one it derives 844from to determine whether the file is genuinely modified. But if one 845sends @code{Is-modified}, then the server takes the client's word for 846it. A similar situation exists for @code{tag}, if the @samp{-c} option 847is specified. 848 849Commands for which @code{Modified} is necessary are @code{co}, 850@code{ci}, @code{update}, and @code{import}. 851 852Commands which do not need to inform the server about a working 853directory, and thus should not be sending either @code{Modified} or 854@code{Is-modified}: @code{rdiff}, @code{rtag}, @code{history}, 855@code{init}, and @code{release}. 856 857Commands for which further investigation is warranted are: 858@code{remove}, @code{add}, and @code{export}. Pending such 859investigation, the more conservative course of action is to stick to 860@code{Modified}. 861 862@item Unchanged @var{filename} \n 863Response expected: no. Tell the server that @var{filename} has not been 864modified in the checked out directory. The @var{filename} is 865a file within the most recent directory sent with @code{Directory}; it 866must not contain @samp{/}. 867 868@item UseUnchanged \n 869Response expected: no. To specify the version of the protocol described 870in this document, servers must support this request (although it need 871not do anything) and clients must issue it. 872The @code{Root} request need not have been previously sent. 873 874@item Notify @var{filename} \n 875Response expected: no. 876Tell the server that an @code{edit} or @code{unedit} command has taken 877place. The server needs to send a @code{Notified} response, but such 878response is deferred until the next time that the server is sending 879responses. 880The @var{filename} is a file within the most recent directory sent with 881@code{Directory}; it must not contain @samp{/}. 882Additional data: 883@example 884@var{notification-type} \t @var{time} \t @var{clienthost} \t 885@var{working-dir} \t @var{watches} \n 886@end example 887where @var{notification-type} is @samp{E} for edit, @samp{U} for 888unedit, undefined behavior if @samp{C}, and all other letters should be 889silently ignored for future expansion. 890@var{time} is the time at which the edit or unedit took place, in a 891user-readable format of the client's choice (the server should treat the 892time as an opaque string rather than interpreting it). 893@c Might be useful to specify a format, but I don't know if we want to 894@c specify the status quo (ISO C asctime() format plus timezone) without 895@c offering the option of ISO8601 and/or RFC822/1123 (see cvs.texinfo 896@c for much much more on date formats). 897@var{clienthost} is the name of the host on which the edit or unedit 898took place, and @var{working-dir} is the pathname of the working 899directory where the edit or unedit took place. @var{watches} are the 900temporary watches, zero or more of the following characters in the 901following order: @samp{E} for edit, @samp{U} for unedit, @samp{C} for 902commit, and all other letters should be silently ignored for future 903expansion. If @var{notification-type} is @samp{E} the temporary watches 904are set; if it is @samp{U} they are cleared. 905If @var{watches} is followed by \t then the 906\t and the rest of the line should be ignored, for future expansion. 907 908The @var{time}, @var{clienthost}, and @var{working-dir} fields may not 909contain the characters @samp{+}, @samp{,}, @samp{>}, @samp{;}, or @samp{=}. 910 911Note that a client may be capable of performing an @code{edit} or 912@code{unedit} operation without connecting to the server at that time, 913and instead connecting to the server when it is convenient (for example, 914when a laptop is on the net again) to send the @code{Notify} requests. 915Even if a client is capable of deferring notifications, it should 916attempt to send them immediately (one can send @code{Notify} requests 917together with a @code{noop} request, for example), unless perhaps if 918it can know that a connection would be impossible. 919 920@item Questionable @var{filename} \n 921Response expected: no. Additional data: no. Tell the server to check 922whether @var{filename} should be ignored, and if not, next time the 923server sends responses, send (in a @code{M} response) @samp{?} followed 924by the directory and filename. @var{filename} must not contain 925@samp{/}; it needs to be a file in the directory named by the most 926recent @code{Directory} request. 927@c FIXME: the bit about not containing / is true of most of the 928@c requests, but isn't documented and should be. 929 930@item Case \n 931Response expected: no. Tell the server that filenames should be matched 932in a case-insensitive fashion. Note that this is not the primary 933mechanism for achieving case-insensitivity; for the most part the client 934keeps track of the case which the server wants to use and takes care to 935always use that case regardless of what the user specifies. For example 936the filenames given in @code{Entry} and @code{Modified} requests for the 937same file must match in case regardless of whether the @code{Case} 938request is sent. The latter mechanism is more general (it could also be 939used for 8.3 filenames, VMS filenames with more than one @samp{.}, and 940any other situation in which there is a predictable mapping between 941filenames in the working directory and filenames in the protocol), but 942there are some situations it cannot handle (ignore patterns, or 943situations where the user specifies a filename and the client does not 944know about that file). 945 946@item Argument @var{text} \n 947Response expected: no. 948Save argument for use in a subsequent command. Arguments 949accumulate until an argument-using command is given, at which point 950they are forgotten. 951 952@item Argumentx @var{text} \n 953Response expected: no. Append \n followed by text to the current 954argument being saved. 955 956@item Global_option @var{option} \n 957Response expected: no. 958Transmit one of the global options @samp{-q}, @samp{-Q}, @samp{-l}, 959@samp{-t}, @samp{-r}, or @samp{-n}. @var{option} must be one of those 960strings, no variations (such as combining of options) are allowed. For 961graceful handling of @code{valid-requests}, it is probably better to 962make new global options separate requests, rather than trying to add 963them to this request. 964The @code{Root} request need not have been previously sent. 965 966@item Gzip-stream @var{level} \n 967Response expected: no. 968Use zlib (RFC 1950/1951) compression to compress all further communication 969between the client and the server. After this request is sent, all 970further communication must be compressed. All further data received 971from the server will also be compressed. The @var{level} argument 972suggests to the server the level of compression that it should apply; it 973should be an integer between 1 and 9, inclusive, where a higher number 974indicates more compression. 975 976@item Kerberos-encrypt \n 977Response expected: no. 978Use Kerberos encryption to encrypt all further communication between the 979client and the server. This will only work if the connection was made 980over Kerberos in the first place. If both the @code{Gzip-stream} and 981the @code{Kerberos-encrypt} requests are used, the 982@code{Kerberos-encrypt} request should be used first. This will make 983the client and server encrypt the compressed data, as opposed to 984compressing the encrypted data. Encrypted data is generally 985incompressible. 986 987Note that this request does not fully prevent an attacker from hijacking 988the connection, in the sense that it does not prevent hijacking the 989connection between the initial authentication and the 990@code{Kerberos-encrypt} request. 991 992@item Gssapi-encrypt \n 993Response expected: no. 994Use GSSAPI encryption to encrypt all further communication between the 995client and the server. This will only work if the connection was made 996over GSSAPI in the first place. See @code{Kerberos-encrypt}, above, for 997the relation between @code{Gssapi-encrypt} and @code{Gzip-stream}. 998 999Note that this request does not fully prevent an attacker from hijacking 1000the connection, in the sense that it does not prevent hijacking the 1001connection between the initial authentication and the 1002@code{Gssapi-encrypt} request. 1003 1004@item Gssapi-authenticate \n 1005Response expected: no. 1006Use GSSAPI authentication to authenticate all further communication 1007between the client and the server. This will only work if the 1008connection was made over GSSAPI in the first place. Encrypted data is 1009automatically authenticated, so using both @code{Gssapi-authenticate} 1010and @code{Gssapi-encrypt} has no effect beyond that of 1011@code{Gssapi-encrypt}. Unlike encrypted data, it is reasonable to 1012compress authenticated data. 1013 1014Note that this request does not fully prevent an attacker from hijacking 1015the connection, in the sense that it does not prevent hijacking the 1016connection between the initial authentication and the 1017@code{Gssapi-authenticate} request. 1018 1019@item Set @var{variable}=@var{value} \n 1020Response expected: no. 1021Set a user variable @var{variable} to @var{value}. 1022The @code{Root} request need not have been previously sent. 1023 1024@item expand-modules \n 1025Response expected: yes. Expand the modules which are specified in the 1026arguments. Returns the data in @code{Module-expansion} responses. Note 1027that the server can assume that this is checkout or export, not rtag or 1028rdiff; the latter do not access the working directory and thus have no 1029need to expand modules on the client side. 1030 1031Expand may not be the best word for what this request does. It does not 1032necessarily tell you all the files contained in a module, for example. 1033Basically it is a way of telling you which working directories the 1034server needs to know about in order to handle a checkout of the 1035specified modules. 1036 1037For example, suppose that the server has a module defined by 1038 1039@example 1040aliasmodule -a 1dir 1041@end example 1042 1043That is, one can check out @code{aliasmodule} and it will take 1044@code{1dir} in the repository and check it out to @code{1dir} in the 1045working directory. Now suppose the client already has this module 1046checked out and is planning on using the @code{co} request to update it. 1047Without using @code{expand-modules}, the client would have two bad 1048choices: it could either send information about @emph{all} working 1049directories under the current directory, which could be unnecessarily 1050slow, or it could be ignorant of the fact that @code{aliasmodule} stands 1051for @code{1dir}, and neglect to send information for @code{1dir}, which 1052would lead to incorrect operation. 1053@c Those don't really seem like the only two options. I mean, what 1054@c about keeping track of the correspondence from when we first checked 1055@c out a fresh directory? Not that the CVS client does this, or that 1056@c I've really thought about whether it would be a good idea... 1057 1058With @code{expand-modules}, the client would first ask for the module to 1059be expanded: 1060 1061@example 1062C: Root /home/kingdon/zwork/cvsroot 1063. . . 1064C: Argument aliasmodule 1065C: Directory . 1066C: /home/kingdon/zwork/cvsroot 1067C: expand-modules 1068S: Module-expansion 1dir 1069S: ok 1070@end example 1071 1072and then it knows to check the @file{1dir} directory and send 1073requests such as @code{Entry} and @code{Modified} for the files in that 1074directory. 1075 1076@item ci \n 1077@itemx diff \n 1078@itemx tag \n 1079@itemx status \n 1080@itemx admin \n 1081@itemx history \n 1082@itemx watchers \n 1083@itemx editors \n 1084@itemx annotate \n 1085Response expected: yes. Actually do a cvs command. This uses any 1086previous @code{Argument}, @code{Directory}, @code{Entry}, or 1087@code{Modified} requests, if they have been sent. The 1088last @code{Directory} sent specifies the working directory at the time 1089of the operation. No provision is made for any input from the user. 1090This means that @code{ci} must use a @code{-m} argument if it wants to 1091specify a log message. 1092 1093@item log \n 1094Response expected: yes. Show information for past revisions. This uses 1095any previous @code{Directory}, @code{Entry}, or @code{Modified} 1096requests, if they have been sent. The last @code{Directory} sent 1097specifies the working directory at the time of the operation. Also uses 1098previous @code{Argument}'s of which the canonical forms are the 1099following (@sc{cvs} 1.10 and older clients sent what the user specified, 1100but clients are encouraged to use the canonical forms and other forms 1101are deprecated): 1102 1103@table @code 1104@item -b, -h, -l, -N, -R, -t 1105These options go by themselves, one option per @code{Argument} request. 1106 1107@item -d @var{date1}<@var{date2} 1108Select revisions between @var{date1} and @var{date2}. Either date 1109may be omitted in which case there is no date limit at that end of the 1110range (clients may specify dates such as 1 Jan 1970 or 1 Jan 2038 for 1111similar purposes but this is problematic as it makes assumptions about 1112what dates the server supports). Dates are in RFC822/1123 format. The 1113@samp{-d} is one @code{Argument} request and the date range is a second 1114one. 1115 1116@item -d @var{date1}<=@var{date2} 1117Likewise but compare dates for equality. 1118 1119@item -d @var{singledate} 1120Select the single, latest revision dated @var{singledate} or earlier. 1121 1122To include several date ranges and/or singledates, repeat the @samp{-d} 1123option as many times as necessary. 1124 1125@item -r@var{rev1}:@var{rev2} 1126@itemx -r@var{branch} 1127@itemx -r@var{branch}. 1128@itemx -r 1129Specify revisions (note that @var{rev1} or @var{rev2} can be omitted, or 1130can refer to branches). Send both the @samp{-r} and the revision 1131information in a single @code{Argument} request. To include several 1132revision selections, repeat the @samp{-r} option. 1133 1134@item -s @var{state} 1135@itemx -w 1136@itemx -w@var{login} 1137Select on states or users. To include more than one state or user, 1138repeat the option. Send the @samp{-s} option as a separate argument 1139from the state being selected. Send the @samp{-w} option as part of the 1140same argument as the user being selected. 1141@end table 1142 1143@item co \n 1144Response expected: yes. Get files from the repository. This uses any 1145previous @code{Argument}, @code{Directory}, @code{Entry}, or 1146@code{Modified} requests, if they have been sent. Arguments to this 1147command are module names; the client cannot know what directories they 1148correspond to except by (1) just sending the @code{co} request, and then 1149seeing what directory names the server sends back in its responses, and 1150(2) the @code{expand-modules} request. 1151 1152@item export \n 1153Response expected: yes. Get files from the repository. This uses any 1154previous @code{Argument}, @code{Directory}, @code{Entry}, or 1155@code{Modified} requests, if they have been sent. Arguments to this 1156command are module names, as described for the @code{co} request. The 1157intention behind this command is that a client can get sources from a 1158server without storing CVS information about those sources. That is, a 1159client probably should not count on being able to take the entries line 1160returned in the @code{Created} response from an @code{export} request 1161and send it in a future @code{Entry} request. Note that the entries 1162line in the @code{Created} response must indicate whether the file is 1163binary or text, so the client can create it correctly. 1164 1165@item rannotate \n 1166@itemx rdiff \n 1167@itemx rlog \n 1168@itemx rtag \n 1169Response expected: yes. Actually do a cvs command. This uses any 1170previous @code{Argument} requests, if they have been sent. The client 1171should not send @code{Directory}, @code{Entry}, or @code{Modified} 1172requests for these commands; they are not used. Arguments to these 1173commands are module names, as described for @code{co}. 1174 1175@item init @var{root-name} \n 1176Response expected: yes. If it doesn't already exist, create a @sc{cvs} 1177repository @var{root-name}. Note that @var{root-name} is a local 1178directory and @emph{not} a fully qualified @code{CVSROOT} variable. 1179The @code{Root} request need not have been previously sent. 1180 1181@item update \n 1182Response expected: yes. Actually do a @code{cvs update} command. This 1183uses any previous @code{Argument}, @code{Directory}, @code{Entry}, 1184or @code{Modified} requests, if they have been sent. The 1185last @code{Directory} sent specifies the working directory at the time 1186of the operation. The @code{-I} option is not used--files which the 1187client can decide whether to ignore are not mentioned and the client 1188sends the @code{Questionable} request for others. 1189 1190@item import \n 1191Response expected: yes. Actually do a @code{cvs import} command. This 1192uses any previous @code{Argument}, @code{Directory}, @code{Entry}, or 1193@code{Modified} requests, if they have been sent. The 1194last @code{Directory} sent specifies the working directory at the time 1195of the operation - unlike most commands, the repository field of each 1196@code{Directory} request is ignored (it merely must point somewhere 1197within the root). The files to be imported are sent in @code{Modified} 1198requests (files which the client knows should be ignored are not sent; 1199the server must still process the CVSROOT/cvsignore file unless -I ! is 1200sent). A log message must have been specified with a @code{-m} 1201argument. 1202 1203@item add \n 1204Response expected: yes. Add a file or directory. This uses any 1205previous @code{Argument}, @code{Directory}, @code{Entry}, or 1206@code{Modified} requests, if they have been sent. The 1207last @code{Directory} sent specifies the working directory at the time 1208of the operation. 1209 1210To add a directory, send the directory to be added using 1211@code{Directory} and @code{Argument} requests. For example: 1212 1213@example 1214C: Root /u/cvsroot 1215. . . 1216C: Argument nsdir 1217C: Directory nsdir 1218C: /u/cvsroot/1dir/nsdir 1219C: Directory . 1220C: /u/cvsroot/1dir 1221C: add 1222S: M Directory /u/cvsroot/1dir/nsdir added to the repository 1223S: ok 1224@end example 1225 1226You will notice that the server does not signal to the client in any 1227particular way that the directory has been successfully added. The 1228client is supposed to just assume that the directory has been added and 1229update its records accordingly. Note also that adding a directory is 1230immediate; it does not wait until a @code{ci} request as files do. 1231 1232To add a file, send the file to be added using a @code{Modified} 1233request. For example: 1234 1235@example 1236C: Argument nfile 1237C: Directory . 1238C: /u/cvsroot/1dir 1239C: Modified nfile 1240C: u=rw,g=r,o=r 1241C: 6 1242C: hello 1243C: add 1244S: E cvs server: scheduling file `nfile' for addition 1245S: Mode u=rw,g=r,o=r 1246S: Checked-in ./ 1247S: /u/cvsroot/1dir/nfile 1248S: /nfile/0/// 1249S: E cvs server: use 'cvs commit' to add this file permanently 1250S: ok 1251@end example 1252 1253Note that the file has not been added to the repository; the only effect 1254of a successful @code{add} request, for a file, is to supply the client 1255with a new entries line containing @samp{0} to indicate an added file. 1256In fact, the client probably could perform this operation without 1257contacting the server, although using @code{add} does cause the server 1258to perform a few more checks. 1259 1260The client sends a subsequent @code{ci} to actually add the file to the 1261repository. 1262 1263Another quirk of the @code{add} request is that with CVS 1.9 and older, 1264a pathname specified in 1265an @code{Argument} request cannot contain @samp{/}. There is no good 1266reason for this restriction, and in fact more recent CVS servers don't 1267have it. 1268But the way to interoperate with the older servers is to ensure that 1269all @code{Directory} requests for @code{add} (except those used to add 1270directories, as described above), use @samp{.} for 1271@var{local-directory}. Specifying another string for 1272@var{local-directory} may not get an error, but it will get you strange 1273@code{Checked-in} responses from the buggy servers. 1274 1275@item remove \n 1276Response expected: yes. Remove a file. This uses any 1277previous @code{Argument}, @code{Directory}, @code{Entry}, or 1278@code{Modified} requests, if they have been sent. The 1279last @code{Directory} sent specifies the working directory at the time 1280of the operation. 1281 1282Note that this request does not actually do anything to the repository; 1283the only effect of a successful @code{remove} request is to supply the 1284client with a new entries line containing @samp{-} to indicate a removed 1285file. In fact, the client probably could perform this operation without 1286contacting the server, although using @code{remove} may cause the server 1287to perform a few more checks. 1288 1289The client sends a subsequent @code{ci} request to actually record the 1290removal in the repository. 1291 1292@item watch-on \n 1293@itemx watch-off \n 1294@itemx watch-add \n 1295@itemx watch-remove \n 1296Response expected: yes. Actually do the @code{cvs watch on}, @code{cvs 1297watch off}, @code{cvs watch add}, and @code{cvs watch remove} commands, 1298respectively. This uses any previous @code{Argument}, 1299@code{Directory}, @code{Entry}, or @code{Modified} 1300requests, if they have been sent. The last @code{Directory} sent 1301specifies the working directory at the time of the operation. 1302 1303@item release \n 1304Response expected: yes. Note that a @code{cvs release} command has 1305taken place and update the history file accordingly. 1306 1307@item noop \n 1308Response expected: yes. This request is a null command in the sense 1309that it doesn't do anything, but merely (as with any other requests 1310expecting a response) sends back any responses pertaining to pending 1311errors, pending @code{Notified} responses, etc. 1312The @code{Root} request need not have been previously sent. 1313 1314@item update-patches \n 1315Response expected: yes. 1316This request does not actually do anything. It is used as a signal that 1317the server is able to generate patches when given an @code{update} 1318request. The client must issue the @code{-u} argument to @code{update} 1319in order to receive patches. 1320 1321@item gzip-file-contents @var{level} \n 1322Response expected: no. Note that this request does not follow the 1323response convention stated above. @code{Gzip-stream} is suggested 1324instead of @code{gzip-file-contents} as it gives better compression; the 1325only reason to implement the latter is to provide compression with 1326@sc{cvs} 1.8 and earlier. The @code{gzip-file-contents} request asks 1327the server to compress files it sends to the client using @code{gzip} 1328(RFC1952/1951) compression, using the specified level of compression. 1329If this request is not made, the server must not compress files. 1330 1331This is only a hint to the server. It may still decide (for example, in 1332the case of very small files, or files that already appear to be 1333compressed) not to do the compression. Compression is indicated by a 1334@samp{z} preceding the file length. 1335 1336Availability of this request in the server indicates to the client that 1337it may compress files sent to the server, regardless of whether the 1338client actually uses this request. 1339 1340@item wrapper-sendme-rcsOptions \n 1341Response expected: yes. 1342Request that the server transmit mappings from filenames to keyword 1343expansion modes in @code{Wrapper-rcsOption} responses. 1344 1345@item version \n 1346Response expected: yes. 1347Request that the server transmit its version message. 1348The @code{Root} request need not have been previously sent. 1349 1350@item @var{other-request} @var{text} \n 1351Response expected: yes. 1352Any unrecognized request expects a response, and does not 1353contain any additional data. The response will normally be something like 1354@samp{error unrecognized request}, but it could be a different error if 1355a previous request which doesn't expect a response produced an error. 1356@end table 1357 1358When the client is done, it drops the connection. 1359 1360@node Response intro 1361@section Introduction to Responses 1362 1363After a command which expects a response, the server sends however many 1364of the following responses are appropriate. The server should not send 1365data at other times (the current implementation may violate this 1366principle in a few minor places, where the server is printing an error 1367message and exiting---this should be investigated further). 1368 1369Any set of responses always ends with @samp{error} or @samp{ok}. This 1370indicates that the response is over. 1371 1372@c "file updating response" and "file update modifying response" are 1373@c lame terms (mostly because they are so awkward). Any better ideas? 1374The responses @code{Checked-in}, @code{New-entry}, @code{Updated}, 1375@code{Created}, @code{Update-existing}, @code{Merged}, and 1376@code{Patched} are refered to as @dfn{file updating} responses, because 1377they change the status of a file in the working directory in some way. 1378The responses @code{Mode}, @code{Mod-time}, and @code{Checksum} are 1379referred to as @dfn{file update modifying} responses because they modify 1380the next file updating response. In no case shall a file update 1381modifying response apply to a file updating response other than the next 1382one. Nor can the same file update modifying response occur twice for 1383a given file updating response (if servers diagnose this problem, it may 1384aid in detecting the case where clients send an update modifying 1385response without following it by a file updating response). 1386 1387@node Response pathnames 1388@section The "pathname" in responses 1389 1390Many of the responses contain something called @var{pathname}. 1391@c FIXME: should better document when the specified repository needs to 1392@c end in "/.". 1393The name is somewhat misleading; it actually indicates a pair of 1394pathnames. First, a local directory name 1395relative to the directory in which the command was given (i.e. the last 1396@code{Directory} before the command). Then a linefeed and a repository 1397name. Then 1398a slash and the filename (without a @samp{,v} ending). 1399For example, for a file @file{i386.mh} 1400which is in the local directory @file{gas.clean/config} and for which 1401the repository is @file{/rel/cvsfiles/devo/gas/config}: 1402 1403@example 1404gas.clean/config/ 1405/rel/cvsfiles/devo/gas/config/i386.mh 1406@end example 1407 1408If the server wants to tell the client to create a directory, then it 1409merely uses the directory in any response, as described above, and the 1410client should create the directory if it does not exist. Note that this 1411should only be done one directory at a time, in order to permit the 1412client to correctly store the repository for each directory. Servers 1413can use requests such as @code{Clear-sticky}, 1414@code{Clear-static-directory}, or any other requests, to create 1415directories. 1416@c FIXME: Need example here of how "repository" needs to be sent for 1417@c each directory, and cannot be correctly deduced from, say, the most 1418@c deeply nested directory. 1419 1420Some server 1421implementations may poorly distinguish between a directory which should 1422not exist and a directory which contains no files; in order to refrain 1423from creating empty directories a client should both send the @samp{-P} 1424option to @code{update} or @code{co}, and should also detect the case in 1425which the server asks to create a directory but not any files within it 1426(in that case the client should remove the directory or refrain from 1427creating it in the first place). Note that servers could clean this up 1428greatly by only telling the client to create directories if the 1429directory in question should exist, but until servers do this, clients 1430will need to offer the @samp{-P} behavior described above. 1431 1432@node Responses 1433@section Responses 1434 1435Here are the responses: 1436 1437@table @code 1438@item Valid-requests @var{request-list} \n 1439Indicate what requests the server will accept. @var{request-list} 1440is a space separated list of tokens. If the server supports sending 1441patches, it will include @samp{update-patches} in this list. The 1442@samp{update-patches} request does not actually do anything. 1443 1444@item Checked-in @var{pathname} \n 1445Additional data: New Entries line, \n. This means a file @var{pathname} 1446has been successfully operated on (checked in, added, etc.). name in 1447the Entries line is the same as the last component of @var{pathname}. 1448 1449@item New-entry @var{pathname} \n 1450Additional data: New Entries line, \n. Like @code{Checked-in}, but the 1451file is not up to date. 1452 1453@item Updated @var{pathname} \n 1454Additional data: New Entries line, \n, mode, \n, file transmission. A 1455new copy of the file is enclosed. This is used for a new revision of an 1456existing file, or for a new file, or for any other case in which the 1457local (client-side) copy of the file needs to be updated, and after 1458being updated it will be up to date. If any directory in pathname does 1459not exist, create it. This response is not used if @code{Created} and 1460@code{Update-existing} are supported. 1461 1462@item Created @var{pathname} \n 1463This is just like @code{Updated} and takes the same additional data, but 1464is used only if no @code{Entry}, @code{Modified}, or 1465@code{Unchanged} request has been sent for the file in question. The 1466distinction between @code{Created} and @code{Update-existing} is so 1467that the client can give an error message in several cases: (1) there is 1468a file in the working directory, but not one for which @code{Entry}, 1469@code{Modified}, or @code{Unchanged} was sent (for example, a file which 1470was ignored, or a file for which @code{Questionable} was sent), (2) 1471there is a file in the working directory whose name differs from the one 1472mentioned in @code{Created} in ways that the client is unable to use to 1473distinguish files. For example, the client is case-insensitive and the 1474names differ only in case. 1475 1476@item Update-existing @var{pathname} \n 1477This is just like @code{Updated} and takes the same additional data, but 1478is used only if a @code{Entry}, @code{Modified}, or @code{Unchanged} 1479request has been sent for the file in question. 1480 1481This response, or @code{Merged}, indicates that the server has 1482determined that it is OK to overwrite the previous contents of the file 1483specified by @var{pathname}. Provided that the client has correctly 1484sent @code{Modified} or @code{Is-modified} requests for a modified file, 1485and the file was not modified while CVS was running, the server can 1486ensure that a user's modifications are not lost. 1487 1488@item Merged @var{pathname} \n 1489This is just like @code{Updated} and takes the same additional data, 1490with the one difference that after the new copy of the file is enclosed, 1491it will still not be up to date. Used for the results of a merge, with 1492or without conflicts. 1493 1494It is useful to preserve an copy of what the file looked like before the 1495merge. This is basically handled by the server; before sending 1496@code{Merged} it will send a @code{Copy-file} response. For example, if 1497the file is @file{aa} and it derives from revision 1.3, the 1498@code{Copy-file} response will tell the client to copy @file{aa} to 1499@file{.#aa.1.3}. It is up to the client to decide how long to keep this 1500file around; traditionally clients have left it around forever, thus 1501letting the user clean it up as desired. But another answer, such as 1502until the next commit, might be preferable. 1503 1504@item Rcs-diff @var{pathname} \n 1505This is just like @code{Updated} and takes the same additional data, 1506with the one difference that instead of sending a new copy of the file, 1507the server sends an RCS change text. This change text is produced by 1508@samp{diff -n} (the GNU diff @samp{-a} option may also be used). The 1509client must apply this change text to the existing file. This will only 1510be used when the client has an exact copy of an earlier revision of a 1511file. This response is only used if the @code{update} command is given 1512the @samp{-u} argument. 1513 1514@item Patched @var{pathname} \n 1515This is just like @code{Rcs-diff} and takes the same additional data, 1516except that it sends a standard patch rather than an RCS change text. 1517The patch is produced by @samp{diff -c} for @sc{cvs} 1.6 and later (see 1518POSIX.2 for a description of this format), or @samp{diff -u} for 1519previous versions of @sc{cvs}; clients are encouraged to accept either 1520format. Like @code{Rcs-diff}, this response is only used if the 1521@code{update} command is given the @samp{-u} argument. 1522 1523The @code{Patched} response is deprecated in favor of the 1524@code{Rcs-diff} response. However, older clients (CVS 1.9 and earlier) 1525only support @code{Patched}. 1526 1527@item Mode @var{mode} \n 1528This @var{mode} applies to the next file mentioned in 1529@code{Checked-in}. @code{Mode} is a file update modifying response 1530as described in @ref{Response intro}. 1531 1532@item Mod-time @var{time} \n 1533Set the modification time of the next file sent to @var{time}. 1534@code{Mod-time} is a file update modifying response 1535as described in @ref{Response intro}. 1536The 1537@var{time} is in the format specified by RFC822 as modified by RFC1123. 1538The server may specify any timezone it chooses; clients will want to 1539convert that to their own timezone as appropriate. An example of this 1540format is: 1541 1542@example 154326 May 1997 13:01:40 -0400 1544@end example 1545 1546There is no requirement that the client and server clocks be 1547synchronized. The server just sends its recommendation for a timestamp 1548(based on its own clock, presumably), and the client should just believe 1549it (this means that the time might be in the future, for example). 1550 1551If the server does not send @code{Mod-time} for a given file, the client 1552should pick a modification time in the usual way (usually, just let the 1553operating system set the modification time to the time that the CVS 1554command is running). 1555 1556@item Checksum @var{checksum}\n 1557The @var{checksum} applies to the next file sent (that is, 1558@code{Checksum} is a file update modifying response 1559as described in @ref{Response intro}). 1560In the case of 1561@code{Patched}, the checksum applies to the file after being patched, 1562not to the patch itself. The client should compute the checksum itself, 1563after receiving the file or patch, and signal an error if the checksums 1564do not match. The checksum is the 128 bit MD5 checksum represented as 156532 hex digits (MD5 is described in RFC1321). 1566This response is optional, and is only used if the 1567client supports it (as judged by the @code{Valid-responses} request). 1568 1569@item Copy-file @var{pathname} \n 1570Additional data: @var{newname} \n. Copy file @var{pathname} to 1571@var{newname} in the same directory where it already is. This does not 1572affect @code{CVS/Entries}. 1573 1574This can optionally be implemented as a rename instead of a copy. The 1575only use for it which currently has been identified is prior to a 1576@code{Merged} response as described under @code{Merged}. Clients can 1577probably assume that is how it is being used, if they want to worry 1578about things like how long to keep the @var{newname} file around. 1579 1580@item Removed @var{pathname} \n 1581The file has been removed from the repository (this is the case where 1582cvs prints @samp{file foobar.c is no longer pertinent}). 1583 1584@item Remove-entry @var{pathname} \n 1585The file needs its entry removed from @code{CVS/Entries}, but the file 1586itself is already gone (this happens in response to a @code{ci} request 1587which involves committing the removal of a file). 1588 1589@item Set-static-directory @var{pathname} \n 1590This instructs the client to set the @code{Entries.Static} flag, which 1591it should then send back to the server in a @code{Static-directory} 1592request whenever the directory is operated on. @var{pathname} ends in a 1593slash; its purpose is to specify a directory, not a file within a 1594directory. 1595 1596@item Clear-static-directory @var{pathname} \n 1597Like @code{Set-static-directory}, but clear, not set, the flag. 1598 1599@item Set-sticky @var{pathname} \n 1600Additional data: @var{tagspec} \n. Tell the client to set a sticky tag 1601or date, which should be supplied with the @code{Sticky} request for 1602future operations. @var{pathname} ends in a slash; its purpose is to 1603specify a directory, not a file within a directory. The client should 1604store @var{tagspec} and pass it back to the server as-is, to allow for 1605future expansion. The first character of @var{tagspec} is @samp{T} for 1606a tag, @samp{D} for a date, or something else for future expansion. The 1607remainder of @var{tagspec} contains the actual tag or date. 1608 1609@item Clear-sticky @var{pathname} \n 1610Clear any sticky tag or date set by @code{Set-sticky}. 1611 1612@item Template @var{pathname} \n 1613Additional data: file transmission (note: compressed file transmissions 1614are not supported). @var{pathname} ends in a slash; its purpose is to 1615specify a directory, not a file within a directory. Tell the client to 1616store the file transmission as the template log message, and then use 1617that template in the future when prompting the user for a log message. 1618 1619@item Set-checkin-prog @var{dir} \n 1620Additional data: @var{prog} \n. Tell the client to set a checkin 1621program, which should be supplied with the @code{Checkin-prog} request 1622for future operations. 1623 1624@item Set-update-prog @var{dir} \n 1625Additional data: @var{prog} \n. Tell the client to set an update 1626program, which should be supplied with the @code{Update-prog} request 1627for future operations. 1628 1629@item Notified @var{pathname} \n 1630Indicate to the client that the notification for @var{pathname} has been 1631done. There should be one such response for every @code{Notify} 1632request; if there are several @code{Notify} requests for a single file, 1633the requests should be processed in order; the first @code{Notified} 1634response pertains to the first @code{Notify} request, etc. 1635 1636@item Module-expansion @var{pathname} \n 1637Return a file or directory 1638which is included in a particular module. @var{pathname} is relative 1639to cvsroot, unlike most pathnames in responses. @var{pathname} should 1640be used to look and see whether some or all of the module exists on 1641the client side; it is not necessarily suitable for passing as an 1642argument to a @code{co} request (for example, if the modules file 1643contains the @samp{-d} option, it will be the directory specified with 1644@samp{-d}, not the name of the module). 1645 1646@item Wrapper-rcsOption @var{pattern} -k '@var{option}' \n 1647Transmit to the client a filename pattern which implies a certain 1648keyword expansion mode. The @var{pattern} is a wildcard pattern (for 1649example, @samp{*.exe}. The @var{option} is @samp{b} for binary, and so 1650on. Note that although the syntax happens to resemble the syntax in 1651certain CVS configuration files, it is more constrained; there must be 1652exactly one space between @var{pattern} and @samp{-k} and exactly one 1653space between @samp{-k} and @samp{'}, and no string is permitted in 1654place of @samp{-k} (extensions should be done with new responses, not by 1655extending this one, for graceful handling of @code{Valid-responses}). 1656 1657@item M @var{text} \n 1658A one-line message for the user. 1659Note that the format of @var{text} is not designed for machine parsing. 1660Although sometimes scripts and clients will have little choice, the 1661exact text which is output is subject to vary at the discretion of the 1662server and the example output given in this document is just that, 1663example output. Servers are encouraged to use the @samp{MT} response, 1664and future versions of this document will hopefully standardize more of 1665the @samp{MT} tags; see @ref{Text tags}. 1666 1667@item Mbinary \n 1668Additional data: file transmission (note: compressed file transmissions 1669are not supported). This is like @samp{M}, except the contents of the 1670file transmission are binary and should be copied to standard output 1671without translation to local text file conventions. To transmit a text 1672file to standard output, servers should use a series of @samp{M} requests. 1673 1674@item E @var{text} \n 1675Same as @code{M} but send to stderr not stdout. 1676 1677@item F \n 1678@c FIXME: The second sentence, defining "flush", is somewhat off the top 1679@c of my head. Is there some text we can steal from ANSI C or someplace 1680@c which is more carefully thought out? 1681Flush stderr. That is, make it possible for the user to see what has 1682been written to stderr (it is up to the implementation to decide exactly 1683how far it should go to ensure this). 1684 1685@item MT @var{tagname} @var{data} \n 1686 1687This response provides for tagged text. It is similar to 1688SGML/HTML/XML in that the data is structured and a naive application 1689can also make some sense of it without understanding the structure. 1690The syntax is not SGML-like, however, in order to fit into the CVS 1691protocol better and (more importantly) to make it easier to parse, 1692especially in a language like perl or awk. 1693 1694The @var{tagname} can have several forms. If it starts with @samp{a} 1695to @samp{z} or @samp{A} to @samp{Z}, then it represents tagged text. 1696If the implementation recognizes @var{tagname}, then it may interpret 1697@var{data} in some particular fashion. If the implementation does not 1698recognize @var{tagname}, then it should simply treat @var{data} as 1699text to be sent to the user (similar to an @samp{M} response). There 1700are two tags which are general purpose. The @samp{text} tag is 1701similar to an unrecognized tag in that it provides text which will 1702ordinarily be sent to the user. The @samp{newline} tag is used 1703without @var{data} and indicates that a newline will ordinarily be 1704sent to the user (there is no provision for embedding newlines in the 1705@var{data} of other tagged text responses). 1706 1707If @var{tagname} starts with @samp{+} it indicates a start tag and if 1708it starts with @samp{-} it indicates an end tag. The remainder of 1709@var{tagname} should be the same for matching start and end tags, and 1710tags should be nested (for example one could have tags in the 1711following order @code{+bold} @code{+italic} @code{text} @code{-italic} 1712@code{-bold} but not @code{+bold} @code{+italic} @code{text} 1713@code{-bold} @code{-italic}). A particular start and end tag may be 1714documented to constrain the tagged text responses which are valid 1715between them. 1716 1717Note that if @var{data} is present there will always be exactly one 1718space between @var{tagname} and @var{data}; if there is more than one 1719space, then the spaces beyond the first are part of @var{data}. 1720 1721Here is an example of some tagged text responses. Note that there is 1722a trailing space after @samp{Checking in} and @samp{initial revision:} 1723and there are two trailing spaces after @samp{<--}. Such trailing 1724spaces are, of course, part of @var{data}. 1725 1726@example 1727MT +checking-in 1728MT text Checking in 1729MT fname gz.tst 1730MT text ; 1731MT newline 1732MT rcsfile /home/kingdon/zwork/cvsroot/foo/gz.tst,v 1733MT text <-- 1734MT fname gz.tst 1735MT newline 1736MT text initial revision: 1737MT init-rev 1.1 1738MT newline 1739MT text done 1740MT newline 1741MT -checking-in 1742@end example 1743 1744If the client does not support the @samp{MT} response, the same 1745responses might be sent as: 1746 1747@example 1748M Checking in gz.tst; 1749M /home/kingdon/zwork/cvsroot/foo/gz.tst,v <-- gz.tst 1750M initial revision: 1.1 1751M done 1752@end example 1753 1754For a list of specific tags, see @ref{Text tags}. 1755 1756@item error @var{errno-code} @samp{ } @var{text} \n 1757The command completed with an error. @var{errno-code} is a symbolic 1758error code (e.g. @code{ENOENT}); if the server doesn't support this 1759feature, or if it's not appropriate for this particular message, it just 1760omits the errno-code (in that case there are two spaces after 1761@samp{error}). Text is an error message such as that provided by 1762strerror(), or any other message the server wants to use. 1763The @var{text} is like the @code{M} response, in the sense that it is 1764not particularly intended to be machine-parsed; servers may wish to 1765print an error message with @code{MT} responses, and then issue a 1766@code{error} response without @var{text} (although it should be noted 1767that @code{MT} currently has no way of flagging the output as intended 1768for standard error, the way that the @code{E} response does). 1769 1770@item ok \n 1771The command completed successfully. 1772@end table 1773 1774@node Text tags 1775@section Tags for the MT tagged text response 1776 1777The @code{MT} response, as described in @ref{Responses}, offers a 1778way for the server to send tagged text to the client. This section 1779describes specific tags. The intention is to update this section as 1780servers add new tags. 1781 1782In the following descriptions, @code{text} and @code{newline} tags are 1783omitted. Such tags contain information which is intended for users (or 1784to be discarded), and are subject to change at the whim of the server. 1785To avoid being vulnerable to such whim, clients should look for the tags 1786listed here, not @code{text}, @code{newline}, or other tags. 1787 1788The following tag means to indicate to the user that a file has been 1789updated. It is more or less redundant with the @code{Created} and 1790@code{Update-existing} responses, but we don't try to specify here 1791whether it occurs in exactly the same circumstances as @code{Created} 1792and @code{Update-existing}. The @var{name} is the pathname of the file 1793being updated relative to the directory in which the command is 1794occurring (that is, the last @code{Directory} request which is sent 1795before the command). 1796 1797@example 1798MT +updated 1799MT fname @var{name} 1800MT -updated 1801@end example 1802 1803The @code{importmergecmd} tag is used when doing an import which has 1804conflicts. The client can use it to report how to merge in the newly 1805imported changes. The @var{count} is the number of conflicts. The 1806newly imported changes can be merged by running the following command: 1807@smallexample 1808cvs checkout -j @var{tag1} -j @var{tag2} @var{repository} 1809@end smallexample 1810 1811@example 1812MT +importmergecmd 1813MT conflicts @var{count} 1814MT mergetag1 @var{tag1} 1815MT mergetag2 @var{tag2} 1816MT repository @var{repository} 1817MT -importmergecmd 1818@end example 1819 1820@node Example 1821@section Example 1822 1823@c The C:/S: convention is in imitation of RFC1869 (and presumably 1824@c other RFC's). In other formatting concerns, we might want to think 1825@c about whether there is an easy way to provide RFC1543 formatting 1826@c (without negating the advantages of texinfo), and whether we should 1827@c use RFC2234 BNF (I fear that would be less clear than 1828@c what we do now, however). Plus what about RFC2119 terminology (MUST, 1829@c SHOULD, &c) or ISO terminology (shall, should, or whatever they are)? 1830Here is an example; lines are prefixed by @samp{C: } to indicate the 1831client sends them or @samp{S: } to indicate the server sends them. 1832 1833The client starts by connecting, sending the root, and completing the 1834protocol negotiation. In actual practice the lists of valid responses 1835and requests would be longer. 1836@c The reason that we artificially shorten the lists is to avoid phony 1837@c line breaks. Any better solutions? 1838@c Other than that, this exchange is taken verbatim from the data 1839@c exchanged by CVS (as of Nov 1996). That is why some of the requests and 1840@c reponses are not quite what you would pick for pedagogical purposes. 1841 1842@example 1843C: Root /u/cvsroot 1844C: Valid-responses ok error Checked-in M E 1845C: valid-requests 1846S: Valid-requests Root Directory Entry Modified Argument Argumentx ci co 1847S: ok 1848C: UseUnchanged 1849@end example 1850 1851The client wants to check out the @code{supermunger} module into a fresh 1852working directory. Therefore it first expands the @code{supermunger} 1853module; this step would be omitted if the client was operating on a 1854directory rather than a module. 1855@c Why does it send Directory here? The description of expand-modules 1856@c doesn't really say much of anything about what use, if any, it makes of 1857@c Directory and similar requests sent previously. 1858 1859@example 1860C: Argument supermunger 1861C: Directory . 1862C: /u/cvsroot 1863C: expand-modules 1864@end example 1865 1866The server replies that the @code{supermunger} module expands to the 1867directory @code{supermunger} (the simplest case): 1868 1869@example 1870S: Module-expansion supermunger 1871S: ok 1872@end example 1873 1874The client then proceeds to check out the directory. The fact that it 1875sends only a single @code{Directory} request which specifies @samp{.} 1876for the working directory means that there is not already a 1877@code{supermunger} directory on the client. 1878@c What is -N doing here? 1879 1880@example 1881C: Argument -N 1882C: Argument supermunger 1883C: Directory . 1884C: /u/cvsroot 1885C: co 1886@end example 1887 1888The server replies with the requested files. In this example, there is 1889only one file, @file{mungeall.c}. The @code{Clear-sticky} and 1890@code{Clear-static-directory} requests are sent by the current 1891implementation but they have no effect because the default is for those 1892settings to be clear when a directory is newly created. 1893 1894@example 1895S: Clear-sticky supermunger/ 1896S: /u/cvsroot/supermunger/ 1897S: Clear-static-directory supermunger/ 1898S: /u/cvsroot/supermunger/ 1899S: E cvs server: Updating supermunger 1900S: M U supermunger/mungeall.c 1901S: Created supermunger/ 1902S: /u/cvsroot/supermunger/mungeall.c 1903S: /mungeall.c/1.1/// 1904S: u=rw,g=r,o=r 1905S: 26 1906S: int mein () @{ abort (); @} 1907S: ok 1908@end example 1909 1910The current client implementation would break the connection here and make a 1911new connection for the next command. However, the protocol allows it 1912to keep the connection open and continue, which is what we show here. 1913 1914After the user modifies the file and instructs the client to check it 1915back in. The client sends arguments to specify the log message and file 1916to check in: 1917 1918@example 1919C: Argument -m 1920C: Argument Well, you see, it took me hours and hours to find 1921C: Argumentx this typo and I searched and searched and eventually 1922C: Argumentx had to ask John for help. 1923C: Argument mungeall.c 1924@end example 1925 1926It also sends information about the contents of the working directory, 1927including the new contents of the modified file. Note that the user has 1928changed into the @file{supermunger} directory before executing this 1929command; the top level directory is a user-visible concept because the 1930server should print filenames in @code{M} and @code{E} responses 1931relative to that directory. 1932@c We are waving our hands about the order of the requests. "Directory" 1933@c and "Argument" can be in any order, but this probably isn't specified 1934@c very well. 1935 1936@example 1937C: Directory . 1938C: /u/cvsroot/supermunger 1939C: Entry /mungeall.c/1.1/// 1940C: Modified mungeall.c 1941C: u=rw,g=r,o=r 1942C: 26 1943C: int main () @{ abort (); @} 1944@end example 1945 1946And finally, the client issues the checkin command (which makes use of 1947the data just sent): 1948 1949@example 1950C: ci 1951@end example 1952 1953And the server tells the client that the checkin succeeded: 1954 1955@example 1956S: M Checking in mungeall.c; 1957S: E /u/cvsroot/supermunger/mungeall.c,v <-- mungeall.c 1958S: E new revision: 1.2; previous revision: 1.1 1959S: E done 1960S: Mode u=rw,g=r,o=r 1961S: Checked-in ./ 1962S: /u/cvsroot/supermunger/mungeall.c 1963S: /mungeall.c/1.2/// 1964S: ok 1965@end example 1966 1967@node Requirements 1968@section Required versus optional parts of the protocol 1969 1970The following are part of every known implementation of the CVS protocol 1971(except obsolete, pre-1.5, versions of CVS) and it is considered 1972reasonable behavior to completely fail to work if you are connected with 1973an implementation which attempts to not support them. Requests: 1974@code{Root}, @code{Valid-responses}, @code{valid-requests}, 1975@code{Directory}, @code{Entry}, @code{Modified}, @code{Unchanged}, 1976@code{Argument}, @code{Argumentx}, @code{ci}, @code{co}, @code{update}. 1977Responses: @code{ok}, @code{error}, @code{Valid-requests}, 1978@code{Checked-in}, @code{Updated}, @code{Merged}, @code{Removed}, 1979@code{M}, @code{E}. 1980 1981A server need not implement @code{Repository}, but in order to interoperate 1982with CVS 1.5 through 1.9 it must claim to implement it (in 1983@code{Valid-requests}). The client will not actually send the request. 1984 1985@node Obsolete 1986@section Obsolete protocol elements 1987 1988This section briefly describes protocol elements which are obsolete. 1989There is no attempt to document them in full detail. 1990 1991There was a @code{Repository} request which was like @code{Directory} 1992except it only provided @var{repository}, and the local directory was 1993assumed to be similarly named. 1994 1995If the @code{UseUnchanged} request was not sent, there was a @code{Lost} 1996request which was sent to indicate that a file did not exist in the 1997working directory, and the meaning of sending @code{Entries} without 1998@code{Lost} or @code{Modified} was different. All current clients (CVS 19991.5 and later) will send @code{UseUnchanged} if it is supported. 2000 2001@node Protocol Notes 2002@chapter Notes on the Protocol 2003 2004A number of enhancements are possible. Also see the file @sc{todo} in 2005the @sc{cvs} source distribution, which has further ideas concerning 2006various aspects of @sc{cvs}, some of which impact the protocol. 2007 2008@itemize @bullet 2009@item 2010The @code{Modified} request could be speeded up by sending diffs rather 2011than entire files. The client would need some way to keep the version 2012of the file which was originally checked out; probably requiring the use 2013of "cvs edit" in this case is the most sensible course (the "cvs edit" 2014could be handled by a package like VC for emacs). This would also allow 2015local operation of @code{cvs diff} without arguments. 2016 2017@item 2018The fact that @code{pserver} requires an extra network turnaround in 2019order to perform authentication would be nice to avoid. This relates to 2020the issue of reporting errors; probably the clean solution is to defer 2021the error until the client has issued a request which expects a 2022response. To some extent this might relate to the next item (in terms 2023of how easy it is to skip a whole bunch of requests until we get to one 2024that expects a response). I know that the kerberos code doesn't wait in 2025this fashion, but that probably can cause network deadlocks and perhaps 2026future problems running over a transport which is more transaction 2027oriented than TCP. On the other hand I'm not sure it is wise to make 2028the client conduct a lengthy upload only to find there is an 2029authentication failure. 2030 2031@item 2032The protocol uses an extra network turnaround for protocol negotiation 2033(@code{valid-requests}). It might be nice to avoid this by having the 2034client be able to send requests and tell the server to ignore them if 2035they are unrecognized (different requests could produce a fatal error if 2036unrecognized). To do this there should be a standard syntax for 2037requests. For example, perhaps all future requests should be a single 2038line, with mechanisms analogous to @code{Argumentx}, or several requests 2039working together, to provide greater amounts of information. Or there 2040might be a standard mechanism for counted data (analogous to that used 2041by @code{Modified}) or continuation lines (like a generalized 2042@code{Argumentx}). It would be useful to compare what HTTP is planning 2043in this area; last I looked they were contemplating something called 2044Protocol Extension Protocol but I haven't looked at the relevant IETF 2045documents in any detail. Obviously, we want something as simple as 2046possible (but no simpler). 2047 2048@item 2049The scrambling algorithm in the CVS client and server actually support 2050more characters than those documented in @ref{Password scrambling}. 2051Someday we are going to either have to document them all (but this is 2052not as easy as it may look, see below), or (gradually and with adequate 2053process) phase out the support for other characters in the CVS 2054implementation. This business of having the feature partly undocumented 2055isn't a desirable state long-term. 2056 2057The problem with documenting other characters is that unless we know 2058what character set is in use, there is no way to make a password 2059portable from one system to another. For example, a with a circle on 2060top might have different encodings in different character sets. 2061 2062It @emph{almost} works to say that the client picks an arbitrary, 2063unknown character set (indeed, having the CVS client know what character 2064set the user has in mind is a hard problem otherwise), and scrambles 2065according to a certain octet<->octet mapping. There are two problems 2066with this. One is that the protocol has no way to transmit character 10 2067decimal (linefeed), and the current server and clients have no way to 2068handle 0 decimal (NUL). This may cause problems with certain multibyte 2069character sets, in which octets 10 and 0 will appear in the middle of 2070other characters. The other problem, which is more minor and possibly 2071not worth worrying about, is that someone can type a password on one 2072system and then go to another system which uses a different encoding for 2073the same characters, and have their password not work. 2074 2075The restriction to the ISO646 invariant subset is the best approach for 2076strings which are not particularly significant to users. Passwords are 2077visible enough that this is somewhat doubtful as applied here. ISO646 2078does, however, have the virtue (!?) of offending everyone. It is easy 2079to say "But the $ is right on people's keyboards! Surely we can't 2080forbid that". From a human factors point of view, that makes quite a 2081bit of sense. The contrary argument, of course, is that a with a circle 2082on top, or some of the characters poorly handled by Unicode, are on 2083@emph{someone}'s keyboard. 2084 2085@end itemize 2086 2087@bye 2088