Merge Tracking Functional Specification

Repository Access operation

Copy/move operations which contact the repository include:

• WC to URL
• URL to WC
• URL to URL

These operations always propogate both explicit and implicit merge info. Other than the inclusion of merge info, operation is effectively the same as pre-Merge Tracking.

Working Copy to Working Copy operation

Pre-Merge Tracking, WC to WC operations occurred offline (e.g. with no repository access). This is a typical behavior of refactoring tools (e.g. IDEs like Eclipse), and is very useful when offline (e.g. on an airplane or subway, or at a cafe).

However, to propogate merge info during copy/move operations, access to both a path's comprehensive merge info and its history is necessary. To preserve offline operation, the Merge Tracking implementation supports two modes:

• A compatibility mode, which neither contacts the repository, nor does any merge info propogation (unless a copy source's merge info has been locally modified, in which its value is propogated the as any Subversion revision property). This is the default mode of operation.
• A mode which requires repository access (e.g. isn't offline), but which propogates all merge info from source path to destination. This mode is activated via the --use-merge-history option.

This behavior is comparable to the difference between svn status and svn status -u.

While some state indicating delayed merge info retrieval and handling could instead be stored in WC to preserve offline operation, there are complications with this when subsequent uncommited revert operations should change the merge info (we'd have to store negative merge info in the WC).

Full Elision

• Simple Equivalency: The merge info on a child path and the merge info on its nearest ancestor both map the same set of source paths to the same revision ranges. The "same" source path is taken to mean that the only differences between the two are relative path differences which are exactly the same as the relative path differences between the child and the ancestor, e.g.:

    Properties on '/A_COPY_2':
      svn:mergeinfo : /A:4-9
    /A_COPY:3
    Properties on '/A_COPY_2/B/E':
      svn:mergeinfo : /A/B/E:4-9
    /A_COPY/B/E:3

  The merge info on 'A_COPY_2/B/E' elides to 'A_COPY_2' because the only differences between the merge source paths on each is 'B/E' which is the same as the relative path difference between 'A_COPY_2/B/E' and 'A_COPY_2'.

• Semantic Equivalency: Excepting paths unique to the child or ancestor which map to empty revision ranges, the merge info between the child and ancestor is otherwise equivalent per the definition of simple equivalency, e.g.:

    Properties on '/A_COPY_2':
      svn:mergeinfo : /A:4-9
    /A_COPY:
    Properties on '/A_COPY_2/B/E':
      svn:mergeinfo : /A/B/E:4-9
  
    Properties on '/A_COPY_2':
      svn:mergeinfo : /A:4-9
    Properties on '/A_COPY_2/B/E':
      svn:mergeinfo : /A/B/E:4-9
    /A_COPY/B/E:

  In both of the above examples the merge info on 'A_COPY_2/B/E' elides to 'A_COPY_2'.

• Empty Revision Range Equivalency: If the merge info on a path is made up entirely of paths mapped to empty revision ranges and the path has no ancestor with merge info then the merge info fully elides.

Partial Elision

• Partial Equivalency: Only the merge source paths unique to the child which map to empty revision ranges will elide if the merge info between the child and ancestor is otherwise non-equivalent, e.g.:

    Properties on '/A_COPY_2':
      svn:mergeinfo : /A:4-6
    Properties on '/A_COPY_2/B/E':
      svn:mergeinfo : /A/B/E:5
    /A_COPY/B/E:

  The empty revision range merge info from 'A_COPY/B/E' on 'A_COPY_2/B/E' elides, leaving:

    Properties on '/A_COPY_2':
      svn:mergeinfo : /A:4-6
    Properties on '/A_COPY_2/B/E':
      svn:mergeinfo : /A/B/E:5

Elision and Non-Inheritable Revision Ranges

The above rules apply only to mergeinfo without non-inheritable revision ranges. Mergeinfo with non-inheritable revision ranges cannot elide or be elided to.

Merge History Manipulation

While direct manipulation of housekeeping properties can be used to change merge info, commands to manipulate this information have been provided. Either style of operation supports adjustment of merge info when manual merges occur, and can also be used to fulfill block changes undesired for merge (later, this might be better-addressed by a separate housekeeping property).

• merge --record-only adds (or subtracts, if a reversed revision range is supplied) merge info for a path without performing the actual merge.
• propedit/propset changes merge info for a path.
• propdel removes merge info for a path.

Merge History Audit and Query

The Commutative Author and Revision Reporting feature has been implemented, and will be included in 1.5.0.

These features may or may not be completed for 1.5.0.

• Changeset Merge Availability (unimplemented)
• Find Changeset (unimplemented)

The Most Recent Common Ancestor approach

In this scheme, An optional set of merge sources in each node-revision. When asked to do a merge with only one source (that is, just svn merge URL, with no second argument), you compute the most recent ancestor and do a three-way merge between the common ancestor, the given URL, and the WC.

To compute the most recent ancestor, you chain off the immediate predecessors of each node-revision. The immediate predecessors are the direct predecessor (the most recent node-revision within the node) and the merge sources. An interleaved breadth-first search should find the most recent common ancestor.

The Ancestry Set approach

In this scheme, you record the full ancestry set for each node-revision -- that is, the set of all changes which are accounted for in that node-revision. (How you store this ancestry set is unimportant; the point is, you need a reasonably efficient way of determining it when asked.) If you are asked to "svn merge URL", you apply the changes present in URL's ancestry but absent in WC's ancestry. Note that this is not a single three-way merge; you may have to apply a large number of disjoint changes to the WC.

For a longer description of this approach, see the "Merging and Ancestry" section of the original design doc.

                    1     
                    2     
                    3     
                  /   \   
                 /     \  
                /       \ 
            one           1   
            two           2.5 
            three         3   
             |     \      |
             |      \     |   
             |       \    |            
             |        \   |            
             |         \ one                ## This node is a human's
             |           two-point-five     ## merge of two sides.
             |           three        
             |            |
             |            |
             |            |
            one          one
            Two          two-point-five
            three        newline       
               \         three  
                \         |   
                 \        |
                  \       |
                   \      |
                    \     |
                     \    |
                      \   |
                       \  |
                         one                ## This node is a human's
                         Two-point-five     ## merge of the changes
                         newline            ## since the last merge.
                         three

Comparisons, Arguments, and Questions

AS allows you to merge changes from a branch out of order, without doing any bookkeeping. MRCA requires you to merge changes from a branch in order.

MRCA is simpler to implement, since it results in a three-way merge (which is well-understood by Subversion). However, it may not handle all edge cases. For instance, it may break down faster if the merging topology is not hierarchical.

MRCA may be easier for users to understand, even though AS is probably simpler to a mathematician.

Consistency with other modern version controls systems is desirable.

If a user asks to merge a directory, should we apply MRCA or AS to each subdirectory and file to determine what ancestor(s) to use? Or should we apply MRCA or AS just once, to the directory itself? The latter approach seems simpler and more efficient, but will break down quickly if the user wants to merge subdirectories of a branch in advance of merging in the whole thing.

Distribution of Conflict Resolution

No explicit facility is provided for distribution of conflict resolution. To support this use case, developers can co-ordinate with each other to resolve merge conflicts on portions of a tree, and trade patches.

Migration

No explicit steps are necessary to migrate the content of a pre-Merge Tracking repository. Only an upgrade to Subversion 1.5.0 is necessary.

TODO: Merge meta data from svnmerge.py. Dan Berlin has written Python code to perform this migration; it needs to be made available in the tools/server-side/ area of the distribution .

Interoperability

Executive summary for client/repository inter-op:

• Older Subversion clients may interact with a 1.5.x+ Subversion repository, but will continue to lack Merge Tracking functionality for:
  • Recording meta data about any merges performed.
  • Using merge meta data to avoid repeated merging.
• 1.5.x+ Subversion clients may interact with a older Subversion repositories, with Merge Tracking functionality effectively neutralized.

Gory detail for client/repository inter-op:

• A repository 1.4.x- doesn't provide any way to retrieve inherited merge info for a path (regardless of client version). For a 1.5.x+ client which could theoretically make use of any merge info available to it, this will typically neutralize its Merge Tracking functionality. The one case where merge info might come into play is when the merge info for a path is available locally (e.g. in the client's WC); in this case, repeated merges may be avoided.
• A 1.5.x client will record merge tracking meta data for merges performed, regardless of repository version. However, a repository 1.4.x- won't know to do anything special with this merge info. When the repository is upgraded to 1.5.x+, we'll retain this merge info in the svn:mergeinfo property, but I'm not yet clear on what'll happen to the sqlite merge info index. We may need some sort of upgrade path here, but don't have one yet, and aren't promising one.

Subversion dump files continue to be fully portable between pre- and post-Merge Tracking versions of Subversion.