notes/anchors_and_targets.txt

   1 Of Anchors and Targets
   2 ======================
   3
   4 Definitions (contextually bound, of course):
   5
   6    anchor - The name given to the directory at which an editor is
   7             rooted.  That is to say, the directory baton returned by
   8             editor->replace_root() is meant to describe the anchor
   9             directory.
  10
  11    editor - A function vtable containing methods used to describe
  12             changes to a directory tree.  [see include/svn_delta.h]
  13
  14    target - The file(s) or directory(s), relative to the anchor,
  15             designated as the actual intended subject of a given
  16             operation (update, commit, etc.).  This, in practice, can
  17             be NULL if the anchor itself is the intended subject.
  18
  19
  20 A Little Background
  21
  22    The concept of anchors and targets trickled out of the brains of
  23    C. Michael Pilato and Ben Collins-Sussman during the course of
  24    debugging the `svn up' command.  Updates are not atomic, so each
  25    item-to-be-updated ("update target") passed to this command gets
  26    its own update procedure.  The update procedure involves describing
  27    the update target in the working copy to the repository using a
  28    "reporter".  The repository then, using an editor, modifies the
  29    update target in the working copy to look exactly as it does in
  30    the repository (usually in the youngest revision, but optionally,
  31    at any revision snapshot of the tree).
  32
  33    At that time, if the update target was a directory, the editor
  34    handed to the repository was rooted at that directory.  If the
  35    update target was a file, the editor was rooted at the parent
  36    directory containing that file.
  37
  38    It became apparent rather quickly that the orderly design of the
  39    editor apparatus required more precise usage in order to get the
  40    desired results.  Some of the problems in the original usage are as
  41    follows:
  42
  43      * For directory updates, it was impossible for the driver of the
  44        editor to request that the update target be deleted.  The
  45        editor's delete_entry() receives as parameters a directory
  46        baton, and the name of an entry in that directory to be
  47        deleted.  If an editor is rooted at the update target, it is
  48        impossible for there to exist a directory baton describing its
  49        parent, and therefore no way to delete it as a named entry in
  50        its parent.  Clearly, this limitation to the update command was
  51        unacceptable.
  52
  53     * For file updates, having an editor rooted at the parent
  54       directory without supplying addition information to the editor's
  55       driver meant that if siblings of the update target were also
  56       "out of date" with respect to the update request, they too would
  57       be affected by the editor drive.  Clearly it was unacceptable to
  58       have items in the working copy modified that should have been
  59       considered outside the scope of the requested update operation.
  60
  61    And so the notion of anchors and targets was born.
  62
  63
  64 The Implementation
  65
  66    Anchors had been present all along as the root of the editor drive,
  67    but were not going to be chosen in a way that expanded the scope of
  68    the knowledge that the editor has about the tree.  Targets became
  69    the "additional information" passed to the editor driver to
  70    restrict the scope of the editor's legitimate activity to only the
  71    file or directory intended as the focus of the update.
  72
  73    A new function, svn_wc_get_actual_target() was created and given
  74    the responsibility of deciding, given an update target path (and
  75    access to the working copy administrative directory), what the
  76    actual anchor and target of the editor drive would be.  The rules
  77    are fairly straightforward:
  78
  79      * For directory updates, if the parent directory of the update
  80        target is a valid place to root an editor, that parent
  81        directory becomes the anchor, and the update target itself
  82        becomes the target.  If the parent directory is not a valid
  83        place to root an editor, the update target becomes both the
  84        anchor and the target (the target is passed as NULL).  Validity
  85        of the parent directory in the working copy is determined by
  86        whether or not it is also the update target's parent directory
  87        in the repository.
  88
  89      * For file updates, the update target file's parent directory is
  90        the anchor, and the file itself is the target.
  91
  92    Shortly after this was implemented for updates, it became apparent
  93    that commits needed the same sort of ideology in place.  That was
  94    implented as well.
  95
  96
  97 The Status Quo
  98
  99    There currently exist a few kinks in the system, not (in my
 100    opinion) in the theoretical design of the anchor/target scheme, but
 101    in their handling as those items get passed around through the
 102    working copy, RA layer, and filesystem modules.  Some complaints
 103    have been raised about the theoretical design of the anchor/target
 104    scheme, however, such as the need to examine the a directory
 105    target's parent, and perhaps a handful of unspecified
 106    "spidey-sense" warnings.  PLEASE, if you have valid technical
 107    complaints, (re-)voice them in reponse to this mail so they can be
 108    evaluated more closely, offering better solutions if you can.
 109
 110    For example, the editor could be changed so that some flavor of
 111    delete_entry() could delete the item represented by the baton given
 112    it (perhaps, delete_this()).  I believe this to be inelegant.
 113
 114      * The only way to get that baton would be to add or replace the
 115        file or directory, operations which are obviously tied to
 116        entirely different notions.
 117
 118      * The only *required* place for this would be in attempting to
 119        delete a directory whose parent in the working copy was not
 120        also its parent in the repository, which would (in either the
 121        update or the commit case), result in the completely destroyed
 122        working copy.  In the commit case, I suppose this is alright,
 123        but it would certainly be strange for a user who had checked
 124        out a repository subdirectory which has recently been deleted
 125        to run `svn up' and find their working copy missing.
 126
 127      * It requires special handling for the directory that maps
 128        to the root of the repository, which simply cannot be deleted
 129        (theoretical wrongness all over the place).  Currently, the
 130        solution has no "special cases".
 131
 132
 133 In Conclusion
 134
 135    There are likely better ideas out there that never crossed my mind.
 136    Please submit them for review and discussion!  Currently, I suspect
 137    that the most of the bugs in the present system exist because the
 138    distinction of the anchor and target notions is lost when at some
 139    point in the code path they are concatenated back together on the
 140    "server" side (or, some place that doesn't have access to the
 141    working copy module, since I think there are issues in both ra_dav
 142    and ra_local) into a single path.
 143
 144