notes/shelving/shelf-structure.txt

== Storage Structure for Shelving ==


=== Shelving v3 (trunk) ===

In development in trunk (1.12-dev), marked "experimental".

Each shelf-version is stored in an entire copy of the WC. The shelves are
stored in a sibling to the user's WC, at '<WC-root-dir>.shelves'. Inside it:

* .../<encoded-name>.current
  Holds an ASCII-decimal number stating the latest shelf-version of the
  shelf <encoded-name>, followed by a newline character (LF).

* .../<encoded-name>.log
  Holds the 'revision' properties of the shelf, in svn_hash_write2() format
  terminated with "PROPS-END". Created when any revprop is set; need not
  exist.

* .../<encoded-name>-<version>.wc
  Directory holding a shelf-version as a real WC.


=== Shelving v2 ===

Released in Subversion 1.11.0, marked "experimental".

Each shelf has zero or more versions of the change, and exactly one set of
'revision' properties.

* .svn/experimental/shelves/v2
  This subdirectory holds all shelving metadata and data.
  It is created on demand, and never deleted.

* .svn/experimental/shelves/v2/<encoded-name>.current
  Holds an ASCII-decimal number stating the latest shelf-version of the
  shelf <encoded-name>, followed by a newline character (LF).

* .svn/experimental/shelves/v2/<encoded-name>.log
  Holds the 'revision' properties of the shelf, in svn_hash_write2() format
  terminated with "PROPS-END". Created when any revprop is set; need not
  exist.

* .svn/experimental/shelves/v2/<encoded-name>-<version>.d
  Directory holding the metadata and {base,working}{text,props} files for a
  shelf-version. For each shelved WC-relpath <P>:
  - <P>.meta : metadata, serialized in a shelf-v2-specific format
  - <P>.base : the base text (absent for a directory)
  - <P>.work : the working text (absent for a directory)
  - <P>.base-props : the base properties
  - <P>.work-props : the working properties

<encoded-name>: the shelf name as UTF-8, encoded byte-by-byte into
  two-hex-digit pairs, e.g. shelf name 'Az' is encoded as '417f'.

<version>: an ASCII-decimal number, starting at 1


=== Shelving v1 ===

Released in Subversion 1.10.0, marked "experimental".

Shelving only, no 'checkpoints' (versions). Each shelf has an optional log
message.

* .svn/shelves
  This subdirectory holds all shelving metadata and data.
  It is created on demand, and never deleted.

* .svn/shelves/<encoded-name>.patch
  The patch file representing one shelf, preceded by its log message.
  If a log message is not given, the empty string is stored instead. The
  log message is terminated in the same was as in the log message editor:
  a newline, then "--This line, and those below, will be ignored--". Then
  follows a blank line, a line "--This patch was generated by 'svn
  shelve'--", a blank line, then the patch.

<encoded-name>: the shelf name as UTF-8, encoded byte-by-byte into
  two-hex-digit pairs, e.g. shelf name 'Az' is encoded as '417f'.