When is the reintegrate option really necessary?

Question

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?

Answer 1

Let me explain when --reintegrate is absolutely necessary.

Consider the following use case.

1. you have project p1 under p1/trunk. The project has a file, readme.txt, with one line "line1"<
2. Create a new branch, p1/branches/br1
3. Stay in trunk. Add line "line2" to readme.txt and commit it to trunk
4. Switch to the p1/branches/br1 branch. Update to HEAD.
5. Merge from trunk to this branch (to pick up trunk changes).
6. You should have line1 and line2 in readme.txt
7. Commit merge the result to p1/branches/br1 branch
8. Switch to trunk. Update to HEAD.
9. Merge from p1/branches/br1 to trunk.
   1. 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.

Answer 2

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.

Answer 3

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.

Answer 4

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.