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 as 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 does 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.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sat Oct 21 14:36:41 2006