notes/rename-tracking/renames-client-side.txt

   1
   2              CLIENT-SIDE TRACKING OF RENAMES
   3              ===============================
   4
   5
   6 CONTENTS
   7
   8     1. Introduction
   9
  10     2. Behaviour of Local Renames
  11
  12     3. Behaviour of Incoming Renames
  13
  14     4. Copies
  15
  16
  17 1. Introduction
  18
  19     See issue #3631, "Client-side tracking of renames", and issue #3630,
  20     "Rename tracking".
  21
  22     This document specifies the desired client-side behaviour for tracking
  23     a rename.
  24
  25     A local, scheduled rename can result from a Subversion "rename" command
  26     or from an incoming rename during an update, switch or merge.  The
  27     behaviour of local renames is specified in section 2.
  28
  29     The other necessary part of client-side behaviour is handling an
  30     incoming rename during an update, switch or merge.  That behaviour is
  31     specified in section 3.
  32
  33     A. What is a Rename?
  34
  35         A "rename" operation moves a node from one path to another, in a
  36         single operation.  The original node is then in a different
  37         directory and/or has a new name within its directory.
  38
  39         No distinction is made between the words "rename" and "move": either
  40         word refers to the operation that moves a node to a different
  41         directory and/or changes its base name.
  42
  43         No distinction is made between renaming a file, a directory or a
  44         symlink, unless otherwise noted.
  45
  46         A rename cannot change the node kind.
  47
  48         A node can be renamed and edited in the same change.
  49
  50     B. What is New?
  51
  52         The rename operation can be viewed as having two halves - removal
  53         from the source path, and adding or copying to the target path - but
  54         unlike in previous versions of Subversion, these two actions are:
  55
  56           - atomic (indivisible), and
  57
  58           - not quite the same as the separate "svn delete" and "svn copy"
  59             operations.
  60
  61         The rename is remembered and propagated as a rename.  One result is
  62         that when a node 'foo' is renamed to 'bar' in branch B1 and that
  63         change is then merged to branch B2, the corresponding node 'foo' in
  64         branch B2 is renamed to 'bar'.  In previous version of Subversion,
  65         that did not happen; instead, node 'foo' in B2 was deleted and then
  66         a new node 'bar' was created in B2 by copying the original 'foo'
  67         from B1.
  68
  69
  70 2. Behaviour of Local Renames
  71
  72     A local rename is a scheduled change in the working copy.
  73
  74     A. Atomicity
  75
  76         - commit either path: fail, or commit both halves (TBD)
  77
  78         - resolve either path: fail, or resolve both halves (TBD)
  79
  80         - revert either path: fail, or revert both halves (TBD)
  81
  82         - merge from either path: fail, or include both halves (TBD)
  83
  84         - update/switch: fail, or include both halves (TBD)
  85
  86         - changelist: ?
  87
  88         - export: ?
  89
  90         - lock/unlock: ?
  91
  92         - ...
  93
  94     B. Incoming edits (from update/switch/merge)
  95
  96        Here, "edit" means any modification including a property change or,
  97        for a directory, an add or delete or edit of a child.
  98
  99         - Incoming edit to the source path of any rename (even if a
 100           replacement node exists at that path): apply to the target path.
 101           ### Or tree conflict if a replacement node exists?
 102
 103         - Incoming edit to the target path: tree conflict (?) (not possible
 104           with up/sw)
 105
 106         - Incoming add at the source path: tree conflict.
 107
 108         - Incoming add at the target path: tree conflict.
 109
 110         - Incoming delete of the source path: tree conflict.
 111
 112         - Incoming delete of the target path: tree conflict.
 113
 114         - For incoming renames, and cases where there is both an incoming
 115           rename and a local rename, see section 3.
 116
 117     C. Commit
 118
 119         - Transmit the rename information to the server.
 120
 121         - See issue #3632, "Subversion's RA subsystem should carry rename
 122           information".
 123
 124     D. Renaming and Copying
 125
 126         - copy from source path: fail (can't reference a gone-away node)
 127
 128         - copy from target path: record as copy of that target path? (can we
 129           guarantee ordering such that that will be propagated correctly?)
 130
 131         - copy/move a dir with a whole rename inside it: DTRT (ordering?)
 132
 133         - rename from source path: fail (can't reference a gone-away node)
 134           (unless the source has since been replaced by a new node, in which
 135           case that new node is referenced)
 136
 137         - rename from target path: adapt the original rename
 138
 139         ### Peter Samuelson says:
 140             I think this operation,    {mv A B; cp B C},
 141             should behave exactly like {cp A C; mv A B}.
 142
 143     E. Other WC commands
 144
 145         - delete target path: convert the rename into a delete.
 146
 147         - 'svn info': on source node, display the target path; on target
 148           path, indicate it is a tracked rename.
 149
 150         - 'svn status': indicate source and target paths are parts of a
 151           rename.
 152
 153         - 'svn log --stop-on-copy' does not stop at a rename.
 154
 155         - 'svn diff' and 'svnlook diff' do not show either a whole-file add
 156           or a whole-file delete, but just show an indication that the file
 157           was renamed and show any content change that was made at the same
 158           time.
 159
 160         - ...
 161
 162
 163 3. Behaviour of Incoming Renames
 164
 165     An incoming rename is a rename described to the client by the server
 166     during an update, switch or merge operation.
 167
 168     A. Automatically merge the incoming rename with the local working copy,
 169        if possible.  If not possible, raise a tree conflict.
 170
 171         - Incoming rename, identical to a local rename: merge the two
 172           identical changes and unschedule the local rename
 173
 174         - Incoming rename, where source is source of a local rename:
 175           adjust the local rename accordingly
 176
 177         - Incoming rename, where target is target of a local rename:
 178           tree conflict
 179
 180         - Incoming rename, where source is target of a local rename:
 181           tree conflict (not possible for up/sw)
 182
 183         - Incoming rename, where target is source of a local rename:
 184           tree conflict (not possible for up/sw)
 185
 186         - Incoming rename, local edit: rename the local node, keeping the
 187           local edits (including any unversioned nodes in it, if it's a dir)
 188
 189         - Incoming rename, local delete: tree conflict
 190
 191     B. Source of Information on Incoming Renames
 192
 193         - The intended source is from an updated RA interface.  See issue
 194           #3632, "Subversion's RA subsystem should carry rename information"
 195
 196         - A possible backward compatibility measure, when talking to servers
 197           that do not support rename tracking, could be to infer renames
 198           from heuristics on incoming deletes and copies.
 199
 200
 201 4. Copies
 202
 203     ### TO DO
 204
 205     Copies should exhibit behaviour in line with renames.  During a merge,
 206     an incoming copy should result in a local copy from a local source,
 207     rather than a local copy from a source in the source branch.  ...
 208