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.
* In and inside itself, an 'external' or 'switched' file or tree is
indistinguishable from any other WC file or tree. [4]
* 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.
* 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.
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.
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?
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 |
| | | |
| Target URL | Same repo | Same or other repo |
| | | |
| Pinned to a revision | No [2] | Optional; recorded |
| | | in 'svn:externals' |
| | | |
| 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. | ? | ? |
| | | |
| diff | ? | ? |
| | | |
| commit | descend | [descend?] |
| | | |
| update | ? | ? |
| | | |
| switch | Can switch a WC root | No UI exists for an |
| | but it's not then | external outside |
| | recorded as such. | of a WC. |
| | | |
| ... | | |
| | | |
+----------------------+----------------------+----------------------+
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.
[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.
- Julian
