notes/moves

   1
   2  =======================
   3  Moves in Subversion 1.8
   4  =======================
   5
   6 This file purposefully talks about 'moves' rather than 'renames'.
   7 This isn't about true renames as requested in issue #898.
   8 Rather, we keep the add+delete concept while trying to make moves behave
   9 more in a way that one would expect if true renames were implemented,
  10 as requested in issue #3631. See also the umbrella issue #3630.
  11
  12 So far the changes only cover local (client-side) moves in the working copy.
  13 We reuse as much existing code as possible, so new functionality is
  14 implemented as part of existing copy/delete code paths unless doing
  15 so is not feasible.
  16
  17 One significant change from how copies work is that moves are tracked
  18 both ways, i.e. one can locate the add-half of a move if given the
  19 delete-half, and locate the delete-half if given the add-half.
  20
  21 The goals are:
  22
  23   - Improve the behaviour for tree-conflicts involving a local move.
  24       A "local move vs. edit" tree conflict should be automatically resolved.
  25       Any tree conflict involving a local move should clearly indicate
  26       so in its description, saying 'local move' instead of 'local delete'
  27       or 'local add'.
  28
  29   - Prepare the client to be able to use the editor-v2 rename interfaces
  30     when talking to the server.
  31
  32
  33 Notes regarding specific layers of Subversion follow below.
  34
  35
  36 == wc.db ==
  37
  38 The following columns in the NODES table are used to differentiate
  39 moves from copies:
  40
  41   /* Boolean value, specifying if this node was moved here (rather than just
  42      copied). This is set on all the nodes in the moved tree.  The source of
  43      the move is implied by a different node with a moved_to column pointing
  44      at the root node of the moved tree. */
  45   moved_here  INTEGER,
  46
  47   /* If the underlying node was moved away (rather than just deleted), this
  48      specifies the local_relpath of where the node was moved to.
  49      This is set only on the root of a move, and is NULL for all children.
  50
  51      The op-depth of the moved-to node is not recorded. A moved_to path
  52      always points at a node within the highest op-depth layer at the
  53      destination. This invariant must be maintained by operations which
  54      change existing move information. */
  55   moved_to  TEXT,
  56
  57 Many queries were added or changed to use these columns.
  58
  59 == libsvn_wc ==
  60
  61 In the internal wc_db API, the _scan_addition() and _scan_deletion()
  62 interfaces were extended to make use of new DB queries to differentiate
  63 moved nodes from copied, added, and deleted nodes.
  64
  65 Two functions were built on top of the wc_db API and added to the
  66 private libsvn_wc API:
  67   svn_wc__node_was_moved_away() provides, for a given local_abspath:
  68     - the moved_to abspath within the working copy
  69     - the abspath of the op-root of the copy operation that created
  70       the node at the moved_to abspath
  71   svn_wc__node_was_moved_here() provides, for a given local_abspath:
  72     - the moved_from abspath within the working copy
  73     - the abspath of the op-root of the delete operation that deleted
  74       the node at the moved_from abspath
  75
  76 More API changes might be needed (TBD).
  77 In particular, scan_deletion may need to return a list of moves
  78 in the multi-layer case (http://wiki.apache.org/subversion/MultiLayerMoves)
  79
  80 We might require a working copy upgrade when going from 1.7 to 1.8,
  81 and only allow new move functionality to be used with 1.8 working copies.
  82
  83
  84 == libsvn_client ==
  85
  86 This layer already uses 1.7 and earlier svn_wc move APIs. For callers
  87 of such APIs, changes will hopefully be fairly transparent apart from
  88 changes that enhance behaviour of move operations.
  89
  90 Interfaces which have changed behaviour:
  91
  92  svn_client_commit: Commit will refuse to commit anything if only one
  93    half of a move appears in the commit target list, or if only one half of
  94    a move is picked up by recursion.
  95
  96  svn_client_revert: The behaviour of this API is not changed, but it
  97    is worth noting how it behaves for moves:
  98    - If both halves of a move are among the revert targets (either by
  99      virtue of being listed explicitly, or by being picked up during
 100      recursion), the entire move is reverted.
 101    - If only one half of a move is among the revert targets, the other
 102      half will be transformed into a normal copy or delete.
 103      See http://svn.haxx.se/dev/archive-2011-08/0239.shtml for rationale.
 104
 105  - svn_client_status: Status provides the moved-to abspath for a moved-away
 106      nodes, and the moved-from abspath for a moved-here node.
 107      Note that, mostly due to performance reasons, only information about
 108      roots of moves is provided. Children of moved nodes aren't marked as such.
 109
 110  - svn_client_info: Like status, except that it also provides move
 111      information about children of moved nodes.
 112
 113  - svn_client_patch: Patch uses move information to apply changes to files
 114      which have been moved locally.
 115
 116  - svn_client_update/svn_client_merge: Update and Merge use move
 117     information to auto-resolve the "local move vs. incoming edit"
 118     tree conflict scenario.
 119
 120 Interfaces which have not changed behaviour yet but might change in 1.8.0:
 121
 122  - svn_client_update/svn_client_merge: Update and Merge might use move
 123     information to auto-resolve some additional tree conflict scenarios.
 124
 125  - diff: Diff might use move information to generate 'rename from' headers
 126     when the --git option is used. (A related problem is making diff use
 127     correct copyfrom in repos-repos diffs, which is not trivial.)
 128
 129 Several public APIs may still be bumped as their behaviour changes.
 130
 131 For backwards compatibility, APIs released prior to 1.8 will continue
 132 to treat moves just like 1.7 and earlier releases did. (However, see
 133 also the note on working copy upgrades above, which might affect to
 134 what degree the APIs need to stay compatible.)
 135
 136
 137 == svn ==
 138
 139 The svn client presents moves similar to but distinct from copy operations.
 140
 141 svn status shows move roots:
 142
 143 $ svn status
 144 A  +    foo
 145         > moved from 'bar'
 146 D       bar
 147         > moved to 'foo'
 148 $
 149
 150 svn info shows additional Moved-To: and Moved-From: lines for any moved node.