[svnbook] r4186 committed - * en/book/ch04-branching-and-merging.xml...

svnbook at googlecode.com svnbook at googlecode.com
Wed Nov 9 14:08:36 CST 2011


Revision: 4186
Author:   cmpilato at gmail.com
Date:     Wed Nov  9 12:07:47 2011
Log:      * en/book/ch04-branching-and-merging.xml
   Edits from my read-thru of Chapter 4 (including the removal of the
   seemingly unnecessary zone="" attribute found on some <indexterm>
   tags...)

http://code.google.com/p/svnbook/source/detail?r=4186

Modified:
  /trunk/en/book/ch04-branching-and-merging.xml

=======================================
--- /trunk/en/book/ch04-branching-and-merging.xml	Wed Nov  9 09:18:25 2011
+++ /trunk/en/book/ch04-branching-and-merging.xml	Wed Nov  9 12:07:47 2011
@@ -480,7 +480,7 @@
      <sidebar id="svn.branchmerge.basicmerging.mergetracking">
        <title>Merge Tracking</title>
        <para>
-        <indexterm zone="svn.branchmerge.basicmerging.mergetracking">
+        <indexterm>
            <primary>merge tracking</primary>
          </indexterm>
          Subversion 1.5 introduced the
@@ -550,11 +550,15 @@
        <para>Continuing with our running example, let's suppose that a
          week has passed since you started working on your private
          branch.  Your new feature isn't finished yet, but at the same
-        time you know that other people on your team continue to
-        make important changes in the
+        time you know that other people on your team continue to make
+        important changes in the
          project's <filename>/trunk</filename>.  It's in your best
          interest to replicate those changes to your own branch, just
-        to make sure they mesh well with your changes.</para>
+        to make sure they mesh well with your changes.  This is done
+        by performing a <firstterm>sync merge</firstterm>—a
+        merge operation designed to bring your branch up to date with
+        any changes made to its ancestral parent branch since your
+        branch was created.</para>

        <tip>
          <para>Frequently keeping your branch in sync with the main
@@ -564,9 +568,8 @@
        </tip>

        <para>Subversion is aware of the history of your branch and
-        knows when it split away from the trunk.  To replicate the
-        latest, greatest trunk changes to your branch, first make sure
-        your working copy of the branch
+        knows when it split away from the trunk.  To perform a sync
+        merge, first make sure your working copy of the branch
          is <quote>clean</quote>—that it has no local
          modifications reported by <command>svn status</command>.  Then
          simply run:</para>
@@ -588,17 +591,18 @@

        <para>This basic syntax—<userinput>svn merge
          <replaceable>URL</replaceable></userinput>—tells
-        Subversion to merge all recent changes from the URL to the
-        current working directory (which is typically the root of your
-        working copy).  Notice that we're using the caret
-        (<literal>^</literal>) syntax<footnote><para>This was
-        introduced in svn 1.6.</para></footnote> to avoid having to
-        type out the entire <filename>/trunk</filename> URL.
-        Also note the notification <quote>--- Recording mergeinfo
-        for merge...</quote>.  This tells you that the merge is
-        updating the <literal>svn:mergeinfo</literal> property. We'll
-        discuss both this property and these notifications later in
-        this chapter, see
+        Subversion to merge all changes which have not been previously
+        merged from the URL to the current working directory (which is
+        typically the root of your working copy).  Notice that we're
+        using the caret (<literal>^</literal>)
+        syntax<footnote><para>This was introduced in svn
+        1.6.</para></footnote> to avoid having to type out the
+        entire <filename>/trunk</filename> URL.  Also note
+        the <quote>Recording mergeinfo for merge…</quote>
+        notification.  This tells you that the merge is updating
+        the <literal>svn:mergeinfo</literal> property. We'll discuss
+        both this property and these notifications later in this
+        chapter, in
          <xref linkend="svn.branchmerge.basicmerging.mergeinfo"/>.</para>

        <tip>
@@ -616,13 +620,17 @@
          <title>Keeping a Branch in Sync Without Merge Tracking</title>

          <para>You may not always be able to use Subversion's merge
-          tracking feature, perhaps your server is using Subversion 1.4
-          or earlier.  In a case like this the <command>merge</command>
-          subcommand is <emphasis>not</emphasis> aware of the history of
-          your branch or when it split away from the trunk. To replicate
-          the most recent trunk changes you need to perform sync merges
-          the <quote>old-fashioned</quote> way, by specifying a starting
-          and ending revision.</para>
+          tracking feature, perhaps because your server is running
+          Subversion 1.4 or earlier.  In such a scenario, you can of
+          course still perform merges, but Subversion will need you to
+          manually do many of the historical calculations that it
+          automatically does on your behalf when the merge tracking
+          feature is available.</para>
+
+        <para>To replicate the most recent trunk changes you need to
+          perform sync merges the <quote>old-fashioned</quote>
+          way—by specifying ranges of revisions you wish to
+          merge.</para>

          <para>Let's say you branched <filename>/trunk</filename> to
            <filename>/branches/foo-feature</filename> in revision
@@ -641,10 +649,10 @@
  </screen>
          </informalexample>

-        <para>When you are ready to sync your branch with the ongoing
-          changes from trunk, you specify the starting revision as the
-          revision of <filename>/trunk</filename> which the branch was
-          copied from and the ending revision as
+        <para>When you are ready to syncronize your branch with the
+          ongoing changes from trunk, you specify the starting
+          revision as the revision of <filename>/trunk</filename>
+          which the branch was copied from and the ending revision as
            <literal>HEAD</literal>:</para>

          <informalexample>
@@ -658,9 +666,14 @@
  </screen>
          </informalexample>

-        <para>You'll need to track which revisions were merged to your
-          branch.  One of the simplest ways to do this is in the log
-          message for the commit of the merge:</para>
+        <para>After any conflicts have been resolved, you can commit
+          the merged changed to your branch.  Now, to avoid
+          accidentally trying to merge these same changes into your
+          branch again in the future, you'll need to record the fact
+          that you've already merged them.  But where should that
+          record be kept?  One of the simplest places to record this
+          information is in the log message for the commit of the
+          merge:</para>

          <informalexample>
            <screen>
@@ -673,10 +686,15 @@
          </informalexample>

          <para>The next time you sync
-        <filename>/branches/foo-branch</filename> with
-        <filename>/trunk</filename> you repeat this process, except that
-        the starting revision is the <emphasis>youngest</emphasis>
-        revision your last sync brought in from trunk:</para>
+          <filename>/branches/foo-branch</filename> with
+          <filename>/trunk</filename> you repeat this process, except that
+          the starting revision is the <emphasis>youngest</emphasis>
+          revision that's already been merged in from the trunk.
+          If you've been keeping good records of your merges in the
+          commit log messages, you should be able to determine what
+          that youngest revision was by reading the revision logs
+          associated with your branch.  Once you know your starting
+          revision, you can perform another sync merge:</para>

          <informalexample>
            <screen>
@@ -706,7 +724,7 @@
          carefully with <command>svn diff</command>, and then build and
          test your branch.  Notice that the current working directory
          (<quote><filename>.</filename></quote>) has also been
-        modified; the <command>svn diff</command> will show that
+        modified; <command>svn diff</command> will show that
          its <literal>svn:mergeinfo</literal> property has been either
          created or modified.  This is important merge-related metadata
          that you should <emphasis>not</emphasis> touch, since it is
@@ -715,14 +733,14 @@
          chapter.)</para>

        <para>After performing the merge, you might also need to resolve
-        some conflicts (just as you do with <command>svn
-        update</command>) or possibly make some small edits to get
+        some conflicts—just as you do with <command>svn
+        update</command>—or possibly make some small edits to get
          things working properly.  (Remember, just because there are
          no <emphasis>syntactic</emphasis> conflicts doesn't mean there
          aren't any <emphasis>semantic</emphasis> conflicts!)  If you
          encounter serious problems, you can always abort the local
          changes by running <userinput>svn revert . -R</userinput> (which
-        will undo all local modifications) and start a
+        will undo all local modifications) and starting a
          long <quote>what's going on?</quote> discussion with your
          collaborators.  If things look good, however, you can
          submit these changes into the repository:</para>
@@ -740,10 +758,9 @@
        </informalexample>

        <para>At this point, your private branch is now <quote>in
-          sync</quote> with the trunk, so you can rest easier knowing
-          that as you continue to work in isolation, you're not
-          drifting too far away from what everyone else is
-          doing.</para>
+        sync</quote> with the trunk, so you can rest easier knowing
+        that as you continue to work in isolation, you're not drifting
+        too far away from what everyone else is doing.</para>

        <sidebar>
          <title>Why Not Use Patches Instead?</title>
@@ -810,28 +827,32 @@
        <informalexample>
          <screen>
  $ svn merge ^/calc/trunk
-svn: E195020: Cannot merge into mixed-revision working copy [357:378]; try  
updating first
+svn: E195020: Cannot merge into mixed-revision working copy [357:378]; try  
up\
+dating first
+$
  </screen>
        </informalexample>

-      <para>Well that was unexpected! What happened was that while
-        making changes to your branch over the past week you now have
-        a working copy that is at mixed-revisions
-        (see <xref linkend="svn.basic.in-action.mixedrevs"/>).  With
-        the release of Subversion 1.7 the <command>svn merge</command>
-        subcommand disables merges into mixed-revision working copies by
-        default.  Without going into too much detail, this is because of
-        limitations in the way merges are tracked by the
+      <para>Well that was unexpected!  After making changes to your
+        branch over the past week you now find yourself with a working
+        copy that contains a mixture of revisions (see
+        <xref linkend="svn.basic.in-action.mixedrevs"/>).  With the
+        release of Subversion 1.7 the <command>svn merge</command>
+        subcommand disables merges into mixed-revision working copies
+        by default.  Without going into too much detail, this is
+        because of limitations in the way merges are tracked by the
          <literal>svn:mergeinfo</literal> property (see
-        <xref linkend="svn.branchmerge.basicmerging.mergeinfo"/>
-        for details).  These limitations mean that merges into
+        <xref linkend="svn.branchmerge.basicmerging.mergeinfo"/> for
+        details).  These limitations mean that merges into
          mixed-revision working copies can result in unexpected text
-        and tree conflicts.<footnote><para>The <command>svn merge</command>
-        subcommand option <option>--allow-mixed-revisions</option> allows
-        you to override this prohibition, but you should only do that if  
you
-        understand the ramifications and have a good reason for doing so.
-        </para></footnote> We don't want any needless conflicts, so we
-        update the working copy and then reattempt the merge.</para>
+        and tree conflicts.<footnote><para>The <command>svn
+        merge</command> subcommand
+        option <option>--allow-mixed-revisions</option> allows you to
+        override this prohibition, but you should only do so if you
+        understand the ramifications and have a good reason for
+        it.</para></footnote>  We don't want any needless conflicts, so
+        we update the working copy and then reattempt the
+        merge.</para>

        <informalexample>
          <screen>
@@ -859,10 +880,10 @@
        <sidebar id="svn.branchemerge.basicmerging.stayinsync.subtree">
          <title>Subtree Merges and Subtree Mergeinfo</title>
          <para>
-          <indexterm  
zone="svn.branchemerge.basicmerging.stayinsync.subtree">
+          <indexterm>
              <primary>subtree merge</primary>
            </indexterm>
-          <indexterm  
zone="svn.branchemerge.basicmerging.stayinsync.subtree">
+          <indexterm>
              <primary>subtree mergeinfo</primary>
            </indexterm>
            In most of the examples in this chapter the merge target is
@@ -873,14 +894,14 @@
            <firstterm>subtree merge</firstterm> and the mergeinfo recorded
            to describe it is called
            <firstterm>subtree mergeinfo</firstterm>. There is nothing
-          special about subtree merges or subtree mergeinfo, in fact
-          there is really only one important point to keep in mind about
-          these concepts: The complete record of merges to a branch may
-          not be contained solely in the mergeinfo on the branch root, we
-          may have to look to any subtree mergeinfo to get a full  
accounting.
-          Fortunately Subversion does this <quote>accounting</quote> for
-          you and rarely will you need to concern yourself with it.  A
-          brief example will help explain:</para>
+          special about subtree merges or subtree mergeinfo.  In fact
+          there is really only one important point to keep in mind
+          about these concepts: the complete record of merges to a
+          branch may not be contained solely in the mergeinfo on the
+          branch root.  You may have to look to any subtree mergeinfo
+          to get a full accounting.  Fortunately Subversion does this
+          for you and rarely will you need to concern yourself with
+          it.  A brief example will help explain:</para>

          <informalexample>
            <screen>
@@ -935,16 +956,16 @@
  </screen>
          </informalexample>

-        <indexterm zone="svn.branchemerge.basicmerging.stayinsync.subtree">
+        <indexterm>
            <primary>mergeinfo elision</primary>
          </indexterm>

-        <para>You might be wondering why <filename>INSTALL</filename> in
-          the above example has mergeinfo for r651-652, when we only
-          merged r958. This is due to mergeinfo inheritance, which we'll
-          cover shortly in the
-          <xref  
linkend="svn.branchmerge.basicmerging.mergeinfo.inheritance"/>
-          sidebar. Also note that the subtree mergeinfo on
+        <para>You might be wondering why <filename>INSTALL</filename>
+          in the above example has mergeinfo for r651-652, when we
+          only merged r958. This is due to mergeinfo inheritance,
+          which we'll cover in the sidebar
+          <xref  
linkend="svn.branchmerge.basicmerging.mergeinfo.inheritance"
+          />.  Also note that the subtree mergeinfo on
            <filename>doc/INSTALL</filename> was removed, or
            <quote>elided</quote>.  This is called
            <firstterm>mergeinfo elision</firstterm> and it occurs
@@ -982,7 +1003,7 @@
          Your new feature is done, and you're ready to merge your
          branch changes back to the trunk (so your team can enjoy the
          bounty of your labor).  The process is simple.  First, bring
-        your branch in sync with the trunk again, just as you've been
+        your branch into sync with the trunk again, just as you've been
          doing all along<footnote><para>With Subversion 1.7 you don't
          absolutely have to do all your sync merges to the root of your
          branch as we do in this example.  <emphasis>If</emphasis> your
@@ -1012,19 +1033,19 @@
  </screen>
        </informalexample>

-      <para>Now, you use <command>svn merge</command> with the
-        <option>--reintegrate</option> option to replicate your
-        branch changes back into the trunk.  You'll need a working
-        copy of <filename>/trunk</filename>.  You can do this by
-        either doing an <command>svn checkout</command>, dredging up
-        an old trunk working copy from somewhere on your disk, or
-        using <command>svn switch</command>
-        (see <xref linkend="svn.branchmerge.switchwc"/>).
-        Your trunk working copy cannot have any local edits or be at
-        mixed-revisions
-        (see <xref linkend="svn.basic.in-action.mixedrevs"/>).  While
-        these are typically best practices for merging, they are
-        <emphasis>required</emphasis> when using the
+      <para>Now, use <command>svn merge</command> with the
+        <option>--reintegrate</option> option to replicate your branch
+        changes back into the trunk.  You'll need a working copy
+        of <filename>/trunk</filename>.  You can get one by doing
+        an <command>svn checkout</command>, dredging up an old trunk
+        working copy from somewhere on your disk, or
+        using <command>svn switch</command> (see
+        <xref linkend="svn.branchmerge.switchwc" />).  Your trunk
+        working copy cannot have any local edits or contain a mixture
+        of revisions (see
+        <xref linkend="svn.basic.in-action.mixedrevs" />).  While
+        these are typically best practices for merging anyway, they
+        are <emphasis>required</emphasis> when using the
          <option>--reintegrate</option> option.</para>

        <para>Once you have a clean working copy of the trunk, you're
@@ -1059,14 +1080,14 @@
  </screen>
        </informalexample>

-      <para>Congratulations, your branch has now been remerged back
-        into the main line of development.  Notice our use of
-        the <option>--reintegrate</option> option this time around.
-        The option is critical for reintegrating changes from a branch
-        back into its original line of development—don't forget
-        it!  It's needed because this sort of <quote>merge
-        back</quote> is a different sort of work than what you've
-        done up until now.  Previously, we were
+      <para>Congratulations, your branch-specific changes have now
+        been merged back into the main line of development.  Notice
+        our use of the <option>--reintegrate</option> option this time
+        around.  The option is critical for reintegrating changes from
+        a branch back into its original line of
+        development—don't forget it!  It's needed because this
+        sort of <quote>merge back</quote> is a different sort of work
+        than what you've done up until now.  Previously, we were
          asking <command>svn merge</command> to grab the <quote>next
          set</quote> of changes from one line of development (the
          trunk) and duplicate them to another (your branch).  This is
@@ -1078,7 +1099,7 @@
          merges the range 380:385.</para>

        <para>When merging your branch back to the trunk, however, the
-        underlying mathematics is quite different.  Your feature
+        underlying mathematics are quite different.  Your feature
          branch is now a mishmash of both duplicated trunk changes and
          private branch changes, so there's no simple contiguous range
          of revisions to copy over.  By specifying
@@ -1272,16 +1293,17 @@
        <sidebar id="svn.branchmerge.basicmerging.mergeinfo.inheritance">
          <title>Mergeinfo Inheritance</title>

-        <indexterm  
zone="svn.branchmerge.basicmerging.mergeinfo.inheritance">
+        <indexterm>
            <primary>mergeinfo inheritance</primary>
          </indexterm>

          <para>When a path has the <literal>svn:mergeinfo</literal>
-          property set on it we say it has <quote>explicit</quote>
-          mergeinfo.  This explicit mergeinfo describes not only what
-          changes were merged into that particular directory, but also
-          all the children of that directory (because those children
-          inherit the mergeinfo of their parent path).  For example:</para>
+          property set on it we say it has <firstterm>explicit
+          mergeinfo</firstterm>.  This explicit mergeinfo describes
+          not only what changes were merged into that particular
+          directory, but also all the children of that directory
+          (because those children inherit the mergeinfo of their
+          parent path).  For example:</para>

          <informalexample>
            <screen>
@@ -1515,7 +1537,7 @@
          merge</command> to apply a changeset, or a whole range of
          changesets, to your working copy.  In our case of undoing a
          change, we're asking <command>svn merge</command> to apply
-        changeset #303 to our working copy
+        changeset r303 to our working copy
          <emphasis>backward</emphasis>.</para>

        <para>Keep in mind that rolling back a change like this is just
@@ -2321,7 +2343,7 @@
  </screen>
        </informalexample>

-      <para>Since Subversion 1.7, <option>--record-only</option>
+      <para>Beginning with Subversion 1.7, <option>--record-only</option>
          merges are transitive.  This means that, in addition to recording
          mergeinfo describing the blocked revision(s), any
          <literal>svn:mergeinfo</literal> property differences in the
@@ -2367,13 +2389,14 @@
          <filename>^/trunk</filename> isn't foolproof since someone could
          merge r996:1003 directly from
          <filename>^/branches/frazzle-feature-branch</filename>.
-        Fortunately the transitive nature of <option>--record-only</option>
-        merges in 1.7 prevents this; the <option>--record-only</option>
-        merge applies the <literal>svn:mergeinfo</literal> diff from
-        revision 1055, thus blocking merges directly from the frazzle  
branch
-        <emphasis>and</emphasis> as it has always done prior to 1.7, it
-        blocks merges of revision 1055 directly from
-        <filename>^/trunk</filename>:</para>
+        Fortunately the transitive nature
+        of <option>--record-only</option> merges in Subversion 1.7
+        prevents this; the <option>--record-only</option> merge
+        applies the <literal>svn:mergeinfo</literal> diff from
+        revision 1055, thus blocking merges directly from the frazzle
+        branch <emphasis>and</emphasis> as it has always done prior to
+        Subversion 1.7, it blocks merges of revision 1055 directly
+        from <filename>^/trunk</filename>:</para>

        <informalexample>
          <screen>




More information about the svnbook-dev mailing list