[SvnBook] #62: [PATCH] Hanchrow review [ch3:ch4]

SvnBook noreply at red-bean.com
Tue Aug 14 23:00:22 CDT 2007

#62: [PATCH] Hanchrow review [ch3:ch4]
  Reporter:  cmpilato     |       Owner:  sussman      
      Type:  enhancement  |      Status:  new          
  Priority:  normal       |   Milestone:  1.4          
 Component:  content      |     Version:  nightly/trunk
Resolution:               |    Keywords:               
Changes (by cmpilato):

  * owner:  cmpilato => sussman


 Chapter 3 stuff reviewed and applied.  Handing off to sussman for the ch04
 stuff.  Here's an updated patch which applies cleanly as of this moment.

 Index: ch04-branching-and-merging.xml
 --- ch04-branching-and-merging.xml      (revision 2851)
 +++ ch04-branching-and-merging.xml      (working copy)
 @@ -105,6 +105,12 @@

      <para>Let's say that you've been given the task of performing a
 +      <!-- this is probably silly, but I would hesitate to suggest
 +      that someone use branches to "reorganize" a product, as long as
 +      issue 2685 is open.  I'd instead simply say "rewrite" or "make
 +      real big changes to".  (I now notice that you address precisely
 +      this bug below, in the section
 +      svn.branchmerge.copychanges.bestprac.moves; excellent) -->
        radical reorganization of the project.  It will take a long time
        to write, and will affect all the files in the project.  The
        problem here is that you don't want to interfere with Sally, who
 @@ -225,7 +231,10 @@
  Committed revision 341.

 -      <para>There's really no difference between these two methods.
 +      <!-- but from the user's point of view, there's a HUGE
 +      difference: the first method requires that they download a
 +      potentially large amount of data from the repository. -->
 +      <para>From the repository's point of view, there's really no
 difference between these two methods.
          Both procedures create a new directory in revision 341, and
          the new directory is a copy of
          <filename>/calc/trunk</filename>.  This is shown in
 @@ -257,9 +266,9 @@
            duplicate any data.  Instead, it creates a new directory
            entry that points to an <emphasis>existing</emphasis> tree.
            If you're a Unix user, this is the same concept as a
 -          hard-link.  As further changes are made to files and
 +          <quote>hard link</quote>.  As further changes are made to files
            directories beneath the copied directory, Subversion
 -          continues to employ this hard-link concept where it can.  It
 +          continues to employ this <quote>hard link</quote> concept where
 it can.  It
            only duplicates data when it is necessary to disambiguate
            different versions of objects.</para>

 @@ -273,6 +282,7 @@
            more about this, visit Subversion's website and read about
            the <quote>bubble up</quote> method in Subversion's design
 +        <!-- why not include a link to doc/design/server.xml? -->

          <para>Of course, these internal mechanics of copying and
            sharing data are hidden from the user, who simply sees
 @@ -302,8 +312,8 @@

        <para>There's nothing special about this working copy; it simply
          mirrors a different directory in the repository.  When you
 -        commit changes, however, Sally won't ever see them when she
 -        updates.  Her working copy is of
 +        commit changes, however, Sally won't see them when she
 +        updates, because her working copy is of
          <filename>/calc/trunk</filename>.  (Be sure to read <xref
          linkend="svn.branchmerge.switchwc"/> later in this chapter: the
          <command>svn switch</command> command is an alternate way of
 @@ -637,7 +647,7 @@
            way to represent changes to <emphasis>trees</emphasis>, such
            as the addition, removal, or renaming of files and
            directories.  Nor can the <command>patch</command> program
 -          notice changes to property changes.  If Sally's change had,
 +          notice changes to properties.  If Sally's change had,
            say, added a new directory, the output of <command>svn
            diff</command> wouldn't have mentioned it at
            all.  <command>svn diff</command> only outputs the limited
 @@ -860,7 +870,9 @@
          <para>The <option>--dry-run</option> option doesn't actually
            apply any local changes to the working copy.  It only shows
            status codes that <emphasis>would</emphasis> be printed in a
 -          real merge.  It's useful for getting a <quote>high
 +          real merge. <!-- I have a sneaking suspicion that - -dry-run
 +          doesn't always announce every status code, but I can't prove
 +          it  :-(  --> It's useful for getting a <quote>high
            level</quote> preview of the potential merge, for those
            times when running <command>svn diff</command> gives too
            much detail.</para>
 @@ -897,7 +909,7 @@
            compare the wrong two trees, creating a delta that doesn't
            apply cleanly.  <command>svn merge</command> will do its
            best to apply as much of the delta as possible, but some
 -          parts may be impossible.  Just like the Unix
 +          parts may be impossible.  Just as the Unix
            <command>patch</command> command sometimes complains about
            <quote>failed hunks</quote>, <command>svn merge</command>
            will complain about <quote>skipped targets</quote>:</para>
 @@ -922,9 +934,15 @@
            likely comparing the wrong two trees; they're the classic
            sign of user error.  When this happens, it's easy to
            recursively revert all the changes created by the merge
 -          (<command>svn revert --recursive</command>), delete any
 -          unversioned files or directories left behind after the
 -          revert, and re-run <command>svn merge</command> with
 +          (<command>svn revert --recursive</command>),
 +          <!-- Why must we delete unversioned stuff?  And can you
 +          suggest a convenient method of doing that, when there are a
 +          lot of unversioned objects?-->
 +          delete any unversioned files or directories left behind
 +          after the revert,
 +                  and re-run <command>svn merge</command> with
            different arguments.</para>

          <para>Also notice that the previous example shows a conflict
 @@ -967,6 +985,7 @@
            describe the relationship between two objects in a
            repository: if they're related to each other, then one
            object is said to be an ancestor of the other.</para>
 +        <!-- might they not instead merely have a _common_ ancestor? -->

          <para>For example, suppose you commit revision 100, which
            includes a change to a file <filename>foo.c</filename>.
 @@ -983,8 +1002,8 @@

          <para>The reason for bringing this up is to point out an
            important difference between <command>svn diff</command> and
 -          <command>svn merge</command>.  The former command ignores
 -          ancestry, while the latter command is quite sensitive to it.
 +          <command>svn merge</command>: <command>svn diff</command>
 +          ancestry, while <command>svn merge</command> is quite sensitive
 to it.
            For example, if you asked <command>svn diff</command> to
            compare revisions 99 and 102 of <filename>foo.c</filename>,
            you would see line-based diffs; the <literal>diff</literal>
 @@ -1009,9 +1028,8 @@
            If you asked <command>svn merge</command> to compare the two
            trees, you'd see the entire first tree being deleted,
 -          followed by an add of the entire second tree!</para>
 -        <para>In these situations, you'll want <command>svn
 +          followed by an add of the entire second tree!
 +          In these situations, you'll want <command>svn
            merge</command> to do a path-based comparison only, ignoring
            any relations between files and directories.  Add the
            <option>--ignore-ancestry</option> option to your merge
 @@ -1414,9 +1432,9 @@
          particular revision tree, and the second coordinate is a path
          within that tree.  So every version of your file or directory
          can be defined by a specific coordinate pair.  (Remember the
 -        familiar <quote>peg revision</quote> syntax—foo.c at 224
 -        —mentioned back in
 -        <xref linkend="svn.advanced.pegrevs"/>.) </para>
 +        <quote>peg revision</quote>
 +        syntax—foo.c at 224—mentioned back in <xref
 +        linkend="svn.advanced.pegrevs"/>?) </para>

        <para>First, you might need to use <command>svn log</command> to
          discover the exact coordinate pair you wish to resurrect.  A
 @@ -1734,8 +1752,8 @@

      <para>The <command>svn switch</command> command transforms an
        existing working copy to reflect a different branch.  While this
 -      command isn't strictly necessary for working with branches, it
 -      provides a nice shortcut to users.  In our earlier example,
 +      command isn't strictly necessary for working with branches, it's
 +      a nice shortcut.  In our earlier example,
        after creating your private branch, you checked out a fresh
        working copy of the new repository directory.  Instead, you can
        simply ask Subversion to change your working copy of
 @@ -1760,7 +1778,11 @@

      <para>After <quote>switching</quote> to the branch, your working
        copy is no different than what you would get from doing a fresh
 -      checkout of the directory.  And it's usually more efficient to
 +      checkout of the directory.
 +      <!-- not true -- if the original wc has un-checked-in changes,
 +      "switching" will preserve them, whereas a fresh checkout of
 +      course won't have them. -->
 +                                  And it's usually more efficient to
        use this command, because often branches only differ by a small
        degree.  The server sends only the minimal set of changes
        necessary to make your working copy reflect the branch
 @@ -1768,7 +1790,7 @@

      <para>The <command>svn switch</command> command also takes a
        <option>--revision</option> (<option>-r</option>) option, so you
 -      need not always move your working copy to the <quote>tip</quote>
 +      need not always move your working copy to the
        of the branch.</para>

      <para>Of course, most projects are more complicated than our
 @@ -1995,6 +2017,11 @@
          snapshot of your working copy—mixed revisions, URLs,
          and all.</para>

 +      <!-- I can't remember the details, but I'm _certain_ that Ben
 +      has advised against making a branch this way.  Perhaps a warning
 +      would be in order here: "this technique works fine for tags, but
 +      beware if you make a branch this way, you can run into trouble
 +      when you later try to merge ..." -->
        <para>Other users have found interesting uses for this feature.
          Sometimes there are situations where you have a bunch of local
          changes made to your working copy, and you'd like a
 @@ -2003,7 +2030,7 @@
          tree changes, symlink changes or changes in properties), you can
          instead use <command>svn copy</command> to <quote>upload</quote>
          your working copy to a private area of the repository.  Your
 -        collaborator can then either checkout a verbatim copy of your
 +        collaborator can then either check out a verbatim copy of your
          working copy, or use <command>svn merge</command> to receive
          your exact changes.</para>

 @@ -2060,6 +2087,7 @@
        <para>Of course, you're free to ignore these common layouts.
          You can create any sort of variation, whatever works best for
          you or your team.  Remember that whatever you choose, it's not
 +        <!-- the caveat about 2685 applies here -->
          a permanent commitment.  You can reorganize your repository at
          any time.  Because branches and tags are ordinary directories,
          the <command>svn move</command> command can move or rename
 @@ -2229,7 +2257,7 @@
        the vendor's data that you decide to absorb into your project is
        called a <firstterm>vendor drop</firstterm>.</para>

 -    <para>Vendor branches provide two key benefits.  First, by storing
 +    <para>Vendor branches provide two benefits.  First, by storing
        the currently supported vendor drop in your own version control
        system, the members of your project never need to question
        whether they have the right version of the vendor's data.  They
 @@ -2321,7 +2349,7 @@
          changes made to libcomplex between versions 1.0 and 1.1 to our
          modified copy of it.</para>

 -      <para>To perform this upgrade, we checkout a copy of our vendor
 +      <para>To perform this upgrade, we check out a copy of our vendor
          branch, and replace the code in the
          <filename>current</filename> directory with the new libcomplex
          1.1 source code.  We quite literally copy new files on top of
 @@ -2454,8 +2482,11 @@
        <para>You can indicate that you'd like
          <command>svn_load_dirs.pl</command> to tag the new vendor drop
          by passing the <option>-t</option> command-line option and
 -        specifying a tag name.  This tag is another URL relative to
 -        the first program argument.</para>
 +        specifying a tag name.  <!-- a tad unclear; I had to read it
 +        twice to understand it.  Maybe instead say something like "The
 +        tag directory will be created under the directory specified by
 +        the first program argument."--> This tag is another URL
 +        relative to the first program argument.</para>

  $ svn_load_dirs.pl -t libcomplex-1.1                              \
 @@ -2472,8 +2503,8 @@
          one version and not the other, and the script will perform the
          new import without incident.  If, however, there are
          discrepancies in the file layouts between versions,
 -        <command>svn_load_dirs.pl</command> will prompt you for how
 -        you would like to resolve those differences.  For example, you
 +        <command>svn_load_dirs.pl</command> will ask you how
 +        to resolve those differences.  For example, you
          will have the opportunity to tell the script that you know
          that the file <filename>math.c</filename> in version 1.0 of
          libcomplex was renamed to <filename>arithmetic.c</filename> in

Ticket URL: <http://svnbook.red-bean.com/trac/ticket/62#comment:4>
SvnBook <http://svnbook.red-bean.com/>

More information about the svnbook-dev mailing list