subversion-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <>
Subject [Subversion Wiki] Update of "SupportedMergeScenarios" by JulianFoad
Date Thu, 06 Oct 2011 16:10:14 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Subversion Wiki" for change notification.

The "SupportedMergeScenarios" page has been changed by JulianFoad:

(Manually) import doc from Google docs

New page:
= What Merges Does Svn’s Merge Tracking Support? =
We  need to be able to say, “If you do all your merging like <this>,  it will work
like you expect.”  So what is <this>?  What are the  supported scenarios, limitations
and rules, and what can the user expect  within and outside those scenarios?

Merging  is a broad term.  We’re talking here about here merging changes that  have been
made on one branch into another branch.  The whole process of  merging includes several steps
which may be manual or automated:

 * selecting a source branch
 * identifying which changes to pull from the source branch
 * applying those changes to a working copy of the target branch
 * resolving any conflicts, both conflicts that Subversion detects and semantic conflicts
 * committing the result
 * possibly  other actions such as deleting the source branch if it is finished  with, or
taking action to “keep it alive” after a reintegrate

This document is concerned primarily with merging in such a way that Subversion’s merge
''tracking'' will enable future automatic (''catch-up'' and ''reintegrate) ''merges to select
the correct set of changes.  This answers the question, “What ''logical changes''  don't
I have on branch B already, that I need to pull from branch A to  B?”  A related but different
issue is how to apply those changes to the  target branch: “For a given physical or logical
change ‘c1’ that branch A  claims to have an instance of, how do I construct from ‘c1’
the best  physical edit that will apply to branch B with the least amount of  spurious physical

The  information in this document is not intended to repeat the functional  documentation
of the “merge” command itself, but rather to explain the  ways in which that command can
be used effectively.

=== Identifying Logical Changes vs. Commits ===
To  discuss the nuances of what exactly is tracked in Merge Tracking, we  need to think about
the difference between a raw change in the  repository (a ''commit'') and a concept that we
can call a ''logical change''.  This distinction is ''not'' implemented in Subversion 1.6.

When I commit a change that’s not a merge, we can regard that as introducing a new ''logical
change''  into my project, on a given branch.  But when I merge that change to  another branch
and commit the result, that is not creating a new logical  change, rather it is the physical
representation in that target branch  of the same logical change.  (In simple cases the physical
change is  often “the same” but in general it is different, because it is adapted  automatically
or through ''conflict resolution''  to suit that target branch, or because in the target branch
it is  combined with other logical changes into a single commit, or both.)

This is important in an automatic merge, when we want to avoid merging any ''logical change''
that is already present on the target branch, no matter from which intermediate branch it
arrived there.

The whole subject of merge tracking is about whether to port the a given ''logical change''
onto the target branch, or whether that ''logical change''  has already been put there.  The
question is not about the physical  representation of that change; it doesn’t matter whether
the change was  achieved on the target branch by exactly the same physical edits as it  was
in the source branch.  The merge algorithm cannot possibly know  whether the physical change
that was committed (at the time when the  merge info says the merge happened) accurately represents
the ''logical change''  that is claimed, but if it doesn’t (or indeed if it is totally 
unrelated), then something has gone wrong at a higher level.  As far as ''merge tracking''
is concerned, that change was merged.

== Merging Scenarios for Subversion 1.6 ==

 * A, B, C, …    branches
 * A:3        the change in branch A that was committed as revision 3
 * A ⇒ B        a high-level relationship assumed between branches A and B, in the indicated
 * A → B        a merge from branch A to branch B

### TODO: Diagrams. This needs to be more visual to be easily understood.
=== General Concepts ===
==== What’s a “Change”? ====
The  unit of change that Subversion tracks is the change that was committed  in a specific
revision, scoped pathwise to a specific subtree.

==== Tracked Merge ====
 1. When  the “merge” command updates the mergeinfo of the target branch to  record the
merge, the result is the kind of merge that Subversion is  able to track.  In this document,
“a merge” generally refers to this  kind of merge.
 1. A  tracked merge is transitive.  In merging A:10 from A to B, if A:10 was  itself a merge
that brought in one or more recorded changes from  elsewhere (say Z:9), then as well as recording
A:10 on B, we also record  Z:9 on B.

==== Non-Tracked Merge ====
 1. You  can use the “merge” command to merge changes in such a way that the  committed
result is not recorded as a merge.  In terms of merge  tracking, Subversion sees this commit
as an original change, not as a  merge.  This kind of merge should be used only in special

==== Record-Only Merge ====
 1. A  “record-only” merge acts like a normal merge except that it does not  make edits
to the target branch, it only updates the mergeinfo on the  target branch as if that merge
had happened.  After a ''record-only merge''  has been committed, although only the mergeinfo
changed in that commit,  the merge tracking logic sees that commit as the time when the merge
 (the one that is now recorded) was performed.  It doesn’t notice that  there is no physical
change in the commit.  It doesn’t care whether the  physical change was in fact merged into
this target branch in the past  or will be merged in the future.  If and when the physical
change is  merged as a non-tracked merge, that commit will be regarded as an  original change
and not as a merge.

==== The Immediate Source Branch ====
 1. Merge tracking only notices what changes have been merged from the immediate source branch.
 Using automatic (''catch-up'')  merges, say we merged A:10 into B as B:13, and A:10 into
C as C:14, and  now we are about to merge “all unmerged changes” from B to C.  When  considering
what to merge from B, we only look at what revisions on the  source branch B are recorded
as having been merged into C, and let’s say  we find all changes from B are recorded there
except B:13.  Subversion  will try to merge the commit B:13 from B to C, and it will conflict,
at  least logically and probably physically, because it is just an adjusted  version of the
original change A:10 which has already been merged into C  directly.  This is a limitation
of the merge tracking algorithm.

=== The Feature Branch Scenario ===
This  scenario is a way of using merges with a branch that has a limited  lifetime and is
going to be merged back into the branch that it is based  on.  A typical usage is to develop
a new feature or a non-trivial bug  fix in a software project.

Suppose  the purpose of branch B is to develop some changes based on branch A.   From time
to time we will bring all the latest changes from branch A  onto B, so that the development
branch B is always based on a recent  snapshot of the state of branch A.  When finished, we
will merge the  changes that were developed on branch B into branch A.  At that time, we 
may have finished with branch B, or we may want to continue with some  further development
on it and merge that second phase of development to  branch A, and so on, but eventually we
expect to finish with branch B.

We call this relationship A ⇒ B the ''Feature Branch'' relationship.

 1. Branches  A and B must be ancestrally related.  Usually, B is created as a copy  of A,
but any history in which the nodes A and B share a common ancestor  is acceptable.
 1. Merges are performed from and to the root of a branch, unless otherwise stated.  (See
''Subtree Merges''.)

==== Catch-Up, aka Sync ====
 1. An  “automatic” merge A → B, at any time, brings B “up to date” with A by  merging
all revisions from A that are not already (recorded as being) in  B, into B.  The revisions
are not merged individually but in batches,  where each batch is as big as possible.

==== Reintegrate ====
 1. Reintegrate B → A, when B is sufficiently up to date with A.
 1. After  a reintegrate, before any further catch-up or re-integrate merges  between A and
B, it is necessary to do a record-only merge from A to B.  See the [[|Keeping
a Reintegrated Branch Alive]] section in the Book for details.

==== Cherry-Pick ====
 1. A → B.  You can cherry-pick any individual revision or revision range from A that is
not already recorded on B.
 1. B  → A.  You can cherry-pick any individual revision or revision range  from B that
is not already recorded on A and is not itself the result of  a merge from A.  (If it is the
result of a merge from A, then ###.)
 1. You  should NOT cherry-pick a change from A to B or from B to A that is  already recorded
on the target branch.  (Subversion attempts the merge  but does not record it.)  (### Are
we sure?)

==== Multiple Branches ====
 1. The ''Feature Branch'' relationship can be daisy-chained.
  * A ⇒ B, B ⇒ C, C ⇒ D, …

 1. The ''Feature Branch'' relationship can be applied one-to-many.
  * A ⇒ B, A ⇒ B2, A ⇒ B3, …
 1. The ''Feature Branch'' relationship cannot be applied many-to-one.
  * '''NO: '''A ⇒ B, A2 ⇒ B, A3 ⇒ B, …

 1. The ''Feature Branch'' relationship cannot be applied with cycles in the graph of relationships.
  * '''NO:''' A ⇒ B, B ⇒ A
  * '''NO:''' A ⇒ B, B ⇒ C, C ⇒ A

 1. The ''Feature Branch'' relationship cannot be applied with multiple paths in the graph
of relationships.
  * '''NO:''' A ⇒ B, B ⇒ C, A ⇒ C
  * '''NO:''' A ⇒ B, A ⇒ C, B ⇒ D, C ⇒ D

==== Reverse Merge ====
 1. A  → B.  You can cherry-pick A → B, the reverse of a change “c1” on A that  was
previously merged (and recorded as merged) to B.  Subversion  records that the change is no
longer present on B, just as if that  change had not previously been merged from A to B, and
so “c1” is  eligible for being included in a catch-up merge again.
 1. A  → A.  In any branch A you can reverse cherry-pick a change “c1” from  A’s own
history to undo that change.  If the change “c1” was an original  change in A, this is
recorded as a manual edit and is not tracked as a  merge.  If the change “c1” was a merge
(say change “c0” from branch Z)  into A, or included such a merge, ### ? that’s fine
too, as long as “c0”  is currently recorded on A.  Subversion records that the change
is no  longer present on A, just as if that change had not previously been  merged, and so
“c1” is eligible for being included in a catch-up merge  again.  But if “c0” was not
currently recorded on A (for example, if it  already had been reverse-merged once and not
subsequently  forward-merged), that is not valid; Subversion will perform but not  record
the merge.

==== Subtree Merges ====
 1. ### ?

=== The Release Branch Scenario ===
In  this scenario, a branch is expected to have occasional edits,  occasional cherry-pick
merges to and/or from the branch it’s based on,  and there is no special merging to be done
at its end of life. The set of rules is much simpler than for the release branch scenario.

==== Multiple Branches ====
### How do A ⇒ B feature branch relationships connect with C ⇒ D release branch relationships?
==== Cherry-Pick ====
 1. A → B.  You can cherry-pick any individual revision or revision range from A that is
not already recorded on B.
 1. B → A.  You can cherry-pick any individual revision or revision range from B that is
not already recorded on A.
 1. You  should NOT cherry-pick a change from A to B or from B to A that is  already recorded
on the target branch.  (Subversion attempts the merge  but does not record it.)

View raw message