[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

RE: [RFC] 'External' and 'Switched': common ground

From: Bert Huijben <bert_at_vmoo.com>
Date: Fri, 20 Aug 2010 11:42:17 -0700

> -----Original Message-----
> From: Julian Foad [mailto:julian.foad_at_wandisco.com]
> Sent: vrijdag 20 augustus 2010 10:54
> To: dev_at_subversion.apache.org
> Subject: [RFC] 'External' and 'Switched': common ground
>
> What's the idea?
>
>
> External means Switched
> =======================
>
> Well, not quite! But at the WC layer they have a lot in common. Let's
> take advantage of it.
>
> In both cases:
>
> * An 'external' or 'switched' WC node is a file or a directory (tree).
>
> * An 'external' or 'switched' WC node is an immediate child of a
> versioned WC directory. [3]
>
> * An 'external' or 'switched' WC node is attached to a repository
> location other than the one implied by its WC parent directory.

An external directory is not connected to it's parent. (You don't get it in the list of children using entries and/or nodes). To the parent it is just an unversioned directory, but if you look inside you find a working copy root that might (accidentally) be from the same repository. And it can be a few levels deeper than just an immediate child.

File externals are switched files; nothing more and nothing less... But we added a lot of plastering over that fact to hide the implementation and to make our code hard to maintain...

> * In and inside itself, an 'external' or 'switched' file or tree is
> indistinguishable from any other WC file or tree. [4]

A directory external is a working copy root. A file external isn't.

> * Only its relationship to its WC parent directory is 'special'. The
> only operations that may see it as different are those that start at
> a higher level (outside the node) and recurse or look into it, and
> those that start inside the node and walk up the tree towards the WC
> root.

For external files, the definition can be a few directories up the tree. Which makes it a special child that needs that special recording in the BASE tree (or before that on the entry) to handle it different than normal switched files

An external directory is just a working copy if you look at it directly.

> * Client operations treat the node as part of its parent WC in some
> ways, and treat it as special in other ways, depending on the
> command and on user-specified options.

Yes,

Well, there are no real operations on external directories as they are just unversioned to the parent working copy.

External files... specialized code... specialized code... specialized code.

External files are part of the parent working copy, so things like (recursive) locks and things apply on them. But these locks don't apply on directory externals as they are in a different working copy.

> By defining 'External' and 'Switched' in terms of their common ground
> and their differences, we can reduce complexity and clarify the issues
> that are currently obscure. This could be especially helpful at the
> moment for designing their WC representation.

Switched nodes are part of the working copy.
File externals are part of the working copy

Directory externals are itself a working copy, but aren't as seen from the parent working copy.

I think it will be very hard to explain these in the same way.

> How should we represent external files and external dirs in the WC in a
> unified manner? Do we need to explicitly mark them as 'external'? What
> differences in behaviour should 'external' nodes and 'switched' nodes
> exhibit within the WC?

One option would be to pull file externals out of their parent working copy and make them their own working copy root. We can handle this in WC-DB. (Create a different wcroot id, defining the file to be its own root. Fix the update handling and we are done).

>
>
> Differences in WC State
> =======================
>
> This table documents the differences in WC state at a high level.
>
> +----------------------+----------------------+----------------------+
> | | switched | external |
> +----------------------+----------------------+----------------------+
> | | | |
> | WC path affected | Existing child | Non-existent child |

File external: existing child.
> | | | |
> | Target URL | Same repo | Same or other repo |
File external: same repo
> | | | |
> | Pinned to a revision | No [2] | Optional; recorded |
> | | | in 'svn:externals' |
File external: recorded on the node itself.
(And it's currently impossible to find the svn:externals definition for a specific external without looking at all it's ancestor directories)

> | | | |
> | Initial depth | Set by "switch" cmd | Infinity |
> | | | |
> +----------------------+----------------------+----------------------+
>
> ### Anything else?
>
>
> Differences in Client Commands (Current behaviour)
> ==================================================
>
> The following differences occur when a command encounters an 'external'
> or 'switched' node during its operation. This table is to document the
> current (1.6.x) behaviour.
>
> ### We'll need some test scripts to help gather this data.
>
> +----------------------+----------------------+----------------------+
> | | switched | external |
> +----------------------+----------------------+----------------------+
> | | | |
> | recursive descent, | yes | optional |
> | in general | | |
> | | | |
> | status | report & descend | report [& descend] |
> | | | |
> | propget/list/etc. | ? | ? |
yes | no
> | | | |
> | diff | ? | ? |
yes | no
> | | | |
> | commit | descend | [descend?] |
Yes | no (except for some buggy behavior relying on passing a limiting depth)
> | | | |
> | update | ? | ? |
Yes | optional
> | | | |
> | switch | Can switch a WC root | No UI exists for an |
> | | but it's not then | external outside |
> | | recorded as such. | of a WC. |
(externals definitions are normally updated after a switch by handling the svn:externals property changes)
> | | | |
> | ... | | |

File externals are in all these cases handled as switch.
> | | | |
> +----------------------+----------------------+----------------------+
>
> We ought to think about the UI and design a set of useful and consistent
> behaviours. But that's out of scope here; this document focuses on the
> WC layer.
>
>
> What to Do About It?
> ====================
>
> The first practical step I can see is to write a test suite utility for
> creating a WC with all the possible states in it, and first writing
> tests that just expose the current behaviour variations, and then
> deciding which of those are intended and which are bugs or awaited
> features.
>
> Any other suggestions on how to make some practical use of this idea?
>
>
> Footnotes
> =========
>
> [2] The ability for "svn update -rX" to "pin" that part of the WC at
> rX has been requested by users and seems like a reasonable (clean,
> moderately useful) feature.

I wouldn't want just using -r to pin the revision, but I certainly like the idea of a --pin option. And if we generalize this we can also use it to deny commits on pinned nodes. (Which is currently a feature request for file externals with a fixed revision)

> [3] You can "svn switch" a WC root, and the whole WC is then based on
> the new location, but it is not normally regarded as being in a
> "switched" state. The concept of a node being in a "switched"
> state is only meaningful with respect to the expected location as
> determined from the node's parent directory in the same WC. (The
> "svnversion" command has an option to specify an expected location
> so that it can report the status of the whole WC as "switched"
> relative to that specified location.)
>
> [4] A possible exception is that "update" should obey the "pinned
> revision number" if present. But that need not necessarily be an
> exception: we might choose to define that functionality on all WC
> nodes but only use it on 'external' nodes.

See my answer on [2]. I like this generalized pinned idea as option to replace our checks on file externals.

(First thing that comes to mind is how it would interact with 'svn switch on some parent')

        Bert
Received on 2010-08-20 20:43:28 CEST

This is an archived mail posted to the Subversion Dev mailing list.