| |
| |
| 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". |