| 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 lives somewhere inside a | |
| versioned WC directory. (A switched node is always an immediate | |
| child of a versioned directory [3]. An external dir can be at a | |
| deeper level, with one or more levels of unversioned directory in | |
| between, but that doesn't currently work for file externals.) | |
| * 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 (file) | external (dir) | | |
| +----------------------+----------------------+----------------------+----------------------+ | |
| | | | | | | |
| | WC path affected | Existing child | Non-existent child | Non-existent child | | |
| | | of a versioned dir | of a versioned dir | or grandchild etc. | | |
| | | | | of a versioned dir | | |
| | | | | | | |
| | Resulting WC | Same WC | Same WC | Separate WC | | |
| | | | | | | |
| | Target URL | Same repo | Same repo | Same or other repo | | |
| | | | | | | |
| | Pinned to a revision | No [2] | Optional; recorded | Optional; recorded | | |
| | | | on the node itself | in 'svn:externals' | | |
| | | | | | | |
| | Initial depth | Set by "switch" cmd | n/a | 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 (file) | external (dir) | | |
| +----------------------+----------------------+----------------------+----------------------+ | |
| | | | | | | |
| | recursive descent, | descend | descend | optional | | |
| | in general | | | | | |
| | | | | | | |
| | status | report & descend | report 'X' & status | report [& descend] | | |
| | | | | | | |
| | propget/list/etc. | descend | descend | skip | | |
| | | | | | | |
| | diff | descend | descend | skip | | |
| | | | | | | |
| | commit | descend | descend | skip [5] | | |
| | | | | | | |
| | update | descend | descend | descend (optional) | | |
| | | (in-line) | (in-line) | (afterwards) | | |
| | | | | | | |
| | switch | ? | ? | descend [6] | | |
| | | | | | | |
| | merge (tracking) | Skip it; track it as | Skip it; track it as | Just skip it; no | | |
| | | skipped. | skipped. | tracking needed. | | |
| | | | | | | |
| | ... | | | | | |
| | | | | | | |
| +----------------------+----------------------+----------------------+----------------------+ | |
| Behaviour differences when the target is the switched/external node or | |
| somewhere inside it: | |
| +----------------------+----------------------+----------------------+----------------------+ | |
| | | switched | external (file) | external (dir) | | |
| +----------------------+----------------------+----------------------+----------------------+ | |
| | | | | | | |
| | ... | | | | | |
| | | | | | | |
| +----------------------+----------------------+----------------------+----------------------+ | |
| 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. | |
| 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. | |
| [5] Bert says: "except for some buggy behavior relying on passing a | |
| limiting depth". | |
| [6] Bert says: "externals definitions are normally updated after a | |
| switch by handling the svn:externals property changes". |