Merge tracking functional specification. Describes Subversion 1.5.0, except where noted as unimplemented. This is a living specification, which will change as features are added or refined.
Merge operations involving a single source URL (e.g. svn
merge -cN URL) allow the revision range and source URL
parameters to be optional. The revision range defaults to "all
unmerged revisions", while the source URL is inferred using a
combination of merge info and copy history. When a revision range is
not provided, merge operations are not able to "revert" changes
(e.g. a la svn merge -c -7 URL).
See the repeated merge section below for discussion of various merge algorithms, and details on the merge algorithm used.
Merge info is not taken into consideration for three-way
merges, merge operations which do not specify identical "from"
and "to" URLs (e.g. svn merge FROM_URL@REV1 TO_URL@REV2).
In the future, Subversion will likely support this, but currently
lacks sufficient history and merge info between the repository and
client to perform this operation in a reasonable manner. The primary
use case this will impact is vendor branches.
Output is shown the same as pre-Merge Tracking, except for:
Copy and move operations handle two types of merge info:
svn:mergeinfo
property on the source path.Copy/move operations which contact the repository include:
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.
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:
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).
Switched paths are treated as the root of the working copy regarding merge info inheritance and elision, specifically:
Property changes from propedit, propset,
and propdel operations can be used to change merge info.
However, as these operations do not attempt to address merge info
inheritance, changes to merge info on a directory affects merge info
on any child paths.
Merge info set on a working copy "child" path as a result of a merge, switch, or update, may fully/partially elide to the path's nearest working copy or repository ancestor with fully/partially equivalent merge info. Elision is attempted as part of any merge/switch/update:
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'.
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'.
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
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 Tracking meta data is stored in housekeeping properties
(e.g. svn:mergeinfo).
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 mere info for a path.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.
Show changesets available for merge/already merged from one or more
merge source(s). The command-line client's default output format
should be equivalent to that of svn log, and allow for
XML-formatted output (for machine parsing). Blue sky, the
command-line could also produce an output format equivalent to that of
svn diff.
Recent discussion can be found here. Development is tracked here.
The Show Changesets Blocked from Merging portion of this feature is scheduled for implementation post-1.5, and is dependent upon the revision blocking feature slated for the same timeframe.
Show where a changeset has been merged from/merged to, providing merging revision, URL, and rangelist. The command-line client should allow for XML-formatted output (for machine parsing).
Recent discussion can be found here. Development is tracked here.
The Find Paths containing Specific Incarnation of Versioned Resource portion of this feature is not yet scheduled for implementation.
The following commands which show username and merge information should respect merge information and support Commutative Reporting. These commands are:
svn logsvn blamesvn info, svn ls --verbose and svn
status --show-updates are purposely not included in this list.
While one would typically need more information than they can
reasonably provide alone, adding more output to these commands would
clutter their command-line interface, reducing their utility. Merge
Tracking-aware API support for the underlying functionality provided
by these commands may be added at some point in the future (e.g. for
use by third-party clients like TortoiseSVN).
A new switch, --use-merge-history, along with a
corresponding single-character shortcut (-g), will be
introduced for the toggle merge information. Using it will enable these
commands to show the additional information gleaned from parsing and
processing the merge info on the targets in question. This switch will
also work with --xml to include additional merge
information. The new functionality added by
--use-merge-history is as follows.
svn logThe original log message(s), in the current format, with the
addition of a list of revisions and merge source paths that have
been merged into the target. The output for log should
be consistent with the diff output for the
svn:mergeinfo property.
The --verbose switch will output the log information
for the merged revisions in place of the information for the revision
in which the merge occured. Each of the original message(s) will have an
additional line indicating that it is the result of a merge, and which
revision the merge occured in.
For instance, if Alice was the original author of r12, Bob was the
orginial author of r14, and Chuck merged them both r12 and r14 as part
of r24, the output of svn log --use-merge-history
will look like this:
------------------------------------------------------------------------ r24 | chuck | 2007-04-30 10:18:01 -0500 (Mon, 16 Apr 2007) | 1 line Merge r12 and r14 from branch to trunk. ------------------------------------------------------------------------ r14 | bob | 2007-04-16 18:50:29 -0500 (Mon, 16 Apr 2007) | 1 line Result of a merge from: r24 Remove inadvertent changes to Death-Ray-o-Matic introduced in r12. ------------------------------------------------------------------------ r12 | alice | 2007-04-16 19:02:48 -0500 (Mon, 16 Apr 2007) | 1 line Result of a merge from: r24 Fix frapnalyzer bug in frobnicator.
Using the same example, the output of svn log
--use-merge-history --verbose will look like:
------------------------------------------------------------------------ r24 | chuck | 2007-04-30 10:18:01 -0500 (Mon, 16 Apr 2007) | 1 line Changed paths: M /trunk/death-ray.c M /trunk/frobnicator/frapnalyzer.c Merge r12 and r14 from branch to trunk. ------------------------------------------------------------------------ r14 | bob | 2007-04-16 18:50:29 -0500 (Mon, 16 Apr 2007) | 1 line Changed paths: M /trunk/death-ray.c Result of a merge from: r24 Remove inadvertent changes to Death-Ray-o-Matic introduced in r12. ------------------------------------------------------------------------ r12 | alice | 2007-04-16 19:02:48 -0500 (Mon, 16 Apr 2007) | 1 line Changed paths: M /trunk/frobnicator/frapnalyzer.c M /trunk/death-ray.c Result of a merge from: r24 Fix frapnalyzer bug in frobnicator.
If r12 was itself a merge of r9 and r10, svn log
--use-merge-history for r24 will look like this:
------------------------------------------------------------------------ r24 | chuck | 2007-04-30 10:18:01 -0500 (Mon, 16 Apr 2007) | 1 line Merge r12 and r14 from branch to trunk. ------------------------------------------------------------------------ r14 | bob | 2007-04-16 18:50:29 -0500 (Mon, 16 Apr 2007) | 1 line Result of a merge from: r24 Remove inadvertent changes to Death-Ray-o-Matic introduced in r12. ------------------------------------------------------------------------ r12 | alice | 2007-04-16 19:02:48 -0500 (Mon, 16 Apr 2007) | 1 line Result of a merge from: r24 Fix frapnalyzer bug in frobnicator. ------------------------------------------------------------------------ r10 | alice | 2007-04-16 19:02:28 -0500 (Mon, 16 Apr 2007) | 1 line Result of a merge from: r12, r24 Fix frapnalyzer documentation. ------------------------------------------------------------------------ r9 | bob | 2007-04-16 19:01:48 -0500 (Mon, 16 Apr 2007) | 1 line Result of a merge from: r12, r24 Whitespace fixes. No functional change.
In each case, merged revisions will be grouped together under the merging revisions, and sorted by revision number. This may mean that not all log messages will be in revision number order, but changes will be presented in the order they were actually made.
Output for svn log -g --xml will exploit the tree structure
of XML to include child messages as subelements of the corresponding parent
log messages. Consumers can use the location of a particular log message in
the tree to determine its ancestry.
This output may be useful for auditing purposes to those migrating from svnmerge.py, as a replacement for repeating the entirety of the merged ranges' log messages in the log message for the commit of a merge (e.g. svnmerge.py's generated svnmerge-commit-message.txt file).
svn blameReuse the existing author and revision columns. Instead of listing the merging author and revision, list the original author and revision of that line. Unlike other commands, we do not need to worry about multiple source revisions, because each line can have at most one author.
The output of svn blame may be the following:
2 alice This is the file 'iota'.
14 bob 'A' has changed a bit, with 'upsilon', and 'xi'.
Using the -g switch will show the author who most recently
changed the line, independent of which branch it was changed on (so long as
the changes have been merged). If Chuck made changes to the file in r11,
which was then merged in r14, the output of svn blame -g for the
same file may look like this:
2 alice This is the file 'iota'.
11 chuck 'A' has changed a bit, with 'upsilon', and 'xi'.
The --verbose flag also triggers additional information.
In addition to the date of the revision, --verbose, in
combination with -g, also displays the the original path, relative
to the repository root, where the modifications were made. Given the above
example, svn blame -g --verbose will be something like this:
2 alice 2007-06-07 10:16:49 -0500 (Thu, 07 Jun 2007) /trunk/iota This is the file 'iota'.
11 chuck 2007-06-07 12:29:48 -0500 (Thu, 07 Jun 2007) /branches/a/iota 'A' has changed a bit, with 'upsilon', and 'xi'.
The output of svn blame -g --xml is not limited by size, and
will include all available information.
For commits which remove merge info (e.g. reverts),
--use-merge-history will trace back to the original author. For
example if Alice makes a commit to code previously modified by Bob (committed
with no merge history), and Alice's commit is subsequently reverted by Chris,
we should show Bob as the author. If Bob's commit was itself the result of a
merge, we should recurse until we find a commit which did not add merge info
(the leaf node), and assume its author.
Although not part of the initial implementation, additional features have been suggested:
--use-merge-history.
There are two general schemes for solving the repeated merge problem. Subversion 1.5 uses the Most Recent Common Ancestor (MRCA) approach. If a later version of Subversion (e.g. 2.0) overhauls the Merge Tracking implementation, it'll likely use the Ancestry Set (AS) approach.
Either solution also supports the cherry picking, rollback, and property merging use cases. A merge preview which is lighter-weight than an uncommitted merge into a WC is not supported.
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.
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.
Make 'hunks' of contextually-merged text sensitive to ancestry.
A high-resolution version of repeated merge. Rather than tracking whole changesets, we track the lineage of specific lines of code within a file. The basic idea is that when re-merging a particular hunk of code, the contextual-merging process is aware that certain lines of code already represent the merging of particular lines of development. Jack Repenning has a great example of this from ClearCase (see ASCII diagram below).
See the variance
adjusted patching document for an extended discussion of how to
implement this by composing diffs; see svn_diff_diff4() for an implementation of same. We
may be closer to ancestry-sensitive merging than we think.
Here's an example demonstrating how individual lines of code can be tracked. In this diagram, we're drawing the lineage of a single file, with time flowing downwards. The file begins life with three lines of text, "1\n2\n\3\n". The file then splits into two lines of development.
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
It's the second merge that's important here.
In a system like Subversion, the second merge of the left branch to the right will fail miserably: the whole file's contents will be placed within conflict markers. That's because it's trying to dumbly apply a patch that changes "1\n2\n3" to "one\nTwo\nthree", and the target file has no matching lines at all.
A smarter system (like Clearcase) would remember that the previous merge had happened, and specifically notice that the lines "one" and "three" are the results of that previous merge. Therefore, it would ask the human only to deal with the "Two" versus "two-point-five" conflict; the earlier changes ("1\n2\n3" to "one\ntwo\nthree") would already be accounted for.
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.
Merging inevitably produces conflicts which cannot be resolved by an algorithm alone. In such a case, human intervention is required to resolve the conflicts. The merge algorithm used by Subversion's Merge Tracking implementation makes this problem worse, since it breaks a requested merge range into several merges to avoid repeating merges which have already been applied to a merge target or its children.
To help alleviate the pain of conflict resolution, a merge conflict resolution callback can be employed by Subversion clients. This callback is invoked whenever merge conflicts are encountered, and can takes steps like launching a graphical merge tool (for interactive conflict resolution), or following a pre-specified directive like "always use the version from my merge source". This last implementation can be used to support the SCM automated merge use case.
The command-line client includes a merge conflict resolution callback which behaves much like svk, when in interactive mode displaying some context for each conflict and prompting for how to resolve it, or when in non-interactive mode, taking directives beforehand. See the 1.5 release notes for an example.
Related discussion from the dev@ mailing list can be found here:
Issue #2022 is loosely related.
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.
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 .
Executive summary for client/repository inter-op:
Gory detail for client/repository inter-op:
Subversion dump files continue to be fully portable between pre- and post-Merge Tracking versions of Subversion.
$Date$