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