notes/anchors_and_targets.txt - subversion - Git at Google

 Of Anchors and Targets
 ======================

 Definitions (contextually bound, of course):

    anchor - The name given to the directory at which an editor is
             rooted.  That is to say, the directory baton returned by
             editor->replace_root() is meant to describe the anchor
             directory.

    editor - A function vtable containing methods used to describe
             changes to a directory tree.  [see include/svn_delta.h]

    target - The file(s) or directory(s), relative to the anchor,
             designated as the actual intended subject of a given
             operation (update, commit, etc.).  This, in practice, can
             be NULL if the anchor itself is the intended subject.


 A Little Background

    The concept of anchors and targets trickled out of the brains of
    C. Michael Pilato and Ben Collins-Sussman during the course of
    debugging the `svn up' command.  Updates are not atomic, so each
    item-to-be-updated ("update target") passed to this command gets
    its own update procedure.  The update procedure involves describing
    the update target in the working copy to the repository using a
    "reporter".  The repository then, using an editor, modifies the
    update target in the working copy to look exactly as it does in
    the repository (usually in the youngest revision, but optionally,
    at any revision snapshot of the tree).

    At that time, if the update target was a directory, the editor
    handed to the repository was rooted at that directory.  If the
    update target was a file, the editor was rooted at the parent
    directory containing that file.

    It became apparent rather quickly that the orderly design of the
    editor apparatus required more precise usage in order to get the
    desired results.  Some of the problems in the original usage are as
    follows:

      * For directory updates, it was impossible for the driver of the
        editor to request that the update target be deleted.  The
        editor's delete_entry() receives as parameters a directory
        baton, and the name of an entry in that directory to be
        deleted.  If an editor is rooted at the update target, it is
        impossible for there to exist a directory baton describing its
        parent, and therefore no way to delete it as a named entry in
        its parent.  Clearly, this limitation to the update command was
        unacceptable.

     * For file updates, having an editor rooted at the parent
       directory without supplying addition information to the editor's
       driver meant that if siblings of the update target were also
       "out of date" with respect to the update request, they too would
       be affected by the editor drive.  Clearly it was unacceptable to
       have items in the working copy modified that should have been
       considered outside the scope of the requested update operation.

    And so the notion of anchors and targets was born.


 The Implementation

    Anchors had been present all along as the root of the editor drive,
    but were not going to be chosen in a way that expanded the scope of
    the knowledge that the editor has about the tree.  Targets became
    the "additional information" passed to the editor driver to
    restrict the scope of the editor's legitimate activity to only the
    file or directory intended as the focus of the update.

    A new function, svn_wc_get_actual_target() was created and given
    the responsibility of deciding, given an update target path (and
    access to the working copy administrative directory), what the
    actual anchor and target of the editor drive would be.  The rules
    are fairly straightforward:

      * For directory updates, if the parent directory of the update
        target is a valid place to root an editor, that parent
        directory becomes the anchor, and the update target itself
        becomes the target.  If the parent directory is not a valid
        place to root an editor, the update target becomes both the
        anchor and the target (the target is passed as NULL).  Validity
        of the parent directory in the working copy is determined by
        whether or not it is also the update target's parent directory
        in the repository.

      * For file updates, the update target file's parent directory is
        the anchor, and the file itself is the target.

    Shortly after this was implemented for updates, it became apparent
    that commits needed the same sort of ideology in place.  That was
    implented as well.


 The Status Quo

    There currently exist a few kinks in the system, not (in my
    opinion) in the theoretical design of the anchor/target scheme, but
    in their handling as those items get passed around through the
    working copy, RA layer, and filesystem modules.  Some complaints
    have been raised about the theoretical design of the anchor/target
    scheme, however, such as the need to examine the a directory
    target's parent, and perhaps a handful of unspecified
    "spidey-sense" warnings.  PLEASE, if you have valid technical
    complaints, (re-)voice them in reponse to this mail so they can be
    evaluated more closely, offering better solutions if you can.

    For example, the editor could be changed so that some flavor of
    delete_entry() could delete the item represented by the baton given
    it (perhaps, delete_this()).  I believe this to be inelegant.

      * The only way to get that baton would be to add or replace the
        file or directory, operations which are obviously tied to
        entirely different notions.

      * The only *required* place for this would be in attempting to
        delete a directory whose parent in the working copy was not
        also its parent in the repository, which would (in either the
        update or the commit case), result in the completely destroyed
        working copy.  In the commit case, I suppose this is alright,
        but it would certainly be strange for a user who had checked
        out a repository subdirectory which has recently been deleted
        to run `svn up' and find their working copy missing.

      * It requires special handling for the directory that maps
        to the root of the repository, which simply cannot be deleted
        (theoretical wrongness all over the place).  Currently, the
        solution has no "special cases".


 In Conclusion

    There are likely better ideas out there that never crossed my mind.
    Please submit them for review and discussion!  Currently, I suspect
    that the most of the bugs in the present system exist because the
    distinction of the anchor and target notions is lost when at some
    point in the code path they are concatenated back together on the
    "server" side (or, some place that doesn't have access to the
    working copy module, since I think there are issues in both ra_dav
    and ra_local) into a single path.
	Of Anchors and Targets
	======================

	Definitions (contextually bound, of course):

	anchor - The name given to the directory at which an editor is
	rooted. That is to say, the directory baton returned by
	editor->replace_root() is meant to describe the anchor
	directory.

	editor - A function vtable containing methods used to describe
	changes to a directory tree. [see include/svn_delta.h]

	target - The file(s) or directory(s), relative to the anchor,
	designated as the actual intended subject of a given
	operation (update, commit, etc.). This, in practice, can
	be NULL if the anchor itself is the intended subject.


	A Little Background

	The concept of anchors and targets trickled out of the brains of
	C. Michael Pilato and Ben Collins-Sussman during the course of
	debugging the `svn up' command. Updates are not atomic, so each
	item-to-be-updated ("update target") passed to this command gets
	its own update procedure. The update procedure involves describing
	the update target in the working copy to the repository using a
	"reporter". The repository then, using an editor, modifies the
	update target in the working copy to look exactly as it does in
	the repository (usually in the youngest revision, but optionally,
	at any revision snapshot of the tree).

	At that time, if the update target was a directory, the editor
	handed to the repository was rooted at that directory. If the
	update target was a file, the editor was rooted at the parent
	directory containing that file.

	It became apparent rather quickly that the orderly design of the
	editor apparatus required more precise usage in order to get the
	desired results. Some of the problems in the original usage are as
	follows:

	* For directory updates, it was impossible for the driver of the
	editor to request that the update target be deleted. The
	editor's delete_entry() receives as parameters a directory
	baton, and the name of an entry in that directory to be
	deleted. If an editor is rooted at the update target, it is
	impossible for there to exist a directory baton describing its
	parent, and therefore no way to delete it as a named entry in
	its parent. Clearly, this limitation to the update command was
	unacceptable.

	* For file updates, having an editor rooted at the parent
	directory without supplying addition information to the editor's
	driver meant that if siblings of the update target were also
	"out of date" with respect to the update request, they too would
	be affected by the editor drive. Clearly it was unacceptable to
	have items in the working copy modified that should have been
	considered outside the scope of the requested update operation.

	And so the notion of anchors and targets was born.


	The Implementation

	Anchors had been present all along as the root of the editor drive,
	but were not going to be chosen in a way that expanded the scope of
	the knowledge that the editor has about the tree. Targets became
	the "additional information" passed to the editor driver to
	restrict the scope of the editor's legitimate activity to only the
	file or directory intended as the focus of the update.

	A new function, svn_wc_get_actual_target() was created and given
	the responsibility of deciding, given an update target path (and
	access to the working copy administrative directory), what the
	actual anchor and target of the editor drive would be. The rules
	are fairly straightforward:

	* For directory updates, if the parent directory of the update
	target is a valid place to root an editor, that parent
	directory becomes the anchor, and the update target itself
	becomes the target. If the parent directory is not a valid
	place to root an editor, the update target becomes both the
	anchor and the target (the target is passed as NULL). Validity
	of the parent directory in the working copy is determined by
	whether or not it is also the update target's parent directory
	in the repository.

	* For file updates, the update target file's parent directory is
	the anchor, and the file itself is the target.

	Shortly after this was implemented for updates, it became apparent
	that commits needed the same sort of ideology in place. That was
	implented as well.


	The Status Quo

	There currently exist a few kinks in the system, not (in my
	opinion) in the theoretical design of the anchor/target scheme, but
	in their handling as those items get passed around through the
	working copy, RA layer, and filesystem modules. Some complaints
	have been raised about the theoretical design of the anchor/target
	scheme, however, such as the need to examine the a directory
	target's parent, and perhaps a handful of unspecified
	"spidey-sense" warnings. PLEASE, if you have valid technical
	complaints, (re-)voice them in reponse to this mail so they can be
	evaluated more closely, offering better solutions if you can.

	For example, the editor could be changed so that some flavor of
	delete_entry() could delete the item represented by the baton given
	it (perhaps, delete_this()). I believe this to be inelegant.

	* The only way to get that baton would be to add or replace the
	file or directory, operations which are obviously tied to
	entirely different notions.

	* The only required place for this would be in attempting to
	delete a directory whose parent in the working copy was not
	also its parent in the repository, which would (in either the
	update or the commit case), result in the completely destroyed
	working copy. In the commit case, I suppose this is alright,
	but it would certainly be strange for a user who had checked
	out a repository subdirectory which has recently been deleted
	to run `svn up' and find their working copy missing.

	* It requires special handling for the directory that maps
	to the root of the repository, which simply cannot be deleted
	(theoretical wrongness all over the place). Currently, the
	solution has no "special cases".


	In Conclusion

	There are likely better ideas out there that never crossed my mind.
	Please submit them for review and discussion! Currently, I suspect
	that the most of the bugs in the present system exist because the
	distinction of the anchor and target notions is lost when at some
	point in the code path they are concatenated back together on the
	"server" side (or, some place that doesn't have access to the
	working copy module, since I think there are issues in both ra_dav
	and ra_local) into a single path.