If you always synchronise a feature branch before you merge it back. Why do you really have to use the --reintegrate
option?
The Subversion book says:
When merging your branch back to the trunk, however, the underlying mathematics is quite different. Your feature branch is now a mishmosh of both duplicated trunk changes and private branch changes, so there's no simple contiguous range of revisions to copy over. By specifying the --reintegrate option, you're asking Subversion to carefully replicate only those changes unique to your branch. (And in fact, it does this by comparing the latest trunk tree with the latest branch tree: the resulting difference is exactly your branch changes!)
So the --reintegrate
option only merges the changes that are unique to the feature branch. But if you always synchronise before merge (which is a recommended practice, in order to deal with any conflicts on the feature branch), then the only changes between the branches are the changes that are unique to the feature branch, right? And if Subversion tries to merge code that is already on the target branch, it will just do nothing, right?
In a blog post, Mark Phippard writes:
If we include those synched revisions, then we merge back changes that already exist in trunk. This yields unnecessary and confusing conflicts.
Is there an example of when dropping reintegrate gives me unnecessary conflicts?
Let me explain when --reintegrate
is absolutely necessary.
Consider the following use case.
- you have project p1 under p1/trunk. The project has a file,
readme.txt
, with one line "line1"<
- Create a new branch, p1/branches/br1
- Stay in trunk. Add line "line2" to
readme.txt
and commit it to trunk
- Switch to the
p1/branches/br1
branch. Update to HEAD.
- Merge from trunk to this branch (to pick up trunk changes).
- You should have
line1
and line2
in readme.txt
- Commit merge the result to
p1/branches/br1
branch
- Switch to trunk. Update to HEAD.
- Merge from
p1/branches/br1 to trunk.
- You'll see
line1
, line2
and line2
in readme.txt
. So, you have "line2" two times which is incorrect. SVN does not show any conflicts. So, it is very dangerous because merge performed with no errors and you are under impression that everything is fine.
The solution here is that the step 9 merge should be done using the --reintegrate
option. The reintegrate option tells SVN to compare br1
with trunk and apply only br1
changes to trunk. In this particular case we have not done any changes in br1
. The result in trunk should be two lines "line1" and "line2".
Another useful remark. Branch p1/branches/br1
should not be used for development after step 9 anymore. If you want to continue development in branches, create a new branch, for example, p1/branches/br2
. Another merge from trunk to p1/branches/br1
causes lots of conflicts.
It is never necessary to use --reintegrate
; it's a convenience. If your most recent merge from trunk
to feature-branch
merged all of the changes that occurred in trunk
since you branched up to revision rev
, then you could use the following command.
svn merge url://trunk@rev url://feature-branch .
Note that this command would be run in the root of an up-to-date working copy of trunk
with no outstanding changes to be committed.
Let me expand my answer to more directly answer the question "Is there an example of when dropping reintegrate gives me unnecessary conflicts?"
Here's what the article means by "If we include those synched revisions, then we merge back changes that already exist in trunk. This yields unnecessary and confusing conflicts."
Including the synched revisions would look like this:
svn merge -r N:HEAD url://feature-branch .
Where .
is a clean working copy of trunk and N
is the revision that feature-branch
was created from trunk
. That merge command merges all of the changes committed to the feature-branch
since it was branched, including those changes that were merged from trunk
after the feature-branch
was created. That means changes already made to trunk
would be included in the merge above. You'd be telling Subversion to apply changes to trunk
that actually originated in trunk
, which results in conflicts.
I think that Mark means it avoids comparing two files which have been modified, one to reintegrate from the branch and its corresponding file in the trunk, when both have been synchronized (and not just changed locally in their respective branch).
Let's assume we have trunk/a.c
and branches/dev/a.c
, with trunk/a.c
modified at some point and re-integrated in the branch later with a merge. As you pointed out, it's a good practice to do that before putting everything back to the trunk.
So the next step would be that merging back to the trunk, where a.c
are "different" on both sides since they have changed at both locations. Without the option there will be an unnecessary comparison, wheras the --reintegrate
will make SVN see the change was not just local.
It’s never necessary to use --reintegrate
— it’s simply an alias. If you have a working copy of trunk
, then
svn merge --reintegrate url://feature-branch workingcopy
is the same as
svn merge url://trunk url://feature-branch workingcopy
You can use whichever one you’re more comfortable with.