$Id: Protocol,v 1.23 2003/03/04 19:26:13 jdp Exp $
Copyright 1999-2003 John D. Polstra

This document describes protocol version 15.6.

General conventions:

  Commands consist of text lines which are generally readable by
  humans.  Tokens in commands are separated by white space.  Tokens
  containing embedded white space employ the following escape
  conventions:

    \_ = space
    \t = tab
    \n = newline
    \r = carriage return
    \\ = backslash

Start-up (active mode):

  Client	Server
  ------	------
		OK <major> <minor> <SWVersion> <greeting>
  PROTO <major> <minor> <SWVersion>
		PROTO <major> <minor>
  USER <user> <hostname>
		OK
  ATTR <numFileTypes>
    <attrTypes0>
    <attrTypes1>
    ...
    <attrTypesN-1>
    .
		ATTR <numFileTypes>
		  <attrTypes0>
		  <attrTypes1>
		  ...
		  <attrTypesM-1>
		  .
  COLL <collection> <release> <umask> <options>
    REF <pattern>
    ...
    ACC <pattern>
    ...
    .
  ...
  .
		COLL <collection> <release> <options>
		  PRFX <keywordPrefix>
		  .
		...
		.
  PORT <endpoint>
		[server connects to the given endpoint]

Shutdown:

  Client			Server
  ------			------
  [close wrA]
  [close wrB]
				[wait for EOF on rdA]
				[wait for EOF on rdB]
				[close wrA]
				[close wrB]
  [wait for EOF on rdA]
  [wait for EOF on rdB]

Tree Lister -> Tree Differ:

  D <dir>
    Go down one directory level into <dir>.

  F <file> <attr>
    The file <file> is live on the client, and the RCS file's attributes
    are <attr>.

  f <file> <attr>
    The file <file> is dead on the client, and the RCS file's attributes
    are <attr>.

  U <attr>
    Go up one directory level.  The attributes of the directory
    being exited are <attr>.

Tree Differ -> Detailer:

  D <file>
    File <file> should be deleted.

  I <dir>
    Create a new directory named <dir>, and add its DirDown entry to
    the list file.  CVS mode only.

  i <dir>
    Remove the DirDown list file entry for the directory <dir>.  CVS
    mode only.

  J <dir> <attr>
    Set the attributes for directory <dir> to <attr>, and update its
    DirUp list file entry.  CVS mode only.

  j <dir>
    Remove the directory <dir>, and delete its DirUp list file
    entry.  CVS mode only.

  H <file> <linkTo>
    Create a hard link named <file> which is a link to <linkTo>, if
    such a link does not already exist live.  CVS mode only.

  h <file> <linkTo>
    Create a hard link named <file> which is a link to <linkTo>, if
    such a link does not already exist dead.  CVS mode only.

  T <file> <attr>
    File <file> should be updated, unless it exists live and has
    attributes of <attr>.  CVS mode only.

  t <file> <attr>
    File <file> should be updated, unless it exists dead and has
    attributes of <attr>.  CVS mode only.

  U <file>
    File <file> should be added or updated.

Detailer -> File Differ:

  A <file>
    Send the entire file <file>.

  C <file> <tag> <date>
    Check out the specified version of <file> and send it in its entirety.
    Checkout mode only.

  D <file>
    File <file> should be deleted.

  H <file> <linkTo>
    Create a hard link named <file> which is a link to <linkTo>, if
    such a link does not already exist live.  CVS mode only.

  h <file> <linkTo>
    Create a hard link named <file> which is a link to <linkTo>, if
    such a link does not already exist dead.  CVS mode only.

  I <dir>
    Create a new directory named <dir>, and add its DirDown entry to
    the list file.  CVS mode only.

  i <dir>
    Remove the DirDown list file entry for the directory <dir>.  CVS
    mode only.

  J <dir> <attr>
    Set the attributes for directory <dir> to <attr>, and update its
    DirUp list file entry.  CVS mode only.

  j <dir>
    Remove the directory <dir>, and delete its DirUp list file
    entry.  CVS mode only.

  L <file> <attr>
    File <file> is live and up to date, but its list file entry needs to
    be updated to <attr>.  CVS mode only.

  l <file> <attr>
    File <file> is dead and up to date, but its list file entry needs to
    be updated to <attr>.  CVS mode only.

  N <file>
    File <file> exists as a node on the client, i.e., as something
    other than a regular file.  CVS mode only.  (* FIXME - really CVS
    mode only? *)

  R <file> <size> <cksum>
    Update the regular file <file> that has size <size> and checksum
    <cksum> on the client.

  r <file> <size> <blockSize>
    Use the rsync algorithm to update <file>.  The file is <size> bytes
    in length on the client.  The file is divided into
    ceiling(<size>/<blockSize>) blocks.  Each block, except possibly the
    last one, has size <blockSize>.  The details of the client's file
    follow:

      <rolling> <md5>
	The 32-bit rolling checksum and the 64-bit md5 checksum, in
	hexadecimal, for one block.  There is one such line for each
	block of the client's file, including any partial final block.
	That's ceiling(<size>/<blockSize>) lines total.

      .
	End of client's file details.

  S <file> <tag> <date> <cksum>
    Update the existing checked out file <file> to the specified
    version.  The version of the existing file is not known, but
    its checksum is <cksum>.  Checkout mode only.

  s <file> <tag> <date> <revNum> <cksum>
    Update the existing checked out file <file> to the specified
    version.  The client is believed to have version <revNum>
    of the file, and the client file's md5 checksum is <cksum>.
    This command is used when updating a file that was last updated
    by an older version of CVSup, which didn't yet record revDates in
    the "checkouts" files.  Checkout mode only.

  U <file> <tag> <date> <revNum> <revDate>
    Update the existing checked out file <file> to the specified
    version.  The client currently has version <revNum> of the file.
    The date associated with the revision in the RCS file should
    be <revDate>.  Checkout mode only.

  V <file>
    Update the RCS file <file>.  CVS mode only.  The details of the
    client's version follow:

      B <revNum>
	Default branch is <revNum>.

      b
	Default branch is empty.

      D
	List of client deltas follows:

	  <revNum> <date>
	    Client has a delta <revNum> with the date <date>.

	  .
	    End of delta list.

      E <expand>
	Default keyword expansion is <expand>.

      T
	List of client tags follows:

	  <tag> <revNum>
	    Client has a tag <tag>:<revNum>.

	  .
	    End of tag list.
      .
	End of client RCS file details.

  X <file>
    Send the entire file <file> as a fixup.  CVS mode only.

  Y <file> <tag> <date>
    Send the specified version of the file <file> in its entirety, as a
    fixup.  Checkout mode only.

File Differ -> Updater:

  A <file> <attr>
    Receive the entire file <file>, and set its attributes to
    <attr>.  The file data follows verbatim, with the number of
    bytes given by the size specified in the attributes.  After
    the data comes a line containing one of the following:

      .
	The file was sent successfully.

      .<
	The file unexpectedly got shorter.  The data sent was padded
	with NUL characters.

    Finally there is a line specifying what the final MD5 checksum of
    the updated file should be:

      5 <cksum>

    Note:  If the file grew during the transfer, the extra characters
    are simply ignored until the next time an update is performed.

  a <file> <attr>
    Identical to "A", but put the file in the Attic.  CVS mode only.

  C <file> <tag> <date> <revNum> <revDate> <attr>
    Receive an entire checked out version of <file>.  Its revision
    number is <revNum>, and it corresponds to the version specified
    by <tag> and <date>.  The date of the delta is <revDate>.  The
    corresponding RCS file has attributes of <attr>.  Checkout mode
    only.  The text of the checked out version follows, with any
    leading "." on a line transformed into "..".  The text is
    terminated by a line containing one of the following:

      .
	End of the text.

      .+
	End of the text, but suppress the newline at the end of the last
	line.

    Finally there is a line specifying what the final MD5 checksum of
    the updated file should be:

      5 <cksum>

  c <file> <tag> <date> <attr>
    Note that the specified version of <file> is dead.  The
    corresponding RCS file has attributes of <attr>.  Checkout
    mode only.

  D <file>
    Delete the specified file, whether it is checked out, live, or in
    the Attic.

  E <file> <command> [<args>]
    Append <command> to the list of shell commands to be executed
    after the next file update, if the update is successful.
    <command> may contain "%s" escapes, which will be replaced by
    the pathname of <file> on the client.  <file> is exactly the
    name of the affected file, relative to the prefix directory;
    if the file is checked out or in the Attic, that is already
    reflected in the name.  Note that any "E" commands immediately
    precede the associated file update command for <file>.  The
    client defers executing them until the file update has succeeded.

  H <file> <linkTo>
    Create a hard link named <file> which is a link to <linkTo>, if
    such a link does not already exist live.  CVS mode only.

  h <file> <linkTo>
    Create a hard link named <file> which is a link to <linkTo>, if
    such a link does not already exist dead.  CVS mode only.

  I <dir>
    Create a new directory named <dir>, and add its DirDown entry to
    the list file.  CVS mode only.

  i <dir>
    Remove the DirDown list file entry for the directory <dir>.  CVS
    mode only.

  J <dir> <attr>
    Set the attributes for directory <dir> to <attr>, and update its
    DirUp list file entry.  CVS mode only.

  j <dir>
    Remove the directory <dir>, and delete its DirUp list file
    entry.  CVS mode only.

  L <file> <attr>
    Update the list file information for the live RCS file <file>.
    CVS mode only.

  l <file> <attr>
    Update the list file information for the dead RCS file <file>.
    CVS mode only.

  N <file> <attr>
    Create or update a node <file> with attributes <attr>.  CVS mode
    only

  n <file> <attr>
    Like "N" except that the node is in the Attic.  CVS mode only.

  R <file> <attr>
    Like "A" except that the file already exists on the client.

  r <file> <attr> <blockSize> <cksum>
    Edit the <file> using the rsync algorithm with a block size of
    <blockSize>, and set its attributes to <attr>.  After editing,
    the file's MD5 checksum should be <cksum>.  The rsync directives
    to construct the new version of the file follow:

      First comes some text, escaped and terminated as described
      under the "C" command, to write to the beginning of the file.

      Next comes 0 or more chunks, each describing a range of
      consecutive blocks from the original file to copy to the end
      of the new file, and some text to write after that.  In each
      chunk, the block range comes first, followed by the escaped
      text:

	<blockStart> <blockCount>
	  Copy <blockCount> rsync blocks from the original file,
	  beginning with block number <blockStart>.  Blocks are
	  numbered from 0.

	<escaped text>
	  Text, escaped as described under the "C" command.

      Finally comes the end marker:

	.
	  End of rsync directives.

  T <file> <tag> <date> <revNum> <revDate> <attr>
    Update the list file information for the live checked out file
    <file>.  The client's version has revision number <revNum>, which
    corresponds to the version specified by <tag> and <date>.  The
    date associated with the delta is <revDate>.  The corresponding
    RCS file has attributes of <attr>.  Checkout mode only.

  U <file> <tag> <date> <revNum> <fromAttic> <logLines> <expand> <attr> <cksum>
    Edit the live checked out file <file> to bring it up to date for
    <tag> and <date>.  The revision number that the client initially
    has is <revNum>. <fromAttic> is "1" or "0", depending on whether
    the RCS file is in the Attic. <logLines> specifies the number of
    "Log" keyword lines that need to be deleted before editing, in
    order to unexpand that keyword properly. <expand> specifies the
    RCS keyword expansion mode that should be used. <attr> gives the
    attributes of the corresponding RCS file.  After editing, the
    checked out file should have a checksum of <cksum>.  Checkout mode
    only.  The editing commands follow:

      D <revNum> <diffBase> <revDate> <author>
	Add a delta.  See the description under the "V" command.

      .
	End of editing commands.

  u <file> <tag> <date> <attr>
    Delete the checked out file <file>, because it has become dead.
    Update the list file to note that the client is current for have
    the version specified by <tag> and <date>, and that the RCS file's
    attributes are <attr>.  Checkout mode only.

  V <file> <attr> <options> <cksum>
    Edit the RCS file <file>, make it live, and set its attributes to
    <attr>.  <options> specifies some details of the RCS file format.
    After editing, the RCS file should have a checksum of <cksum>.  CVS
    mode only.  The editing commands follow:

      B <revNum>
	Set the default branch to <revNum>.

      b
	Clear the default branch.

      D <revNum> <diffBase> <revDate> <author>
	Add a delta to produce revision <revNum>.  <diffBase> is the
	revision number that the diffs must be applied to, in order to
	produce the new revision.  If <diffBase> is ".", then the full
	text of the new revision is attached, rather than a set of
	diffs.  <revDate> and <author> specify the date and author of
	the new revision.  The text associated with the delta follows:

	  L
	    The log text follows, with any leading "." in a line
	    transformed into "..".  The log text is terminated as
	    described for the "C" command.

	  N <key>
            Append a "newphrase" with the given key to the newphrases
            associated with the delta tree.  The words of the
            newphrase follow:

	      W <word>
		Append the word to the newphrase.

	      S
                Append a string to the newphrase.  The string follows,
                with any leading "." in a line transformed into "..".
                The string is terminated as described for the "C"
                command.

	      .
		End of the "newphrase".

	  n <key>
	    Like "N", but the newphrases are associated with the text
	    of the delta, rather than with the tree.

	  S <state>
	    Set the state of the revision to <state>.

	  T
	    The delta text follows, with any leading "." in a line
	    transformed into "..".  The delta text is terminated as
	    described for the "C" command.  The delta text is a set of
	    diffs relative to <diffBase>, or the full text if <diffBase>
	    is ".".

	  .
	    End of the delta.

      d <revNum>
	Delete the specified revision.

      E <expand>
	Change the default RCS keyword expansion mode to <expand>.

      T <tag> <revNum>
	Add a new tag <tag>:<revNum>.

      t <tag> <revNum>
	Delete the tag <tag>:<revNum>.

      .
	End of editing commands.

  v <file> <attr> <options> <cksum>
    Like "V", but put the file in the Attic after editing it.  CVS mode
    only.

  X <file> <attr>
    Receive the live RCS file <file> in its entirety, as a fixup.
    Set its attributes to <attr>.  The data follows, in the same
    format as for the "A" command.  CVS mode only.

  x <file> <attr>
    Like "X", but put the file into the Attic.  CVS mode only.

  Y <file> <tag> <date> <revNum> <revDate> <attr>
    Receive a checked out version of <file> in its entirety, as a
    fixup.  The received version has revision number <revNum>,
    which corresponds to <tag> and <date>.  The date of the revision
    is <revDate>, and the corresponding RCS file has attributes of
    <attr>.  The contents of the revision follow, in the same form
    as for the "C" command.  Checkout mode only.

  Z <file> <attr> <pos>
    Append some new data to the end of the existing file <file>,
    and set its attributes to <attr>.  The data should be written
    to the file starting at file offset <pos>, which should be
    exactly at the end of the file.  Exactly n bytes of data follow,
    where n is the size attribute minus <pos>.  After the data
    comes a terminating line, as in the "A" command.  The number
    of bytes n can be 0, in which case the file's attributes are
    simply updated.

  ! <message>
    Log the given warning message from the server.