Review of chapter 4 - Branching and Merging

Ben Collins-Sussman sussman at
Wed Mar 19 09:37:28 CDT 2008

Thanks for this great feedback!!

On Tue, Mar 18, 2008 at 9:13 PM, Julian Foad <julianfoad at> wrote:
> Dear book authors,
>  Here's a review of the merging aspects of chapter 4 (and related entries in
>  ch09 reference), including input from Paul Burba.
>  [[[
>  Branching and Merging (ch04)
>  ============================
>  Keeping a Branch in Sync
>  ------------------------
>  On first introducing the basic merge command, reinforce that "svn merge URL"
>  means to merge changes *from* URL into WC.
>  After reintegrating, say that I can continue working on the branch and catch
>  up and reintegrate again, or I can delete the branch, or leave it there and
>  make that decision later. (Paul noticed a bug in that self-referential
>  mergeinfo is currently created by these further catch-up and reintegrate
>  cycles; he will look into fixing this.)
>  The "reintegrate" option is explained well in terms of being the right way to
>  merge changes back to trunk in the example scenario. We need to explain also
>  the real meaning and distinction of the two forms of merge so that users can
>  see whether and how they can be applied to other scenarios. For example, if I
>  create a sub-feature branch B2 off feature branch B, can I then sync B2 from
>  trunk, from B, or from both trunk and B2 at arbitrary times, and can I then
>  reintegrate B2 to B, or B2 to trunk, or both or neither?
>  Say that "reintegrate" makes trunk be exactly like branch, by applying the
>  diff necessary to make it so.
>  Be stronger on the need for WC being up to date and clean. (Recommend using
>  "svn up" to ensure or "svnversion" to verify that WC is single-revision.) For
>  the "reintegrate" case, suggest replacing the text "However you get a trunk
>  working copy..." with something like:
>   "However you get a trunk working copy, remember that it must be fully
>  updated (no mixed-revision WCs allowed) and have no local edits. If your
>  working copy isn't "clean" in these ways, svn merge --reintegrate won't work
>  and will return an error."
>  For the normal "merge" command, what can we say about what happens if you
>  don't follow the recommendations on WC being up to date and clean?
>  Syntax (Full Disclosure)
>  ------------------------
>  Examples box: first example (a 2-URL merge) is potentially a non-tracking
>  merge, depending on the relationship between the sources. Mention this, with a
>  reference to the new "Merges that are Not Tracked" section.
>  Merges that are Not Tracked
>  ---------------------------
>  Create this new section, to mention at least:
>   - foreign-repository merges
>   - arbitrary diff-and-apply merges due to specifying two unrelated sources
>   - merges requested by "--ignore-ancestry"  - reverse-merging a change from a
>  path's own history (Note that it does work, but there is currently no way to
>  record the fact that it has been done.  This really gets into the whole idea
>  of a path's 'natural' history and how that is taken into a account *along
>  with* svn:mergeinfo...likely a topic too dense for the book?)
>  Resurrecting Deleted Items
>  --------------------------
>  This section is not closely related to merging; merging is just one of the
>  ways to resurrect deleted items. Consider moving this section out of the main
>  flow of information about merging. Insert a brief reference to it in the
>  "Undoing Changes" section. See also the "Data Lifetimes" section which repeats
>  this somewhat.
>  Blocking Changes
>  ----------------
>  This topic is not so much a primary topic but rather a side-bar on the extent
>  to which you can push Subversion.
>  By "faking" a merge (e.g. with --record-only or by resolving all changes as
>  --accept=mine), we can prevent particular revisions from being merged to the
>  destination branch. This can be useful on a branch that is never intended to
>  be merged back to its parent, such as a "release" branch.
>  This is not a proper "blocking" feature because the intent is not recorded.
>  What is recorded is just the same as if we'd performed the merge, but then
>  adjusted the resulting text back to what it was before, and this is
>  indistinguishable from the kind of editing we might have done in resolving a
>  conflict. As a consequence, if the branch is reintegrated to its parent then
>  the blocked changes will be removed from the parent.
>  Don't even suggest modifying the property with "propset".
>  Merge-sensitive Logs and Annotations
>  ------------------------------------
>  Log: does "-g" show all branches through which a given change has been merged
>  to reach the target branch, or just the nearest, or just the most distant?
>  Blame: same question.
>  Do the log and blame APIs allow the merges via intermediate branches to be
>  seen?
>  Noticing or Ignoring Ancestry
>  -----------------------------
>  Does "diff" really ignore ancestry by default, even when used in the
>  merge-like manner of "svn diff -r10:20 foo at 20"?
>  Mention that "diff" behaves like this *unless* the "--notice-ancestry" option
>  is given.
>  Data Lifetimes
>  --------------
>  Repeats the "Resurrecting Deleted Items" section somewhat.
>  Summary
>  -------
>  "Branches are cheap. So use them liberally!" - No! They're cheap to create, so
>  you shouldn't hesitate to create one when needed, but "use them liberally"
>  invites trouble.
>  ===========
>  How To Edit svn:mergeinfo
>  -------------------------
>  Syntax. Inheritance/elision. (Paul is working on a document describing this.)
>  Is there any caveat necessary for editing mergeinfo for an uncommitted merge
>  before resolving conflicts - e.g. if you edit mergeinfo on the root of your WC
>  and then resolve conflicts on some children, are there any circumstances under
>  which Subversion might invalidate your local corrections? We believe there are
>  no such surprises here, but it would be nice if somebody else could confirm.
>  Under what conditions is it safe to correct mergeinfo in a later commit after
>  the fact? - e.g. if you commit the manual merge (without mergeinfo) in r10,
>  then correct the mergeinfo in r20, can we say that everything will work
>  properly thereafter as long as you never merge in or out of that branch in a
>  way that splits the revision range 10-20?
>  ///
>  Reference (ch09)
>  ================
>  properties:
>   mention svn:mergeinfo
>  options:
>   --use-merge-history: wrongly mentions "svn copy/move" which don't take this
>  option.
>  svn merge:
>   mention --reintegrate
>  svn mergeinfo:
>   mention --from-source
>  ]]]
>  - Julian
>  _______________________________________________
>  svnbook-dev mailing list
>  svnbook-dev at

More information about the svnbook-dev mailing list