/contrib/cvs/doc/cvsclient.texi
Unknown | 2080 lines | 1788 code | 292 blank | 0 comment | 0 complexity | d0204570b0f364de896fd056ee1a9ca7 MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
Large files files are truncated, but you can click here to view the full file
1\input texinfo @c -*- texinfo -*- 2 3@setfilename cvsclient.info 4@include version-client.texi 5 6@dircategory Programming 7@direntry 8* cvsclient: (cvsclient). The CVS client/server protocol. 9@end direntry 10 11@node Top 12@top CVS Client/Server 13 14This document describes the client/server protocol used by CVS. It does 15not describe how to use or administer client/server CVS; see the regular 16CVS manual for that. This is version @value{VERSION} of the protocol 17specification---@xref{Introduction}, for more on what this version number 18means. 19 20@menu 21* Introduction:: What is CVS and what is the client/server protocol for? 22* Goals:: Basic design decisions, requirements, scope, etc. 23* Connection and Authentication:: Various ways to connect to the server 24* Password scrambling:: Scrambling used by pserver 25* Protocol:: Complete description of the protocol 26* Protocol Notes:: Possible enhancements, limitations, etc. of the protocol 27@end menu 28 29@node Introduction 30@chapter Introduction 31 32CVS is a version control system (with some additional configuration 33management functionality). It maintains a central @dfn{repository} 34which stores files (often source code), including past versions, 35information about who modified them and when, and so on. People who 36wish to look at or modify those files, known as @dfn{developers}, use 37CVS to @dfn{check out} a @dfn{working directory} from the repository, to 38@dfn{check in} new versions of files to the repository, and other 39operations such as viewing the modification history of a file. If 40developers are connected to the repository by a network, particularly a 41slow or flaky one, the most efficient way to use the network is with the 42CVS-specific protocol described in this document. 43 44Developers, using the machine on which they store their working 45directory, run the CVS @dfn{client} program. To perform operations 46which cannot be done locally, it connects to the CVS @dfn{server} 47program, which maintains the repository. For more information on how 48to connect see @ref{Connection and Authentication}. 49 50This document describes the CVS protocol. Unfortunately, it does not 51yet completely document one aspect of the protocol---the detailed 52operation of each CVS command and option---and one must look at the CVS 53user documentation, @file{cvs.texinfo}, for that information. The 54protocol is non-proprietary (anyone who wants to is encouraged to 55implement it) and an implementation, known as CVS, is available under 56the GNU Public License. The CVS distribution, containing this 57implementation, @file{cvs.texinfo}, and a copy (possibly more or less up 58to date than what you are reading now) of this document, 59@file{cvsclient.texi}, can be found at the usual GNU FTP sites, with a 60filename such as @file{cvs-@var{version}.tar.gz}. 61 62This is version @value{VERSION} of the protocol specification. This 63version number is intended only to aid in distinguishing different 64versions of this specification. Although the specification is currently 65maintained in conjunction with the CVS implementation, and carries the 66same version number, it also intends to document what is involved with 67interoperating with other implementations (such as other versions of 68CVS); see @ref{Requirements}. This version number should not be used 69by clients or servers to determine what variant of the protocol to 70speak; they should instead use the @code{valid-requests} and 71@code{Valid-responses} mechanism (@pxref{Protocol}), which is more 72flexible. 73 74@node Goals 75@chapter Goals 76 77@itemize @bullet 78@item 79Do not assume any access to the repository other than via this protocol. 80It does not depend on NFS, rdist, etc. 81 82@item 83Providing a reliable transport is outside this protocol. The protocol 84expects a reliable transport that is transparent (that is, there is no 85translation of characters, including characters such as 86linefeeds or carriage returns), and can transmit all 256 octets (for 87example for proper handling of binary files, compression, and 88encryption). The encoding of characters specified by the protocol (the 89names of requests and so on) is the invariant ISO 646 character set (a 90subset of most popular character sets including ASCII and others). For 91more details on running the protocol over the TCP reliable transport, 92see @ref{Connection and Authentication}. 93 94@item 95Security and authentication are handled outside this protocol (but see 96below about @samp{cvs kserver} and @samp{cvs pserver}). 97 98@item 99The protocol makes it possible for updates to be atomic with respect to 100checkins; that is if someone commits changes to several files in one cvs 101command, then an update by someone else would either get all the 102changes, or none of them. The current @sc{cvs} server can't do this, 103but that isn't the protocol's fault. 104 105@item 106The protocol is, with a few exceptions, transaction-based. That is, the 107client sends all its requests (without waiting for server responses), 108and then waits for the server to send back all responses (without 109waiting for further client requests). This has the advantage of 110minimizing network turnarounds and the disadvantage of sometimes 111transferring more data than would be necessary if there were a richer 112interaction. Another, more subtle, advantage is that there is no need 113for the protocol to provide locking for features such as making checkins 114atomic with respect to updates. Any such locking can be handled 115entirely by the server. A good server implementation (such as the 116current @sc{cvs} server) will make sure that it does not have any such 117locks in place whenever it is waiting for communication with the client; 118this prevents one client on a slow or flaky network from interfering 119with the work of others. 120 121@item 122It is a general design goal to provide only one way to do a given 123operation (where possible). For example, implementations have no choice 124about whether to terminate lines with linefeeds or some other 125character(s), and request and response names are case-sensitive. This 126is to enhance interoperability. If a protocol allows more than one way 127to do something, it is all too easy for some implementations to support 128only some of them (perhaps accidentally). 129@c I vaguely remember reading, probably in an RFC, about the problems 130@c that were caused when some people decided that SMTP should accept 131@c other line termination (in the message ("DATA")?) than CRLF. However, I 132@c can't seem to track down the reference. 133@end itemize 134 135@node Connection and Authentication 136@chapter How to Connect to and Authenticate Oneself to the CVS server 137 138Connection and authentication occurs before the CVS protocol itself is 139started. There are several ways to connect. 140 141@table @asis 142@item server 143If the client has a way to execute commands on the server, and provide 144input to the commands and output from them, then it can connect that 145way. This could be the usual rsh (port 514) protocol, Kerberos rsh, 146SSH, or any similar mechanism. The client may allow the user to specify 147the name of the server program; the default is @code{cvs}. It is 148invoked with one argument, @code{server}. Once it invokes the server, 149the client proceeds to start the cvs protocol. 150 151@item kserver 152The kerberized server listens on a port (in the current implementation, 153by having inetd call "cvs kserver") which defaults to 1999. The client 154connects, sends the usual kerberos authentication information, and then 155starts the cvs protocol. Note: port 1999 is officially registered for 156another use, and in any event one cannot register more than one port for 157CVS, so GSS-API (see below) is recommended instead of kserver as a way 158to support kerberos. 159 160@item pserver 161The name @dfn{pserver} is somewhat confusing. It refers to both a 162generic framework which allows the CVS protocol to support several 163authentication mechanisms, and a name for a specific mechanism which 164transfers a username and a cleartext password. Servers need not support 165all mechanisms, and in fact servers will typically want to support only 166those mechanisms which meet the relevant security needs. 167 168The pserver server listens on a port (in the current 169implementation, by having inetd call "cvs pserver") which defaults to 1702401 (this port is officially registered). The client 171connects, and sends the following: 172 173@itemize @bullet 174@item 175the string @samp{BEGIN AUTH REQUEST}, a linefeed, 176@item 177the cvs root, a linefeed, 178@item 179the username, a linefeed, 180@item 181the password trivially encoded (see @ref{Password scrambling}), a 182linefeed, 183@item 184the string @samp{END AUTH REQUEST}, and a linefeed. 185@end itemize 186 187The client must send the 188identical string for cvs root both here and later in the 189@code{Root} request of the cvs 190protocol itself. Servers are encouraged to enforce this restriction. 191The possible server responses (each of which is followed by a linefeed) 192are the following. Note that although there is a small similarity 193between this authentication protocol and the cvs protocol, they are 194separate. 195 196@table @code 197@item I LOVE YOU 198The authentication is successful. The client proceeds with the cvs 199protocol itself. 200 201@item I HATE YOU 202The authentication fails. After sending this response, the server may 203close the connection. It is up to the server to decide whether to give 204this response, which is generic, or a more specific response using 205@samp{E} and/or @samp{error}. 206 207@item E @var{text} 208Provide a message for the user. After this response, the authentication 209protocol continues with another response. Typically the server will 210provide a series of @samp{E} responses followed by @samp{error}. 211Compatibility note: @sc{cvs} 1.9.10 and older clients will print 212@code{unrecognized auth response} and @var{text}, and then exit, upon 213receiving this response. 214 215@item error @var{code} @var{text} 216The authentication fails. After sending this response, the server may 217close the connection. The @var{code} is a code describing why it 218failed, intended for computer consumption. The only code currently 219defined is @samp{0} which is nonspecific, but clients must silently 220treat any unrecognized codes as nonspecific. 221The @var{text} should be supplied to the 222user. Compatibility note: @sc{cvs} 1.9.10 and older clients will print 223@code{unrecognized auth response} and @var{text}, and then exit, upon 224receiving this response. 225Note that @var{text} for this response, or the @var{text} in an @code{E} 226response, is not designed for machine parsing. More vigorous use of 227@var{code}, or future extensions, will be needed to prove a cleaner 228machine-parseable indication of what the error was. 229@end table 230 231@c If you are thinking of putting samp or code around BEGIN AUTH REQUEST 232@c and friends, watch for overfull hboxes. 233If the client wishes to merely authenticate without starting the cvs 234protocol, the procedure is the same, except BEGIN AUTH REQUEST is 235replaced with BEGIN VERIFICATION REQUEST, END AUTH REQUEST 236is replaced with END VERIFICATION REQUEST, and upon receipt of 237I LOVE YOU the connection is closed rather than continuing. 238 239Another mechanism is GSSAPI authentication. GSSAPI is a 240generic interface to security services such as kerberos. GSSAPI is 241specified in RFC2078 (GSSAPI version 2) and RFC1508 (GSSAPI version 1); 242we are not aware of differences between the two which affect the 243protocol in incompatible ways, so we make no attempt to specify one 244version or the other. 245The procedure here is to start with @samp{BEGIN 246GSSAPI REQUEST}. GSSAPI authentication information is then exchanged 247between the client and the server. Each packet of information consists 248of a two byte big-endian length, followed by that many bytes of data. 249After the GSSAPI authentication is complete, the server continues with 250the responses described above (@samp{I LOVE YOU}, etc.). 251 252@item future possibilities 253There are a nearly unlimited number of ways to connect and authenticate. 254One might want to allow access based on IP address (similar to the usual 255rsh protocol but with different/no restrictions on ports < 1024), to 256adopt mechanisms such as Pluggable Authentication Modules (PAM), to 257allow users to run their own servers under their own usernames without 258root access, or any number of other possibilities. The way to add 259future mechanisms, for the most part, should be to continue to use port 2602401, but to use different strings in place of @samp{BEGIN AUTH 261REQUEST}. 262@end table 263 264@node Password scrambling 265@chapter Password scrambling algorithm 266 267The pserver authentication protocol, as described in @ref{Connection and 268Authentication}, trivially encodes the passwords. This is only to 269prevent inadvertent compromise; it provides no protection against even a 270relatively unsophisticated attacker. For comparison, HTTP Basic 271Authentication (as described in RFC2068) uses BASE64 for a similar 272purpose. CVS uses its own algorithm, described here. 273 274The scrambled password starts with @samp{A}, which serves to identify 275the scrambling algorithm in use. After that follows a single octet for 276each character in the password, according to a fixed encoding. The 277values are shown here, with the encoded values in decimal. Control 278characters, space, and characters outside the invariant ISO 646 279character set are not shown; such characters are not recommended for use 280in passwords. There is a long discussion of character set issues in 281@ref{Protocol Notes}. 282 283@example 284 0 111 P 125 p 58 285! 120 1 52 A 57 Q 55 a 121 q 113 286" 53 2 75 B 83 R 54 b 117 r 32 287 3 119 C 43 S 66 c 104 s 90 288 4 49 D 46 T 124 d 101 t 44 289% 109 5 34 E 102 U 126 e 100 u 98 290& 72 6 82 F 40 V 59 f 69 v 60 291' 108 7 81 G 89 W 47 g 73 w 51 292( 70 8 95 H 38 X 92 h 99 x 33 293) 64 9 65 I 103 Y 71 i 63 y 97 294* 76 : 112 J 45 Z 115 j 94 z 62 295+ 67 ; 86 K 50 k 93 296, 116 < 118 L 42 l 39 297- 74 = 110 M 123 m 37 298. 68 > 122 N 91 n 61 299/ 87 ? 105 O 35 _ 56 o 48 300@end example 301 302@node Protocol 303@chapter The CVS client/server protocol 304 305In the following, @samp{\n} refers to a linefeed and @samp{\t} refers to 306a horizontal tab; @dfn{requests} are what the client sends and 307@dfn{responses} are what the server sends. In general, the connection is 308governed by the client---the server does not send responses without 309first receiving requests to do so; see @ref{Response intro} for more 310details of this convention. 311 312It is typical, early in the connection, for the client to transmit a 313@code{Valid-responses} request, containing all the responses it 314supports, followed by a @code{valid-requests} request, which elicits 315from the server a @code{Valid-requests} response containing all the 316requests it understands. In this way, the client and server each find 317out what the other supports before exchanging large amounts of data 318(such as file contents). 319 320@c Hmm, having 3 sections in this menu makes a certain amount of sense 321@c but that structure gets lost in the printed manual (not sure about 322@c HTML). Perhaps there is a better way. 323@menu 324 325General protocol conventions: 326 327* Entries Lines:: Transmitting RCS data 328* File Modes:: Read, write, execute, and possibly more... 329* Filenames:: Conventions regarding filenames 330* File transmissions:: How file contents are transmitted 331* Strings:: Strings in various requests and responses 332* Dates:: Times and dates 333 334The protocol itself: 335 336* Request intro:: General conventions relating to requests 337* Requests:: List of requests 338* Response intro:: General conventions relating to responses 339* Response pathnames:: The "pathname" in responses 340* Responses:: List of responses 341* Text tags:: More details about the MT response 342 343An example session, and some further observations: 344 345* Example:: A conversation between client and server 346* Requirements:: Things not to omit from an implementation 347* Obsolete:: Former protocol features 348@end menu 349 350@node Entries Lines 351@section Entries Lines 352 353Entries lines are transmitted as: 354 355@example 356/ @var{name} / @var{version} / @var{conflict} / @var{options} / @var{tag_or_date} 357@end example 358 359@var{tag_or_date} is either @samp{T} @var{tag} or @samp{D} @var{date} 360or empty. If it is followed by a slash, anything after the slash 361shall be silently ignored. 362 363@var{version} can be empty, or start with @samp{0} or @samp{-}, for no 364user file, new user file, or user file to be removed, respectively. 365 366@c FIXME: should distinguish sender and receiver behavior here; the 367@c "anything else" and "does not start with" are intended for future 368@c expansion, and we should specify a sender behavior. 369@var{conflict}, if it starts with @samp{+}, indicates that the file had 370conflicts in it. The rest of @var{conflict} is @samp{=} if the 371timestamp matches the file, or anything else if it doesn't. If 372@var{conflict} does not start with a @samp{+}, it is silently ignored. 373 374@var{options} signifies the keyword expansion options (for example 375@samp{-ko}). In an @code{Entry} request, this indicates the options 376that were specified with the file from the previous file updating 377response (@pxref{Response intro}, for a list of file updating 378responses); if the client is specifying the @samp{-k} or @samp{-A} 379option to @code{update}, then it is the server which figures out what 380overrides what. 381 382@node File Modes 383@section File Modes 384 385A mode is any number of repetitions of 386 387@example 388@var{mode-type} = @var{data} 389@end example 390 391separated by @samp{,}. 392 393@var{mode-type} is an identifier composed of alphanumeric characters. 394Currently specified: @samp{u} for user, @samp{g} for group, @samp{o} 395for other (see below for discussion of whether these have their POSIX 396meaning or are more loose). Unrecognized values of @var{mode-type} 397are silently ignored. 398 399@var{data} consists of any data not containing @samp{,}, @samp{\0} or 400@samp{\n}. For @samp{u}, @samp{g}, and @samp{o} mode types, data 401consists of alphanumeric characters, where @samp{r} means read, @samp{w} 402means write, @samp{x} means execute, and unrecognized letters are 403silently ignored. 404 405The two most obvious ways in which the mode matters are: (1) is it 406writeable? This is used by the developer communication features, and 407is implemented even on OS/2 (and could be implemented on DOS), whose 408notion of mode is limited to a readonly bit. (2) is it executable? 409Unix CVS users need CVS to store this setting (for shell scripts and 410the like). The current CVS implementation on unix does a little bit 411more than just maintain these two settings, but it doesn't really have 412a nice general facility to store or version control the mode, even on 413unix, much less across operating systems with diverse protection 414features. So all the ins and outs of what the mode means across 415operating systems haven't really been worked out (e.g. should the VMS 416port use ACLs to get POSIX semantics for groups?). 417 418@node Filenames 419@section Conventions regarding transmission of file names 420 421In most contexts, @samp{/} is used to separate directory and file 422names in filenames, and any use of other conventions (for example, 423that the user might type on the command line) is converted to that 424form. The only exceptions might be a few cases in which the server 425provides a magic cookie which the client then repeats verbatim, but as 426the server has not yet been ported beyond unix, the two rules provide 427the same answer (and what to do if future server ports are operating 428on a repository like e:/foo or CVS_ROOT:[FOO.BAR] has not been 429carefully thought out). 430 431Characters outside the invariant ISO 646 character set should be avoided 432in filenames. This restriction may need to be relaxed to allow for 433characters such as @samp{[} and @samp{]} (see above about non-unix 434servers); this has not been carefully considered (and currently 435implementations probably use whatever character sets that the operating 436systems they are running on allow, and/or that users specify). Of 437course the most portable practice is to restrict oneself further, to the 438POSIX portable filename character set as specified in POSIX.1. 439 440@node File transmissions 441@section File transmissions 442 443File contents (noted below as @var{file transmission}) can be sent in 444one of two forms. The simpler form is a number of bytes, followed by a 445linefeed, followed by the specified number of bytes of file contents. 446These are the entire contents of the specified file. Second, if both 447client and server support @samp{gzip-file-contents}, a @samp{z} may 448precede the length, and the `file contents' sent are actually compressed 449with @samp{gzip} (RFC1952/1951) compression. The length specified is 450that of the compressed version of the file. 451 452In neither case are the file content followed by any additional data. 453The transmission of a file will end with a linefeed iff that file (or its 454compressed form) ends with a linefeed. 455 456The encoding of file contents depends on the value for the @samp{-k} 457option. If the file is binary (as specified by the @samp{-kb} option in 458the appropriate place), then it is just a certain number of octets, and 459the protocol contributes nothing towards determining the encoding (using 460the file name is one widespread, if not universally popular, mechanism). 461If the file is text (not binary), then the file is sent as a series of 462lines, separated by linefeeds. If the keyword expansion is set to 463something other than @samp{-ko}, then it is expected that the file 464conform to the RCS expectations regarding keyword expansion---in 465particular, that it is in a character set such as ASCII in which 0x24 is 466a dollar sign (@samp{$}). 467 468@node Strings 469@section Strings 470 471In various contexts, for example the @code{Argument} request and the 472@code{M} response, one transmits what is essentially an arbitrary 473string. Often this will have been supplied by the user (for example, 474the @samp{-m} option to the @code{ci} request). The protocol has no 475mechanism to specify the character set of such strings; it would be 476fairly safe to stick to the invariant ISO 646 character set but the 477existing practice is probably to just transmit whatever the user 478specifies, and hope that everyone involved agrees which character set is 479in use, or sticks to a common subset. 480 481@node Dates 482@section Dates 483 484The protocol contains times and dates in various places. 485 486For the @samp{-D} option to the @code{annotate}, @code{co}, @code{diff}, 487@code{export}, @code{history}, @code{rannotate}, @code{rdiff}, 488@code{rtag}, @code{tag}, 489and @code{update} requests, the server should support two formats: 490 491@example 49226 May 1997 13:01:40 -0000 ; @r{RFC 822 as modified by RFC 1123} 4935/26/1997 13:01:40 GMT ; @r{traditional} 494@end example 495 496The former format is preferred; the latter however is sent by the CVS 497command line client (versions 1.5 through at least 1.9). 498 499For the @samp{-d} option to the @code{log} and @code{rlog} requests, 500servers should at 501least support RFC 822/1123 format. Clients are encouraged to use this 502format too (the command line CVS client, version 1.10 and older, just passed 503along the date format specified by the user, however). 504 505The @code{Mod-time} response and @code{Checkin-time} request use RFC 506822/1123 format (see the descriptions of that response and request for 507details). 508 509For @code{Notify}, see the description of that request. 510 511@node Request intro 512@section Request intro 513 514By convention, requests which begin with a capital letter do not elicit 515a response from the server, while all others do -- save one. The 516exception is @samp{gzip-file-contents}. Unrecognized requests will 517always elicit a response from the server, even if that request begins 518with a capital letter. 519 520The term @dfn{command} means a request which expects a response (except 521@code{valid-requests}). The general model is that the client transmits 522a great number of requests, but nothing happens until the very end when 523the client transmits a command. Although the intention is that 524transmitting several commands in one connection should be legal, 525existing servers probably have some bugs with some combinations of more 526than one command, and so clients may find it necessary to make several 527connections in some cases. This should be thought of as a workaround 528rather than a desired attribute of the protocol. 529 530@node Requests 531@section Requests 532 533Here are the requests: 534 535@table @code 536@item Root @var{pathname} \n 537Response expected: no. Tell the server which @code{CVSROOT} to use. 538Note that @var{pathname} is @emph{not} a fully qualified @code{CVSROOT} 539variable, but only the local directory part of it. @var{pathname} must 540already exist on the server. Again, @var{pathname} @emph{does not} include 541the hostname of the server, how to access the server, etc.; by the time 542the CVS protocol is in use, connection, authentication, etc., are 543already taken care of. 544 545The @code{Root} request must be sent only once, and it must be sent 546before any requests other than @code{Valid-responses}, 547@code{valid-requests}, @code{UseUnchanged}, @code{Set}, 548@code{Global_option}, @code{noop}, or @code{version}. 549 550@item Valid-responses @var{request-list} \n 551Response expected: no. 552Tell the server what responses the client will accept. 553request-list is a space separated list of tokens. 554The @code{Root} request need not have been previously sent. 555 556@item valid-requests \n 557Response expected: yes. 558Ask the server to send back a @code{Valid-requests} response. 559The @code{Root} request need not have been previously sent. 560 561@item Directory @var{local-directory} \n 562Additional data: @var{repository} \n. Response expected: no. 563Tell the server what directory to use. The @var{repository} should be a 564directory name from a previous server response. Note that 565this both gives a default for @code{Entry} and @code{Modified} and 566also for @code{ci} and the other commands; normal usage is to send 567@code{Directory} for each directory in which there will be an 568@code{Entry} or @code{Modified}, and then a final @code{Directory} 569for the original directory, then the command. 570The @var{local-directory} is relative to 571the top level at which the command is occurring (i.e., the last 572@code{Directory} which is sent before the command); 573to indicate that top level, @samp{.} should be sent for 574@var{local-directory}. 575 576Here is an example of where a client gets @var{repository} and 577@var{local-directory}. Suppose that there is a module defined by 578 579@example 580moddir 1dir 581@end example 582 583That is, one can check out @code{moddir} and it will take @code{1dir} in 584the repository and check it out to @code{moddir} in the working 585directory. Then an initial check out could proceed like this: 586 587@example 588C: Root /home/kingdon/zwork/cvsroot 589. . . 590C: Argument moddir 591C: Directory . 592C: /home/kingdon/zwork/cvsroot 593C: co 594S: Clear-sticky moddir/ 595S: /home/kingdon/zwork/cvsroot/1dir/ 596. . . 597S: ok 598@end example 599 600In this example the response shown is @code{Clear-sticky}, but it could 601be another response instead. Note that it returns two pathnames. 602The first one, @file{moddir/}, indicates the working 603directory to check out into. The second one, ending in @file{1dir/}, 604indicates the directory to pass back to the server in a subsequent 605@code{Directory} request. For example, a subsequent @code{update} 606request might look like: 607 608@example 609C: Directory moddir 610C: /home/kingdon/zwork/cvsroot/1dir 611. . . 612C: update 613@end example 614 615For a given @var{local-directory}, the repository will be the same for 616each of the responses, so one can use the repository from whichever 617response is most convenient. Typically a client will store the 618repository along with the sources for each @var{local-directory}, use 619that same setting whenever operating on that @var{local-directory}, and 620not update the setting as long as the @var{local-directory} exists. 621 622A client is free to rename a @var{local-directory} at any time (for 623example, in response to an explicit user request). While it is true 624that the server supplies a @var{local-directory} to the client, as noted 625above, this is only the default place to put the directory. Of course, 626the various @code{Directory} requests for a single command (for example, 627@code{update} or @code{ci} request) should name a particular directory 628with the same @var{local-directory}. 629 630Each @code{Directory} request specifies a brand-new 631@var{local-directory} and @var{repository}; that is, 632@var{local-directory} and @var{repository} are never relative to paths 633specified in any previous @code{Directory} request. 634 635Here's a more complex example, in which we request an update of a 636working directory which has been checked out from multiple places in the 637repository. 638 639@example 640C: Argument dir1 641C: Directory dir1 642C: /home/foo/repos/mod1 643. . . 644C: Argument dir2 645C: Directory dir2 646C: /home/foo/repos/mod2 647. . . 648C: Argument dir3 649C: Directory dir3/subdir3 650C: /home/foo/repos/mod3 651. . . 652C: update 653@end example 654 655While directories @code{dir1} and @code{dir2} will be handled in similar 656fashion to the other examples given above, @code{dir3} is slightly 657different from the server's standpoint. Notice that module @code{mod3} 658is actually checked out into @code{dir3/subdir3}, meaning that directory 659@code{dir3} is either empty or does not contain data checked out from 660this repository. 661 662The above example will work correctly in @sc{cvs} 1.10.1 and later. The 663server will descend the tree starting from all directories mentioned in 664@code{Argument} requests and update those directories specifically 665mentioned in @code{Directory} requests. 666 667Previous versions of @sc{cvs} (1.10 and earlier) do not behave the same 668way. While the descent of the tree begins at all directories mentioned 669in @code{Argument} requests, descent into subdirectories only occurs if 670a directory has been mentioned in a @code{Directory} request. 671Therefore, the above example would succeed in updating @code{dir1} and 672@code{dir2}, but would skip @code{dir3} because that directory was not 673specifically mentioned in a @code{Directory} request. A functional 674version of the above that would run on a 1.10 or earlier server is as 675follows: 676 677@example 678C: Argument dir1 679C: Directory dir1 680C: /home/foo/repos/mod1 681. . . 682C: Argument dir2 683C: Directory dir2 684C: /home/foo/repos/mod2 685. . . 686C: Argument dir3 687C: Directory dir3 688C: /home/foo/repos/. 689. . . 690C: Directory dir3/subdir3 691C: /home/foo/repos/mod3 692. . . 693C: update 694@end example 695 696Note the extra @code{Directory dir3} request. It might be better to use 697@code{Emptydir} as the repository for the @code{dir3} directory, but the 698above will certainly work. 699 700One more peculiarity of the 1.10 and earlier protocol is the ordering of 701@code{Directory} arguments. In order for a subdirectory to be 702registered correctly for descent by the recursion processor, its parent 703must be sent first. For example, the following would not work to update 704@code{dir3/subdir3}: 705 706@example 707. . . 708C: Argument dir3 709C: Directory dir3/subdir3 710C: /home/foo/repos/mod3 711. . . 712C: Directory dir3 713C: /home/foo/repos/. 714. . . 715C: update 716@end example 717 718The implementation of the server in 1.10 and earlier writes the 719administration files for a given directory at the time of the 720@code{Directory} request. It also tries to register the directory with 721its parent to mark it for recursion. In the above example, at the time 722@code{dir3/subdir3} is created, the physical directory for @code{dir3} 723will be created on disk, but the administration files will not have been 724created. Therefore, when the server tries to register 725@code{dir3/subdir3} for recursion, the operation will silently fail 726because the administration files do not yet exist for @code{dir3}. 727 728@item Max-dotdot @var{level} \n 729Response expected: no. 730Tell the server that @var{level} levels of directories above the 731directory which @code{Directory} requests are relative to will be 732needed. For example, if the client is planning to use a 733@code{Directory} request for @file{../../foo}, it must send a 734@code{Max-dotdot} request with a @var{level} of at least 2. 735@code{Max-dotdot} must be sent before the first @code{Directory} 736request. 737 738@item Static-directory \n 739Response expected: no. Tell the server that the directory most recently 740specified with @code{Directory} should not have 741additional files checked out unless explicitly requested. The client 742sends this if the @code{Entries.Static} flag is set, which is controlled 743by the @code{Set-static-directory} and @code{Clear-static-directory} 744responses. 745 746@item Sticky @var{tagspec} \n 747Response expected: no. Tell the server that the directory most recently 748specified with @code{Directory} has a sticky tag or date @var{tagspec}. 749The first character of @var{tagspec} is @samp{T} for a tag, @samp{D} 750for a date, or some other character supplied by a Set-sticky response 751from a previous request to the server. The remainder of @var{tagspec} 752contains the actual tag or date, again as supplied by Set-sticky. 753 754The server should remember @code{Static-directory} and @code{Sticky} 755requests for a particular directory; the client need not resend them 756each time it sends a @code{Directory} request for a given directory. 757However, the server is not obliged to remember them beyond the context 758of a single command. 759 760@item Entry @var{entry-line} \n 761Response expected: no. Tell the server what version of a file is on the 762local machine. The name in @var{entry-line} is a name relative to the 763directory most recently specified with @code{Directory}. If the user 764is operating on only some files in a directory, @code{Entry} requests 765for only those files need be included. If an @code{Entry} request is 766sent without @code{Modified}, @code{Is-modified}, or @code{Unchanged}, 767it means the file is 768lost (does not exist in the working directory). If both @code{Entry} 769and one of @code{Modified}, @code{Is-modified}, or @code{Unchanged} are 770sent for the same file, @code{Entry} must be sent first. For a 771given file, one can send @code{Modified}, @code{Is-modified}, or 772@code{Unchanged}, but not more than one of these three. 773 774@item Kopt @var{option} \n 775This indicates to the server which keyword expansion options to use for 776the file specified by the next @code{Modified} or @code{Is-modified} 777request (for example @samp{-kb} for a binary file). This is similar to 778@code{Entry}, but is used for a file for which there is no entries line. 779Typically this will be a file being added via an @code{add} or 780@code{import} request. The client may not send both @code{Kopt} and 781@code{Entry} for the same file. 782 783@item Checkin-time @var{time} \n 784For the file specified by the next @code{Modified} request, use 785@var{time} as the time of the checkin. The @var{time} is in the format 786specified by RFC822 as modified by RFC1123. The client may specify any 787timezone it chooses; servers will want to convert that to their own 788timezone as appropriate. An example of this format is: 789 790@example 79126 May 1997 13:01:40 -0400 792@end example 793 794There is no requirement that the client and server clocks be 795synchronized. The client just sends its recommendation for a timestamp 796(based on file timestamps or whatever), and the server should just believe 797it (this means that the time might be in the future, for example). 798 799Note that this is not a general-purpose way to tell the server about the 800timestamp of a file; that would be a separate request (if there are 801servers which can maintain timestamp and time of checkin separately). 802 803This request should affect the @code{import} request, and may optionally 804affect the @code{ci} request or other relevant requests if any. 805 806@item Modified @var{filename} \n 807Response expected: no. Additional data: mode, \n, file transmission. 808Send the server a copy of one locally modified file. @var{filename} is 809a file within the most recent directory sent with @code{Directory}; it 810must not contain @samp{/}. If 811the user is operating on only some files in a directory, only those 812files need to be included. This can also be sent without @code{Entry}, 813if there is no entry for the file. 814 815@item Is-modified @var{filename} \n 816Response expected: no. Additional data: none. Like @code{Modified}, 817but used if the server only needs 818to know whether the file is modified, not the contents. 819 820The commands which can take @code{Is-modified} instead of 821@code{Modified} with no known change in behavior are: @code{admin}, 822@code{diff} (if and only if two @samp{-r} or @samp{-D} options are 823specified), @code{watch-on}, @code{watch-off}, @code{watch-add}, 824@code{watch-remove}, @code{watchers}, @code{editors}, 825@code{log}, and @code{annotate}. 826 827For the @code{status} command, one can send @code{Is-modified} but if 828the client is using imperfect mechanisms such as timestamps to determine 829whether to consider a file modified, then the behavior will be 830different. That is, if one sends @code{Modified}, then the server will 831actually compare the contents of the file sent and the one it derives 832from to determine whether the file is genuinely modified. But if one 833sends @code{Is-modified}, then the server takes the client's word for 834it. A similar situation exists for @code{tag}, if the @samp{-c} option 835is specified. 836 837Commands for which @code{Modified} is necessary are @code{co}, 838@code{ci}, @code{update}, and @code{import}. 839 840Commands which do not need to inform the server about a working 841directory, and thus should not be sending either @code{Modified} or 842@code{Is-modified}: @code{rdiff}, @code{rtag}, @code{history}, 843and @code{release}. 844 845Commands for which further investigation is warranted are: 846@code{remove}, @code{add}, and @code{export}. Pending such 847investigation, the more conservative course of action is to stick to 848@code{Modified}. 849 850@item Unchanged @var{filename} \n 851Response expected: no. Tell the server that @var{filename} has not been 852modified in the checked out directory. The @var{filename} is 853a file within the most recent directory sent with @code{Directory}; it 854must not contain @samp{/}. 855 856@item UseUnchanged \n 857Response expected: no. To specify the version of the protocol described 858in this document, servers must support this request (although it need 859not do anything) and clients must issue it. 860The @code{Root} request need not have been previously sent. 861 862@item Empty-conflicts \n 863Response expected: yes. This request is an alias for @code{noop}. Its 864presence in the list of @code{valid-requests} is intended to be used as a 865placeholder to alert the client that the server does not require the contents 866of files with conflicts that have not been modified since the merge, for 867operations other than diff. It was a bug in pre 1.11.22 & pre 1.12.14 servers 868that the contents of files with conflicts was required for the server to 869acknowledge the existence of the conflicts. 870 871@item Notify @var{filename} \n 872Response expected: no. 873Tell the server that an @code{edit} or @code{unedit} command has taken 874place. The server needs to send a @code{Notified} response, but such 875response is deferred until the next time that the server is sending 876responses. 877The @var{filename} is a file within the most recent directory sent with 878@code{Directory}; it must not contain @samp{/}. 879Additional data: 880@example 881@var{notification-type} \t @var{time} \t @var{clienthost} \t 882@var{working-dir} \t @var{watches} \n 883@end example 884where @var{notification-type} is @samp{E} for edit, @samp{U} for 885unedit, undefined behavior if @samp{C}, and all other letters should be 886silently ignored for future expansion. 887@var{time} is the time at which the edit or unedit took place, in a 888user-readable format of the client's choice (the server should treat the 889time as an opaque string rather than interpreting it). 890@c Might be useful to specify a format, but I don't know if we want to 891@c specify the status quo (ISO C asctime() format plus timezone) without 892@c offering the option of ISO8601 and/or RFC822/1123 (see cvs.texinfo 893@c for much much more on date formats). 894@var{clienthost} is the name of the host on which the edit or unedit 895took place, and @var{working-dir} is the pathname of the working 896directory where the edit or unedit took place. @var{watches} are the 897temporary watches, zero or more of the following characters in the 898following order: @samp{E} for edit, @samp{U} for unedit, @samp{C} for 899commit, and all other letters should be silently ignored for future 900expansion. If @var{notification-type} is @samp{E} the temporary watches 901are set; if it is @samp{U} they are cleared. 902If @var{watches} is followed by \t then the 903\t and the rest of the line should be ignored, for future expansion. 904 905The @var{time}, @var{clienthost}, and @var{working-dir} fields may not 906contain the characters @samp{+}, @samp{,}, @samp{>}, @samp{;}, or @samp{=}. 907 908Note that a client may be capable of performing an @code{edit} or 909@code{unedit} operation without connecting to the server at that time, 910and instead connecting to the server when it is convenient (for example, 911when a laptop is on the net again) to send the @code{Notify} requests. 912Even if a client is capable of deferring notifications, it should 913attempt to send them immediately (one can send @code{Notify} requests 914together with a @code{noop} request, for example), unless perhaps if 915it can know that a connection would be impossible. 916 917@item Questionable @var{filename} \n 918Response expected: no. Additional data: no. Tell the server to check 919whether @var{filename} should be ignored, and if not, next time the 920server sends responses, send (in a @code{M} response) @samp{?} followed 921by the directory and filename. @var{filename} must not contain 922@samp{/}; it needs to be a file in the directory named by the most 923recent @code{Directory} request. 924@c FIXME: the bit about not containing / is true of most of the 925@c requests, but isn't documented and should be. 926 927@item Case \n 928Response expected: no. Tell the server that filenames should be matched 929in a case-insensitive fashion. Note that this is not the primary 930mechanism for achieving case-insensitivity; for the most part the client 931keeps track of the case which the server wants to use and takes care to 932always use that case regardless of what the user specifies. For example 933the filenames given in @code{Entry} and @code{Modified} requests for the 934same file must match in case regardless of whether the @code{Case} 935request is sent. The latter mechanism is more general (it could also be 936used for 8.3 filenames, VMS filenames with more than one @samp{.}, and 937any other situation in which there is a predictable mapping between 938filenames in the working directory and filenames in the protocol), but 939there are some situations it cannot handle (ignore patterns, or 940situations where the user specifies a filename and the client does not 941know about that file). 942 943Though this request will be supported into the foreseeable future, it has been 944the source of numerous bug reports in the past due to the complexity of testing 945this functionality via the test suite and client developers are encouraged not 946to use it. Instead, please consider munging conflicting names and maintaining 947a map for communicating with the server. For example, suppose the server sends 948files @file{case}, @file{CASE}, and @file{CaSe}. The client could write all 949three files to names such as, @file{case}, @file{case_prefix_case}, and 950@file{case_prefix_2_case} and maintain a mapping between the file names in, for 951instance a new @file{CVS/Map} file. 952 953@item Argument @var{text} \n 954Response expected: no. 955Save argument for use in a subsequent command. Arguments 956accumulate until an argument-using command is given, at which point 957they are forgotten. 958 959@item Argumentx @var{text} \n 960Response expected: no. Append \n followed by text to the current 961argument being saved. 962 963@item Global_option @var{option} \n 964Response expected: no. 965Transmit one of the global options @samp{-q}, @samp{-Q}, @samp{-l}, 966@samp{-t}, @samp{-r}, or @samp{-n}. @var{option} must be one of those 967strings, no variations (such as combining of options) are allowed. For 968graceful handling of @code{valid-requests}, it is probably better to 969make new global options separate requests, rather than trying to add 970them to this request. 971The @code{Root} request need not have been previously sent. 972 973@item Gzip-stream @var{level} \n 974Response expected: no. 975Use zlib (RFC 1950/1951) compression to compress all further communication 976between the client and the server. After this request is sent, all 977further communication must be compressed. All further data received 978from the server will also be compressed. The @var{level} argument 979suggests to the server the level of compression that it should apply; it 980should be an integer between 1 and 9, inclusive, where a higher number 981indicates more compression. 982 983@item Kerberos-encrypt \n 984Response expected: no. 985Use Kerberos encryption to encrypt all further communication between the 986client and the server. This will only work if the connection was made 987over Kerberos in the first place. If both the @code{Gzip-stream} and 988the @code{Kerberos-encrypt} requests are used, the 989@code{Kerberos-encrypt} request should be used first. This will make 990the client and server encrypt the compressed data, as opposed to 991compressing the encrypted data. Encrypted data is generally 992incompressible. 993 994Note that this request does not fully prevent an attacker from hijacking 995the connection, in the sense that it does not prevent hijacking the 996connection between the initial authentication and the 997@code{Kerberos-encrypt} request. 998 999@item Gssapi-encrypt \n 1000Response expected: no. 1001Use GSSAPI encryption to encrypt all further communication between the 1002client and the server. This will only work if the connection was made 1003over GSSAPI in the first place. See @code{Kerberos-encrypt}, above, for 1004the relation between @code{Gssapi-encrypt} and @code{Gzip-stream}. 1005 1006Note that this request does not fully prevent an attacker from hijacking 1007the connection, in the sense that it does not prevent hijacking the 1008connection between the initial authentication and the 1009@code{Gssapi-encrypt} request. 1010 1011@item Gssapi-authenticate \n 1012Response expected: no. 1013Use GSSAPI authentication to authenticate all further communication 1014between the client and the server. This will only work if the 1015connection was made over GSSAPI in the first place. Encrypted data is 1016automatically authenticated, so using both @code{Gssapi-authenticate} 1017and @code{Gssapi-encrypt} has no effect beyond that of 1018@code{Gssapi-encrypt}. Unlike encrypted data, it is reasonable to 1019compress authenticated data. 1020 1021Note that this request does not fully prevent an attacker from hijacking 1022the connection, in the sense that it does not prevent hijacking the 1023connection between the initial authentication and the 1024@code{Gssapi-authenticate} request. 1025 1026@item Set @var{variable}=@var{value} \n 1027Response expected: no. 1028Set a user variable @var{variable} to @var{value}. 1029The @code{Root} request need not have been previously sent. 1030 1031@item expand-modules \n 1032Response expected: yes. Expand the modules which are specified in the 1033arguments. Returns the data in @code{Module-expansion} responses. Note 1034that the server can assume that this is checkout or export, not rtag or 1035rdiff; the latter do not access the working directory and thus have no 1036need to expand modules on the client side. 1037 1038Expand may not be the best word for what this request does. It does not 1039necessarily tell you all the files contained in a module, for example. 1040Basically it is a way of telling you which working directories the 1041server needs to know about in order to handle a checkout of the 1042specified modules. 1043 1044For example, suppose that the server has a module defined by 1045 1046@example 1047aliasmodule -a 1dir 1048@end example 1049 1050That is, one can check out @code{aliasmodule} and it will take 1051@code{1dir} in the repository and check it out to @code{1dir} in the 1052working directory. Now suppose the client already has this module 1053checked out and is planning on using the @code{co} request to update it. 1054Without using @code{expand-modules}, the client would have two bad 1055choices: it could either send information about @emph{all} working 1056directories under the current directory, which could be unnecessarily 1057slow, or it could be ignorant of the fact that @code{aliasmodule} stands 1058for @code{1dir}, and neglect to send information for @code{1dir}, which 1059would lead to incorrect operation. 1060@c Those don't really seem like the only two options. I mean, what 1061@c about keeping track of the correspondence from when we first checked 1062@c out a fresh directory? Not that the CVS client does this, or that 1063@c I've really thought about whether it would be a good idea... 1064 1065With @code{expand-modules}, the client would first ask for the module to 1066be expanded: 1067 1068@example 1069C: Root /home/kingdon/zwork/cvsroot 1070. . . 1071C: Argument aliasmodule 1072C: Directory . 1073C: /home/kingdon/zwork/cvsroot 1074C: expand-modules 1075S: Module-expansion 1dir 1076S: ok 1077@end example 1078 1079and then it knows to check the @file{1dir} directory and send 1080requests such as @code{Entry} and @code{Modified} for the files in that 1081directory. 1082 1083@item ci \n 1084@itemx diff \n 1085@itemx tag \n 1086@itemx status \n 1087@itemx admin \n 1088@itemx history \n 1089@itemx watchers \n 1090@itemx editors \n 1091@itemx annotate \n 1092Response expected: yes. Actually do a cvs command. This uses any 1093previous @code{Argument}, @code{Directory}, @code{Entry}, or 1094@code{Modified} requests, if they have been sent. The 1095last @code{Directory} sent specifies the working directory at the time 1096of the operation. No provision is made for any input from the user. 1097This means that @code{ci} must use a @code{-m} argument if it wants to 1098specify a log message. 1099 1100@item log \n 1101Response expected: yes. Show information for past revisions. This uses 1102any previous @code{Directory}, @code{Entry}, or @code{Modified} 1103requests, if they have been sent. The last @code{Directory} sent 1104specifies the working directory at the time of the operation. Also uses 1105previous @code{Argument}'s of which the canonical forms are the 1106following (@sc{cvs} 1.10 and older cl…
Large files files are truncated, but you can click here to view the full file