Subversion 1.5 merge-tracking in a nutshell

This entry was posted by on Saturday, 10 May, 2008 at

As I’ve mentioned in other posts, the Subversion project is on the verge of releasing version 1.5, a culmination of nearly two years of work. The release is jam-packed with some huge new features, but the one everyone’s excited about is “merge tracking”.

Merge-tracking is when your version control system keeps track of how lines of development (branches) diverge and re-form together. Historically, open source tools such as CVS and Subversion haven’t done this at all; they’ve relied on “advanced” users carefully examining history and typing arcane commands with just the right arguments. Branching and merging is possible, but it sure ain’t easy. Of course, distributed version control systems have now started to remove the fear and paranoia around branching and merging—they’re actually designed around merging as a core competency. While Subversion 1.5 doesn’t make it merging as easy as a system like Git or Mercurial, it certainly solves common points of pain. As a famous quote goes, “it makes easy things easy, and hard things possible.” Subversion is now beginning to match features in larger, commercial tools such as Clearcase and Perforce.

My collaborators and I are gearing up to release a 2nd Edition of the free online Subversion book soon (and you should be able to buy it from O’Reilly in hardcopy this summer.) If you want gritty details about how merging works, you can glance over Chapter 4 right now, but I thought a “nutshell” summary would make a great short blog post, just to show people how easy the common case now is.

  1. Make a branch for your experimental work:

    $ svn cp trunkURL branchURL
    $ svn switch branchURL

  2. Work on the branch for a while:

    # ...edit files
    $ svn commit
    # ...edit files
    $ svn commit

  3. Sync your branch with the trunk, so it doesn’t fall behind:

    $ svn merge trunkURL
    --- Merging r3452 through r3580 into '.':
    U button.c
    U integer.c
    ...

    $ svn commit

  4. Repeat the prior two steps until you’re done coding.
  5. Merge your branch back into the trunk:

    $ svn switch trunkURL
    $ svn merge --reintegrate branchURL
    --- Merging differences between repository URLs into '.':
    U button.c
    U integer.c
    ...

    $ svn commit

  6. Go have a beer, and live in fear of feature branches no more.

Notice how I never had to type a single revision number in my example: Subversion 1.5 knows when the branch was created, which changes need to be synced from branch to trunk, and which changes need to be merged back into the trunk when I’m done. It’s all magic now. This is how it should have been in the first place. :-)

Subversion 1.5 isn’t officially released yet, but we’re looking for people to test one of our final release candidate source tarballs. CollabNet has also created some nice binary packages for testing, as part of their early adopter program. Try it out and report any bugs!

42 Comments to Subversion 1.5 merge-tracking in a nutshell

  1. Dave R. says:

    May 11th, 2008 at 10:08 am

    Fantastic. This really is how it should have been done all along.

  2. Ian Clarke says:

    May 11th, 2008 at 11:21 am

    To use this merge-tracking feature, do I just need to install 1.5 locally, or must it also be installed on the Subversion server I use?

  3. Ben Collins-Sussman says:

    May 11th, 2008 at 4:01 pm

    @Ian: merge-tracking requires *both* a 1.5 client and 1.5 server. Full details are available at:

    http://subversion.tigris.org/svn_1.5_releasenotes.html

    Word of warning, though: if you touch an existing working copy with a 1.5 client, the working copy is ‘auto upgraded’ such that older clients can’t read it anymore. Same situation on the server side, except that you need to deliberately run ‘svnadmin upgrade’ on the repository to move it up to 1.5 format.

  4. Nick Parker says:

    May 11th, 2008 at 5:11 pm

    Ben,

    That is great news! I see 1.5 is currently on rc5, are there many more rc in queue before the release or are we near the end?

  5. links for 2008-05-11 « 個人的な雑記 says:

    May 11th, 2008 at 5:33 pm

    [...] iBanjo » Blog Archive » Subversion 1.5 merge-tracking in a nutshell (tags: subversion tools svn) [...]

  6. Webiest : Links for May 12th says:

    May 12th, 2008 at 2:00 am

    [...] iBanjo » Blog Archive » Subversion 1.5 merge-tracking in a nutshell – Merge-tracking is when your version control system keeps track of how lines of development (branches) diverge and re-form together. Historically, open source tools such as CVS and Subversion haven?t done this at all; they?ve relied on ?advanced? u [...]

  7. Subversion 1.5 merge tracking • cameronyule.com says:

    May 12th, 2008 at 3:42 am

    [...] great news coming from the Subversion developers recently, announcing that merge tracking will be included in the upcoming 1.5 release. From the announcement; Merge-tracking is when your version control [...]

  8. Cameron says:

    May 12th, 2008 at 4:35 am

    This might just stop a few people defecting to Git. Excellent news!

  9. João Marcus says:

    May 12th, 2008 at 6:28 am

    Well, finally SVN branches will stop being useless for me. Now if SVN only supported disconnected operations…

  10. David Edwards says:

    May 12th, 2008 at 6:47 am

    Wow, that looks so much more sane. Great stuff.

  11. C. Michael Pilato says:

    May 12th, 2008 at 8:10 am

    @Nick: Each “rc” is believed to be the last (else, it wouldn’t really be a (r)elease (c)andidate. But don’t let the “5″ scare you — we had quite a few false starts that never saw public release, and since we don’t ever re-use release numbers (even if the tarballs are DOA), the RC number ratcheted up a bit faster than usual.

  12. jackr says:

    May 12th, 2008 at 11:00 am

    Great capsule summary, Ben! I think I would have included an explicit “commit” as the first step of each merge or switch sequence, though, to point up the value of keeping the commits pure (and reverts possible).

  13. Tech Per says:

    May 12th, 2008 at 11:04 am

    Neat!

    How will this work, when one keeps merging the same branch back into trunk? Like I do, with each bug fix currently. Like this:

    Release 1.3.0 of my product, which i then TAG.

    A bug is reported. I do a 1_3_bugfix BRANCH, copied from 1.3.0 TAG. Fix the bug, TAG a 1.3.1 from branch, release and merge the branch bugfix back into trunk.

    A while passes, and shit, a new bug is discovered. I fix the bug right on the branch, TAG a 1.3.2, release and …

    This is when I usually need to merge only the 1.3.2 changes back, using revision numbers.

    Will this just be a –reintegrate, even though I have reintegrated before?

    Cause if it is, .. me like it :-)

  14. Sandy says:

    May 12th, 2008 at 6:04 pm

    @Tech Per: Read chapter 4 in the 1.5 book:

    “Now that your branch is merged to trunk, you have a couple of options. You can keep working on your branch, repeating the whole process of occasionally syncing with the trunk and eventually using –reintegrate to merge it back again. Or, if you’re really done with the branch, you can destroy your working copy of it and then remove it from the repository”

  15. Tech Per says:

    May 13th, 2008 at 1:22 am

    @Sandy: Thanks! I am already loving it. Gotta get 1.5 when it comes out. If I dare upgrade my repo :-)

  16.   Branches und Merges mit Subversion 1.5 von antiblau blog says:

    May 13th, 2008 at 2:23 am

    [...] Woche der RC 5 von Subversion 1.5 veröffentlicht wurde, beschreibt Ben Collins-Sussman heute in seinem Blog ganz kurz das Feature von Subversion 1.5, auf das viele warten. Subversion 1.5 behält selbst [...]

  17. Florian Potschka says:

    May 13th, 2008 at 8:18 am

    Great! This will make our lifes a lot easier. I’m really looking forward to the 2nd edition od the Subversion book” and release 1.5.

  18. Web Expose » Subversion 1.5 merge-tracking… looks awesome says:

    May 13th, 2008 at 8:37 am

    [...] more at the original post to see how easy this is: Subversion 1.5 merge-tracking in a nutshell. May 13th 2008 Posted to [...]

  19. Alan says:

    May 13th, 2008 at 9:43 am

    Wow. Subversion is my favorite centralized version control system. Now I have even a better reason to love it more. It is almost perfect for my needs.

  20. iBanjo » Blog Archive » Subversion 1.5.0 released says:

    June 19th, 2008 at 2:40 pm

    [...] resolution, and much much more all described here. I had previously posted about how easy it is to manage feature branches; now you can try it [...]

  21. Pierre Phaneuf says:

    June 23rd, 2008 at 6:49 am

    I’m wondering what is the difference between this new feature and using svnmerge.py (of which I have become quite adept, so I already wasn’t afraid of feature branches!)?

    My biggest issue is usually with renames, where it will usually lose the changes to the file if you’re not very careful.

  22. Subversion 1.5发布说明 -- Rock Sun’s Blog says:

    June 24th, 2008 at 12:15 am

    [...] Subversion 1.5 merge-tracking in a nutshell (blog post by Ben Collins-Sussman) [...]

  23. Tim Anderson’s ITWriting - Tech writing blog » What’s new in Subversion 1.5 says:

    July 2nd, 2008 at 7:05 am

    [...] user’s perspective, the difference is that branching and merging is just easier than before, as explained by Ben Sussman: Notice how I never had to type a single revision number in my example: Subversion 1.5 knows when [...]

  24. Submerged中文版 » Blog Archive » 简言叙之Subversion 1.5 Merge-Tracking says:

    July 10th, 2008 at 12:23 am

    [...] 原文链接:http://blog.red-bean.com/sussman/?p=92 Read More [...]

  25. MarkB says:

    July 28th, 2008 at 9:34 am

    I have a follow-up question to items 13 and 14 above in light of the statement in the current (r3212) Subversion book: “At the time of writing (Subversion 1.5), once a –reintegrate merge is done from branch to trunk, the branch is no longer usable for further work. It’s not able to correctly absorb new trunk changes, nor can it be properly reintegrated to trunk again.” Based on this statement the ability to repeatedly reintegrate described in #14 is not currently available.

    Item 13 describes the workflow I want to use on my project. Is it still a planned objective that will be achieved in a later svn release?

    Thank you.

  26. Ben Collins-Sussman says:

    July 28th, 2008 at 10:55 am

    @MarkB: try posting your question to the dev@subversion.tigris.org list.

  27. Preston Lee says:

    August 18th, 2008 at 4:23 pm

    Why is the “–reintegrate” option necessary?

  28. Ben Collins-Sussman says:

    August 18th, 2008 at 4:39 pm

    See http://svnbook.red-bean.com/nightly/en/svn.branchmerge.basicmerging.html#svn.branchemerge.basicmerging.stayinsync

    “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!)”

  29. Preston Lee says:

    August 27th, 2008 at 2:59 pm

    Thanks, Ben. I get that part, but what I don’t understand is why svn can’t figure out that you’re doing a reintegration on its own. If the feature branch keeps metadata on its own merge history, shouldn’t it be able to detect you’re doing a reintegration on its own? Also, I would generally like to keep a feature branch around for a week or two after reintegration just in case; is that planned for the future?

  30. Evert says:

    September 26th, 2008 at 12:53 pm

    Great feature! Works quite well, I did have a problem while trying to reintegrate:

    svn: Cannot reintegrate from ‘*url*’ yet:
    Some revisions have been merged under it that have not been merged
    into the reintegration target; merge them first, then retry.

    Pretty confusing message, I was able to fix it by removing all mergeinfo properties from the branch manually..

  31. Robz says:

    October 23rd, 2008 at 1:38 pm

    I have a question for you. With our scenario for locking down code for testing and user acceptance testing before it goes to prod, we may run into some syncing issues. It’s best to draw a picture:

    http://ferventcoder.com/archive/2008/10/23/call-for-input-branch-development-syncing-issue.aspx

  32. John Taylor says:

    April 23rd, 2009 at 6:20 pm

    What an excellent blog, I’ve added your feed to my RSS reader. :-)

  33. Notes on Merging using SVN and T-SVN « Rob Hubbard’s Blog says:

    September 10th, 2009 at 6:33 pm

    [...] Subversion 1.5 merge-tracking in a nutshell on Ben Collins-Sussman’s blog [...]

  34. SVN Merge – Selecting Changesets says:

    April 25th, 2010 at 7:16 pm

    [...] There is a summary of what to expect from Subversion Merge-Tracking feature here – Subversion 1.5 merge-tracking in a nutshell. [...]

  35. Subversion1.5发布说明 « 编程王网站 says:

    May 1st, 2010 at 8:04 am

    [...] Subversion 1.5 merge-tracking in a nutshell (blog post by Ben Collins-Sussman) [...]

  36. The art of war says:

    July 31st, 2010 at 1:40 am

    The art of war…

    2. ……

  37. Subversion 1.5 branching, merge-tracking | Ruby on Rails blog, scripts, tips says:

    September 28th, 2010 at 9:08 am

    [...] to Ben Collins-Sussman. Original post: Subversion 1.5 merge-tracking in a nutshell … other posts by [...]

  38. Good branch/merge tutorials for Tortoise SVN? « « Programmers Goodies Programmers Goodies says:

    July 2nd, 2011 at 11:16 pm

    [...] Subversion 1.5 merge-tracking in a nutshell [...]

  39. Branch / merge management in Subversion 1.5 - Programmers Goodies says:

    July 4th, 2011 at 2:21 pm

    [...] Here is a pretty basic overview of the process. [...]

  40. How to merge from branch to branch and back again (bidirectional merging) in SVN? - Programmers Goodies says:

    July 5th, 2011 at 11:32 am

    [...] It looks like you’re asking about 1.5 merge tracking. Here’s a quick overview for doing merges to/from trunk (or another branch): http://blog.red-bean.com/sussman/?p=92 [...]

  41. Una embarrada de feature branches | Blog Studio says:

    April 2nd, 2012 at 9:50 am

    [...] la subversion 1.5 existe un parámetro que permite hacer uso de la característica de merge tracking. Con esta mejora, reintegrar un feature branch hacia el trunk que tiene sincronizados los cambios [...]

  42. Subversion1.5发布说明 | 南龙的小站 says:

    July 6th, 2012 at 7:16 am

    [...] Subversion 1.5 merge-tracking in a nutshell (blog post by Ben Collins-Sussman) [...]