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