PageRenderTime 32ms CodeModel.GetById 3ms app.highlight 11ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/cvs/doc/cvsclient.texi

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 2080 lines | 1788 code | 292 blank | 0 comment | 0 complexity | d0204570b0f364de896fd056ee1a9ca7 MD5 | raw file

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