readme

linux subdivision ying gai ke yi le ba

     Oh Most High and Fragrant Emacs, please be in -*- text -*- mode!

This is the library described in the section "The working copy
management library" of svn-design.texi.  It performs local operations
in the working copy, tweaking administrative files and versioned data.
It does not communicate directly with a repository; instead, other
libraries that do talk to the repository call into this library to
make queries and changes in the working copy.


The Problem We're Solving.
==========================

The working copy is arranged as a directory tree, which, at checkout,
mirrors a tree rooted at some node in the repository.  Over time, the
working copy accumulates uncommitted changes, some of which may affect
its tree layout.  By commit time, the working copy's layout could be
arbitrarily different from the repository tree on which it was based.

Furthermore, updates/commits do not always involve the entire tree, so
it is possible for the working copy to go a very long time without
being a perfect mirror of some tree in the repository.


One Way We're Not Solving It.
=============================

Updates and commits are about merging two trees that share a common
ancestor, but have diverged since that ancestor.  In real life, one of
the trees comes from the working copy, the other from the repository.
But when thinking about how to merge two such trees, we can ignore the
question of which is the working copy and which is the repository,
because the principles involved are symmetrical.

Why do we say symmetrical?

It's tempting to think of a change as being either "from" the working
copy or "in" the repository.  But the true source of a change is some
committer -- each change represents some developer's intention toward
a file or a tree, and a conflict is what happens when two intentions
are incompatible (or their compatibility cannot be automatically
determined).

It doesn't matter in what order the intentions were discovered --
which has already made it into the repository versus which exists only
in someone's working copy.  Incompatibility is incompatibility,
independent of timing.

In fact, a working copy can be viewed as a "branch" off the
repository, and the changes committed in the repository *since* then
represent another, divergent branch.  Thus, every update or commit is
a general branch-merge problem:

   - An update is an attempt to merge the repository's branch into the
     working copy's branch, and the attempt may fail wholly or
     partially depending on the number of conflicts.

   - A commit is an attempt to merge the working copy's branch into
     the repository.  The exact same algorithm is used as with
     updates, the only difference being that a commit must succeed
     completely or not at all.  That last condition is merely a
     usability decision: the repository tree is shared by many
     people, so folding both sides of a conflict into it to aid
     resolution would actually make it less usable, not more.  On the
     other hand, representing both sides of a conflict in a working
     copy is often helpful to the person who owns that copy.

So below we consider the general problem of how to merge two trees
that have a common ancestor.  The concrete tree layout discussed will
be that of the working copy, because this library needs to know
exactly how to massage a working copy from one state to another.


Structure of the Working Copy
=============================

Working copy meta-information is stored in .svn/ subdirectories,
analogous to CVS/ subdirs:

  .svn/format                   /* Contains wc adm format version. */
       README                   /* Just explains this is a working copy. */
       repository               /* Where this stuff came from. */
       entries                  /* Various adm info for each directory entry */
       dir-props                /* Working properties for this directory */
       dir-prop-base            /* Pristine properties for this directory */
       lock                     /* Optional, tells others this dir is busy */
       log                      /* Ops log (for rollback/crash-recovery) */
       text-base/               /* Pristine repos revisions of the files... */
            foo.c.svn-base
            bar.c.svn-base
            baz.c.svn-base
       props/                   /* Working properties for files in this dir */
            foo.c.svn-work         /* Stores foo.c's working properties
            bar.c.svn-work
            baz.c.svn-work
       prop-base/               /* Pristine properties for files in this dir */
            foo.c.svn-base         /* Stores foo.c's pristine properties */
            bar.c.svn-base
            baz.c.svn-base
       wcprops/                 /* special 'wc' props for files in this dir*/
            foo.c.svn-work
            bar.c.svn-work
            baz.c.svn-work
       dir-wcprops              /* 'wc' props for this directory. */
       tmp/                     /* Local tmp area */
            ./                     /* Adm files are written directly here. */
            text-base/             /* tmp area for base files */
            prop-base/             /* tmp area for base props */
            props/                 /* tmp area for props */

`format'

   Says what version of the working copy adm format this is (so future
   clients can be backwards compatible easily).

   Also, the presence of this file means that the entire process of
   creating the adm area was completed, because this is always the
   last file created.  Of course, that's no guarantee that someone
   didn't muck things up afterwards, but it's good enough for
   existence-checking.

`README'

   If someone doesn't know what a Subversion working copy is, this
   will tell them how to find out more about Subversion.

`repository'

   Where this dir came from (syntax TBD).

`entries':

   This file holds revision numbers and other information for this
   directory and its files, and records the presence of subdirs (but
   does not record much other information about them, as the subdirs
   do that themselves).

   The entries file contains an XML expression like this:

      <wc-entries xmlns="http://subversion.tigris.org/xmlns/blah">
        <entry ancestor="/path/to/here/in/repos" revision="5"/>
            <!-- no name in above entry means it refers to the dir itself -->
        <entry name="foo.c" revision="5" text-time="..." prop-time="..."/>
        <entry name="bar.c" revision="5" text-time="blah..." checksum="blah"/>
        <entry name="baz.c" revision="6" text-time="..." prop-time="..."/>
        <entry name="X" new="true" revision="0"/>
        <entry name="Y" new="true" ancestor="ancestor/path/Y" revision="3"/>
        <entry name="qux" kind="dir" />
      </wc-entries>

   Where:

      1. `kind' defaults to "file".

      2. `revision' defaults to the directory's revision (in the
         directory's own entry, the revision may not be omitted).

      3. `text-time' is *required* whenever the `revision' attribute
         is changed.  They are inseparable concepts; the textual
         timestamp represents the last time the working file was known
         to be exactly equal to the revision it claims to be.
         `prop-time' is a separate timestamp for the file's
         properties, with the same relative meaning.

         In the ideal world, when a file is updated to be perfectly in
         sync with some repository revision, both the `text-time' and
         `prop-time' timestamps would be identical.  In the real
         world, however, they're going to be only very close.
         Remember that the *only* reason we track timestamps in the
         entries file is to make it easier to detect local
         modifications.  Thus a "locally modified" check must examine
         both timestamps if they both exist.

      4. `ancestor' defaults to the directory's ancestor, prepended
         (according to the repository's path conventions) to the entry
         name in question.  This directory's ancestor may not be
         omitted, but conversely, subdirectories may not record
         ancestry information in their parent's entries file.



   When a file or dir is added, that is recorded here too, in the
   following manner:

      1. Added files are recorded with the "new='true'" flag; if they
         are truly new, their initial revision is 0, otherwise their
         ancestry is recorded (see files X and Y in the example).

      2. Added dirs get the "new='true'" flag too, but they record
         their own ancestry.

   Child directories of the current directory are recorded here, but
   their ancestry information is omitted.  The idea is to make the
   child's existence known to the current directory; all other
   information about the child directory is stored in its own .svn/
   subdir.

`dir-props'

   Properties for this directory.  These are the "working" properties
   that may be changed by the user.

   For now, this file is in svn hashdump format, because it's
   convenient and its performance is good enough for now.  May move to
   Berkeley DB if properties ever get that demanding.  XML is another
   possibility -- it's less efficient, disk-wise, but on the other
   hand its easy to parse it streamily, unlike hashdump format, which
   generally results in a complete data structure in memory before you
   can do anything at all.

`dir-prop-base'

  Same as `dir-props', except this is the pristine copy;  analogous to
  the "text-base" revisions of files.  The last up-to-date copy of the
  directory's properties live here. 

`lock'

   Present iff some client is using this .svn/ subdir for anything.
   kff todo: I think we don't need read vs write types, nor
   race-condition protection, due to the way locking is called.  We'll
   see, though.

`log'

   This file (XML format) holds a log of actions that are about to be
   done, or are in the process of being done.  Each action is of the
   sort that, given a log entry for it, one can tell unambiguously
   whether or not the action was successfully done.  Thus, in
   recovering from a crash or an interrupt, the wc library reads over