[svnbook commit] r3232 - trunk/src/en/book

sussman noreply at red-bean.com
Sat Aug 2 16:05:46 CDT 2008


Author: sussman
Date: Sat Aug  2 16:05:46 2008
New Revision: 3232

Log:
Enter first half of 2nd-round copyedits (most of them) to chapter 4.

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

Modified: trunk/src/en/book/ch04-branching-and-merging.xml
==============================================================================
--- trunk/src/en/book/ch04-branching-and-merging.xml	(original)
+++ trunk/src/en/book/ch04-branching-and-merging.xml	Sat Aug  2 16:05:46 2008
@@ -11,11 +11,11 @@
   <para>Branching, tagging, and merging are concepts common to
     almost all version control systems.  If you're not familiar with
     these ideas, we provide a good introduction in this chapter.  If
-    you are familiar, then hopefully you'll find it interesting to
+    you are familiar, hopefully you'll find it interesting to
     see how Subversion implements them.</para>
 
   <para>Branching is a fundamental part of version control.  If
-    you're going to allow Subversion to manage your data, then this
+    you're going to allow Subversion to manage your data, this
     is a feature you'll eventually come to depend on.  This chapter
     assumes that you're already familiar with Subversion's basic
     concepts (<xref linkend="svn.basic"/>).</para>
@@ -62,7 +62,7 @@
       branches by copying your data, and remembers that the copies are
       related to one another.  It also helps you duplicate changes
       from one branch to another.  Finally, it can make portions of
-      your working copy reflect different branches, so that you can
+      your working copy reflect different branches so that you can
       <quote>mix and match</quote> different lines of development in
       your daily work.</para>
 
@@ -75,7 +75,7 @@
     <title>Using Branches</title>
 
     <para>At this point, you should understand how each commit creates
-      an entire new filesystem tree (called a <quote>revision</quote>)
+      an entirely new filesystem tree (called a <quote>revision</quote>)
       in the repository.  If you don't, go back and read about revisions in
       <xref linkend="svn.basic.in-action.revs"/>.</para>
 
@@ -110,7 +110,7 @@
       process of fixing small bugs here and there.  She's depending on
       the fact that the latest version of the project (in
       <filename>/calc/trunk</filename>) is always usable.  If you
-      start committing your changes bit-by-bit, you'll surely break
+      start committing your changes bit by bit, you'll surely break
       things for Sally (and other team members as well).</para>
 
     <para>One strategy is to crawl into a hole: you and Sally can stop
@@ -125,14 +125,14 @@
       copy of <filename>/calc/trunk</filename> on two different
       machines), you'll need to manually copy your changes back and
       forth or just do all the work on a single computer.  By that
-      same token, it's difficult to share your changes-in-progress
+      same token, it's difficult to share your changes in progress
       with anyone else.  A common software development <quote>best
       practice</quote> is to allow your peers to review your work as
       you go.  If nobody sees your intermediate commits, you lose
       potential feedback and may end up going down the wrong path for
       weeks before another person on your team notices.  Finally, when
       you're finished with all your changes, you might find it very
-      difficult to re-merge your final work with the rest of the
+      difficult to remerge your final work with the rest of the
       company's main body of code.  Sally (or others) may have made
       many other changes in the repository that are difficult to
       incorporate into your working copy—especially if you
@@ -152,7 +152,7 @@
 
       <para>Creating a branch is very simple—you make a copy of
         the project in the repository using the <command>svn
-        copy</command> command.  Subversion is not only able to copy
+        copy</command> command.  Subversion is able to copy not only 
         single files, but whole directories as well.  In this case,
         you want to make a copy of the
         <filename>/calc/trunk</filename> directory.  Where should the
@@ -196,7 +196,7 @@
         within the working copy, this technique isn't recommended.  It
         can be quite slow, in fact!  Copying a directory on the
         client side is a linear-time operation, in that it actually
-        has to duplicate every file and subdirectory on local disk.
+        has to duplicate every file and subdirectory on the local disk.
         Copying a directory on the server, however, is a constant-time
         operation, and it's the way most people create
         branches.</para>
@@ -215,9 +215,9 @@
           duplicate any data.  Instead, it creates a new directory
           entry that points to an <emphasis>existing</emphasis> tree.
           If you're an experienced Unix user, you'll recognize this as
-          the same concept behind a hard-link.  As further changes are
+          the same concept behind a hard link.  As further changes are
           made to files and directories beneath the copied directory,
-          Subversion continues to employ this hard-link concept where
+          Subversion continues to employ this hard link concept where
           it can.  It duplicates data only when it is necessary to
           disambiguate different versions of objects.</para>
 
@@ -235,7 +235,7 @@
         <para>Of course, these internal mechanics of copying and
           sharing data are hidden from the user, who simply sees
           copies of trees.  The main point here is that copies are
-          cheap, both in time and space.  If you create a branch
+          cheap, both in time and in space.  If you create a branch
           entirely within the repository (by running <userinput>svn copy
           <replaceable>URL1</replaceable> <replaceable>URL2</replaceable></userinput>), it's a quick, constant-time operation.
           Make branches as often as you want.</para>
@@ -264,7 +264,7 @@
         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
+        <command>svn switch</command> command is an alternative way of
         creating a working copy of a branch.)</para>
 
       <para>Let's pretend that a week goes by, and the following
@@ -290,8 +290,8 @@
         </listitem>
       </itemizedlist>
 
-      <para>There are now two independent lines of development (shown
-        in <xref linkend="svn.branchmerge.using.work.dia-1"/>) happening on
+      <para>Now two independent lines of development (shown
+        in <xref linkend="svn.branchmerge.using.work.dia-1"/>) are happening on
         <filename>integer.c</filename>.</para>
 
       <figure id="svn.branchmerge.using.work.dia-1">
@@ -345,7 +345,7 @@
         It shows the creation of the branch as an event in the
         history, because <filename>integer.c</filename> was implicitly
         copied when all of <filename>/calc/trunk/</filename> was
-        copied.  Now look what happens when Sally runs the same
+        copied.  Now look at what happens when Sally runs the same
         command on her copy of the file:</para>
 
       <screen>
@@ -393,10 +393,10 @@
     <sect2 id="svn.branchmerge.using.concepts">
       <title>The Key Concepts Behind Branching</title> 
 
-      <para>There are two important lessons that you should remember
+      <para>You should remember two important lessons
         from this section.  First, Subversion has no internal concept
         of a branch—it knows only how to make copies.  When you
-        copy a directory, the resulting directory is only
+        copy a directory, the resultant directory is only
         a <quote>branch</quote> because <emphasis>you</emphasis>
         attach that meaning to it.  You may think of the directory
         differently, or treat it differently, but to Subversion it's
@@ -459,22 +459,22 @@
     <para>In the examples that follow, we're assuming that both your
       Subversion client and server are running Subversion 1.5 (or
       later).  If either client or server is older than version 1.5,
-      then things are more complicated: the system won't track changes
+      things are more complicated: the system won't track changes
       automatically, and you'll have to use painful manual methods to
       achieve similar results.  That is, you'll always need to use the
       detailed merge syntax to specify specific ranges of revisions to
-      replicate (See
+      replicate (see
       <xref linkend="svn.branchmerge.advanced.advancedsyntax"/> later
       in this chapter), and take special care to keep track of what's
       already been merged and what hasn't.  For this reason,
-      we <emphasis>strongly</emphasis> recommend making sure that your
-      client and server are at least version 1.5 or later.</para>
+      we <emphasis>strongly</emphasis> recommend that you make sure your
+      client and server are at least at version 1.5.</para>
 
   <!-- =============================================================== -->
     <sect2 id="svn.branchmerge.changesets">
       <title>Changesets</title>
 
-      <para>Before we get too far in, we should warn you that there's
+      <para>Before we proceed further, we should warn you that there's
         going to be a lot of discussion of <quote>changes</quote> in
         the pages ahead.  A lot of people experienced with version
         control systems use the terms <quote>change</quote>
@@ -483,9 +483,9 @@
         a <firstterm>changeset</firstterm>.</para>
 
       <para>Everyone seems to have a slightly different definition
-        of <quote>changeset,</quote> or at least a different
+        of changeset, or at least a different
         expectation of what it means for a version control system to
-        have one.  For our purpose, let's say that a changeset is just
+        have one.  For our purposes, let's say that a changeset is just
         a collection of changes with a unique name.  The changes might
         include textual edits to file contents, modifications to tree
         structure, or tweaks to metadata.  In more common speak, a
@@ -551,7 +551,7 @@
       <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.)  After running
+        is typically the root of your working copy).  After running
         the prior example, your branch working copy now contains new
         local modifications, and these edits are duplications of all
         of the changes that have happened on the trunk since you first
@@ -586,7 +586,7 @@
         changes by running <userinput>svn revert . -R</userinput> (which
         will undo all local modifications) and start a
         long <quote>what's going on?</quote> discussion with your
-        collaborators.  If things look good, however, then you can
+        collaborators.  If things look good, however, you can
         submit these changes into the repository:</para>
 
       <screen>
@@ -644,7 +644,7 @@
           express changes in tree structure and properties by directly
           applying them to your working copy.  Even more important,
           this command records the changes that have been duplicated
-          to your branch, so that Subversion is aware of exactly which
+          to your branch so that Subversion is aware of exactly which
           changes exist in each location (see
           <xref linkend="svn.branchmerge.basicmerging.mergeinfo"/>.)
           This is a critical feature that makes branch management
@@ -703,26 +703,26 @@
         up-to-date 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 by using <command>svn
+        somewhere on your disk, or using <command>svn 
         switch</command> (see
         <xref linkend="svn.branchmerge.switchwc"/>.) However you get a
         trunk working copy, remember that it's a best practice to do
         your merge into a working copy that
         has <emphasis>no</emphasis> local edits and has been recently
-        updated (i.e., is not a mixture of local revisions.)  If your
+        updated (i.e., is not a mixture of local revisions).  If your
         working copy isn't <quote>clean</quote> in these ways, you can
         run into some unnecessary conflict-related headaches
         and <command>svn merge</command> will likely return an
         error.</para>
 
       <para>Once you have a clean working copy of the trunk, you're
-        ready merge your branch back into it:</para>
+        ready to merge your branch back into it:</para>
 
       <screen>
 $ pwd
 /home/user/calc-trunk
 
-$ svn update  # (just to make sure the working copy is at latest everywhere)
+$ svn update  # (make sure the working copy is up to date)
 At revision 390.
 
 $ svn merge --reintegrate http://svn.example.com/repos/calc/branches/my-calc-branch
@@ -743,7 +743,7 @@
 Committed revision 391.
 </screen>
 
-      <para>Congratulations, your branch has now been re-merged back
+      <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
@@ -763,19 +763,18 @@
 
       <para>When merging your branch back to the trunk, however, the
         underlying mathematics is quite different.  Your feature
-        branch is now a mish-mosh of both duplicated trunk changes and
+        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 <option>--reintegrate</option> option, you're asking
         Subversion to carefully replicate <emphasis>only</emphasis>
-        those changes unique to your branch.  (And in fact it does
+        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!)</para>
 
-      <para>Now that your private branch is merged to trunk, you can
-        destroy your working copy of it and then remove it from the
-        repository:</para>
+      <para>Now that your private branch is merged to trunk, you may
+        wish to remove it from the repository:</para>
 
       <screen>
 $ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch \
@@ -795,7 +794,7 @@
         at some point, should you desire (see
         <xref linkend="svn.branchmerge.basicmerging.resurrect"/>).</para>
 
-      <para>In Subversion 1.5.0, once
+      <para>In Subversion 1.5, once
         a <option>--reintegrate</option> 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
@@ -836,7 +835,7 @@
         Specifically, merge data is tracked in
         the <literal>svn:mergeinfo</literal> property attached to
         files and directories.  (If you're not familiar with
-        Subversion properties, now is the time to go skim over
+        Subversion properties, now is the time to skim
         <xref linkend="svn.advanced.props"/>.)</para>
 
       <para>You can examine the property, just like any
@@ -858,7 +857,7 @@
         has received the specific changes
         is <filename>/branches/my-calc-branch</filename>.</para>
 
-      <para>There's also a subcommand <command>svn
+      <para>There's also a subcommand, <command>svn
         mergeinfo</command>, which can be helpful in seeing not only
         which changesets a directory has absorbed, but also which
         changesets it's still eligible to receive.  This gives a sort
@@ -891,7 +890,7 @@
         a <quote>source</quote> URL (where the changes would be coming
         from), and takes an optional <quote>target</quote> URL (where
         the changes would be merged to).  If no target URL is given,
-        then it assumes that the current working directory is the
+        it assumes that the current working directory is the
         target.  In the prior example, because we're querying our
         branch working copy, the command assumes we're interested in
         receiving changes to <filename>/branches/mybranch</filename>
@@ -899,7 +898,7 @@
 
       <para>Another way to get a more precise preview of a merge
         operation is to use the <option>--dry-run</option>
-        option.</para>
+        option:</para>
 
       <screen>
 $ svn merge http://svn.example.com/repos/calc/trunk --dry-run
@@ -912,8 +911,8 @@
       <para>The <option>--dry-run</option> option doesn't actually
         apply any local changes to the working copy.  It shows only
         status codes that <emphasis>would</emphasis> be printed in a
-        real merge.  It's useful for getting a <quote>high
-        level</quote> preview of the potential merge, for those times
+        real merge.  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>
 
@@ -934,7 +933,7 @@
         isn't an inherently risky thing (unless you've made local
         modifications to your working copy—but we've already
         stressed that you shouldn't be merging into such an
-        environment.)  If you don't like the results of the merge,
+        environment).  If you don't like the results of the merge,
         simply run <userinput>svn revert . -R</userinput> to revert the changes from
         your working copy and retry the command with different
         options.  The merge isn't final until you
@@ -946,7 +945,7 @@
           revert</command> over and over, you may run into some
           annoying (but easily bypassed) roadblocks.  For example, if
           the merge operation adds a new file (i.e., schedules it for
-          addition), then <command>svn revert</command> won't actually
+          addition), <command>svn revert</command> won't actually
           remove the file; it simply unschedules the addition.  You're
           left with an unversioned file.  If you then attempt to run
           the merge again, you may get conflicts due to the
@@ -1005,7 +1004,7 @@
         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
-        <emphasis>backwards</emphasis>.</para>
+        <emphasis>backward</emphasis>.</para>
 
       <para>Keep in mind that rolling back a change like this is just
         like any other <command>svn merge</command> operation, so you
@@ -1020,7 +1019,7 @@
         the commit, did it?  The change still exists in revision 303.
         If somebody checks out a version of the
         <filename>calc</filename> project between revisions 303 and
-        349, they'll still see the bad change, right?</para>
+        349, she'll still see the bad change, right?</para>
 
       <para>Yes, that's true.  When we talk about
         <quote>removing</quote> a change, we're really talking about
@@ -1060,7 +1059,7 @@
         do I get my old file or directory back?</quote></para>
 
       <para>The first step is to define
-        exactly <emphasis role="bold">which</emphasis> item you're
+        exactly <emphasis>which</emphasis> item you're
         trying to resurrect.  Here's a useful metaphor: you can think
         of every object in the repository as existing in a sort of
         two-dimensional coordinate system.  The first coordinate is a
@@ -1111,7 +1110,7 @@
         choices.</para>
 
       <para>One option is to use <command>svn merge</command> to apply
-        revision 808 <quote>in reverse.</quote> (We've already
+        revision 808 <quote>in reverse.</quote> (We already
         discussed how to undo changes in
         <xref linkend="svn.branchmerge.basicmerging.undo"/>.)  This
         would have the effect of re-adding <filename>real.c</filename>
@@ -1127,11 +1126,11 @@
         want.  Certainly, you could reverse-merge revision 808 and
         then <command>svn revert</command> the local modifications to
         <filename>integer.c</filename>, but this technique doesn't
-        scale well.  What if there were 90 files changed in revision
+        scale well.  What if 90 files were changed in revision
         808?</para>
 
       <para>A second, more targeted strategy is not to use
-        <command>svn merge</command> at all, but rather the
+        <command>svn merge</command> at all, but rather to use the
         <command>svn copy</command> command.  Simply copy the exact
         revision and path <quote>coordinate pair</quote> from the
         repository to your working copy:</para>
@@ -1168,7 +1167,7 @@
 $ svn add real.c
 A         real.c
 
-$ svn commit -m "Recreated real.c from revision 807."
+$ svn commit -m "Re-created real.c from revision 807."
 Adding         real.c
 Transmitting file data .
 Committed revision 1390.
@@ -1204,9 +1203,9 @@
     <para>Here ends the automated magic.  Sooner or later, once you
       get the hang of branching and merging, you're going to have to
       ask Subversion to merge <emphasis>specific</emphasis> changes
-      from one place to another.  In order to do this, you're going to
+      from one place to another.  To do this, you're going to
       have to start passing more complicated arguments to <command>svn
-      merge</command>.  This next section describes the fully expanded
+      merge</command>.  The next section describes the fully expanded
       syntax of the command and discusses a number of common
       scenarios that require it.</para>
 




More information about the svnbook-dev mailing list