[svnbook commit] r3234 - trunk/src/en/book
sussman
noreply at red-bean.com
Sat Aug 2 20:08:23 CDT 2008
Author: sussman
Date: Sat Aug 2 20:08:22 2008
New Revision: 3234
Log:
Enter second 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 20:08:22 2008
@@ -494,7 +494,7 @@
<para>In Subversion, a global revision number N names a tree in
the repository: it's the way the repository looked after the
Nth commit. It's also the name of an implicit changeset: if
- you compare tree N with tree N-1, you can derive the exact
+ you compare tree N with tree N−1, you can derive the exact
patch that was committed. For this reason, it's easy to think
of revision N as not just a tree, but a changeset as well. If
you use an issue tracker to manage bugs, you can use the
@@ -1216,7 +1216,7 @@
<para>Just as the term <quote>changeset</quote> is often used in
version control systems, so is the term
- of <firstterm>cherrypicking</firstterm>. This word refers to
+ <firstterm>cherrypicking</firstterm>. This word refers to
the act of choosing <emphasis>one</emphasis> specific
changeset from a branch and replicating it to another.
Cherrypicking may also refer to the act of duplicating a
@@ -1229,14 +1229,14 @@
<para>Why would people want to replicate just a single change?
It comes up more often than you'd think. For example, let's
go back in time and imagine that you haven't yet merged your
- private feature-branch back to the trunk. At the
+ private feature branch back to the trunk. At the
water cooler, you get word that Sally made an interesting
change to <filename>integer.c</filename> on the trunk.
Looking over the history of commits to the trunk, you see that
in revision 355 she fixed a critical bug that directly
impacts the feature you're working on. You might not be ready
to merge all the trunk changes to your branch just yet, but
- you certainly need that particular bugfix in order to continue
+ you certainly need that particular bug fix in order to continue
your work.</para>
<screen>
@@ -1271,7 +1271,7 @@
<para>You can now go through the usual testing procedures before
committing this change to your branch. After the commit,
- Subversion marks r355 as having been merged to the branch, so
+ Subversion marks r355 as having been merged to the branch so
that future <quote>magic</quote> merges that synchronize your
branch with the trunk know to skip over r355. (Merging the
same change to the same branch almost always results in a
@@ -1308,8 +1308,8 @@
U button.c
</screen>
- <para>This use-case of replicating
- (or <firstterm>backporting</firstterm>) bugfixes from one
+ <para>This use case of replicating
+ (or <firstterm>backporting</firstterm>) bug fixes from one
branch to another is perhaps the most popular reason for
cherrypicking changes; it comes up all the time, for example,
when a team is maintaining a <quote>release branch</quote> of
@@ -1320,19 +1320,19 @@
<para>Did you notice how, in the last example, the merge
invocation caused two distinct ranges of merges to be
applied? The <command>svn merge</command> command applied
- two independent patches to your working copy in order to
+ two independent patches to your working copy to
skip over changeset 355, which your branch already
contained. There's nothing inherently wrong with this,
except that it has the potential to make conflict resolution
- more tricky. If the first range of changes creates
+ trickier. If the first range of changes creates
conflicts, you <emphasis>must</emphasis> resolve them
- interactively in order for the merge process to continue and
+ interactively for the merge process to continue and
apply the second range of changes. If you postpone a
conflict from the first wave of changes, the whole merge
command will bail out with an error message.
<footnote>
<para>At least, this is true in Subversion 1.5 at the time
- of writing. This behavior may improve in future
+ of this writing. This behavior may improve in future
versions of Subversion.</para>
</footnote>
</para>
@@ -1343,7 +1343,7 @@
do have different syntax in many cases. Be sure to read about
them in <xref linkend="svn.ref"/> for details, or ask
<command>svn help</command>. For example, <command>svn
- merge</command> requires a working-copy path as a target, i.e.,
+ merge</command> requires a working copy path as a target, that is,
a place where it should apply the generated patch. If the
target isn't specified, it assumes you are trying to perform
one of the following common operations:</para>
@@ -1389,8 +1389,8 @@
<para>The main source of confusion is the
<emphasis>name</emphasis> of the command. The term
<quote>merge</quote> somehow denotes that branches are
- combined together, or that there's some sort of mysterious
- blending of data going on. That's not the case. A better
+ combined together, or that some sort of mysterious
+ blending of data is going on. That's not the case. A better
name for the command might have been <command>svn
diff-and-apply</command>, because that's all that happens:
two repository trees are compared, and the differences are
@@ -1398,7 +1398,7 @@
<para>If you're using <command>svn merge</command> to do basic
copying of changes between branches, it will generally do the
- right thing automatically. For example, a command like the
+ right thing automatically. For example, a command such as the
following:</para>
<screen>
@@ -1416,7 +1416,7 @@
<para>If you choose to use the <command>svn merge</command>
command in all its full glory by giving it specific revision
- ranges to duplicate, then the command takes three main
+ ranges to duplicate, the command takes three main
arguments:</para>
<orderedlist>
@@ -1436,7 +1436,7 @@
</orderedlist>
<para>Once these three arguments are specified, the two trees
- are compared, and the resulting differences are applied to the
+ are compared, and the differences are applied to the
target working copy as local modifications. When the command
is done, the results are no different than if you had
hand-edited the files or run various <command>svn
@@ -1464,7 +1464,7 @@
naming the working copy target. The second syntax can be used
as a shorthand for situations when you're comparing two
different revisions of the same URL. The last syntax shows
- how the working-copy argument is optional; if omitted, it
+ how the working copy argument is optional; if omitted, it
defaults to the current directory.</para>
<para>While the first example shows the <quote>full</quote>
@@ -1485,51 +1485,59 @@
where <literal>svn:mergeinfo</literal> data is not created or
changed. Remember to be a bit wary of these scenarios:</para>
- <itemizedlist>
- <listitem>
- <para><emphasis>Merging unrelated sources</emphasis>. If you
+ <variablelist>
+ <varlistentry>
+ <term>Merging unrelated sources</term>
+ <listitem>
+ <para>If you
ask <command>svn merge</command> to compare two URLs that
aren't related to each other, a patch will still be
generated and applied to your working copy, but no merging
metadata will be created. There's no common history
between the two sources, and future <quote>smart</quote>
merges depend on that common history.</para>
- </listitem>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para><emphasis>Merging from foreign
- repositories</emphasis>. While it's possible to run a
+ <varlistentry>
+ <term>Merging from foreign repositories</term>
+ <listitem>
+ <para>While it's possible to run a
command such as <userinput>svn merge -r 100:200
<replaceable>http://svn.foreignproject.com/repos/trunk</replaceable></userinput>, the
- resulting patch will also lack any historical merge
- metadata. At time of writing, Subversion has no way of
+ resultant patch will also lack any historical merge
+ metadata. At time of this writing, Subversion has no way of
representing different repository URLs within
the <literal>svn:mergeinfo</literal> property.</para>
</listitem>
+ </varlistentry>
- <listitem>
- <para><emphasis>Using <option>--ignore-ancestry</option></emphasis>.
- If this option is passed to <command>svn merge</command>, it
- causes the merging logic to mindlessly generate differences
- the same way that <command>svn diff</command> does, ignoring
- any historical relationships. We discuss this later in the
- chapter in
- <xref linkend="svn.branchmerge.advanced.ancestry"/>.</para>
- </listitem>
+ <varlistentry>
+ <term>Using <option>--ignore-ancestry</option></term>
+ <listitem>
+ <para>If this option is passed to <command>svn
+ merge</command>, it causes the merging logic to mindlessly
+ generate differences the same way that <command>svn
+ diff</command> does, ignoring any historical
+ relationships. We discuss this later in the chapter in
+ <xref linkend="svn.branchmerge.advanced.ancestry"/>.</para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para><emphasis>Applying reverse merges to a target's
- natural history</emphasis>. In a prior section
- (<xref linkend="svn.branchmerge.basicmerging.undo"/>) we
- discussed how to use <command>svn merge</command> to apply
- a <quote>reverse patch</quote> as a way of rolling back
- changes. If this technique is used to undo a change to a
- object's personal history (e.g., commit r5 to the trunk,
- then immediately roll back r5 using <userinput>svn merge . -c
- -5</userinput>), this sort of merge doesn't affect the
- recorded mergeinfo.
+ <varlistentry>
+ <term>Apply reverse merges to a target's natural history</term>
+ <listitem>
+ <para>Earlier in this chapter
+ (<xref linkend="svn.branchmerge.basicmerging.undo"/>)
+ we discussed how to use <command>svn merge</command>
+ to apply a <quote>reverse patch</quote> as a way of
+ rolling back changes. If this technique is used to
+ undo a change to an object's personal history (e.g.,
+ commit r5 to the trunk, then immediately roll back r5
+ using <userinput>svn merge . -c -5</userinput>), this
+ sort of merge doesn't affect the recorded mergeinfo.
<footnote><para>Interestingly, after rolling back a
- revision like this, we wouldn't be able to re-apply
+ revision like this, we wouldn't be able to reapply
the revision using <userinput>svn merge . -c 5</userinput>,
since the mergeinfo would already list r5 as being
applied. We would have to use
@@ -1537,9 +1545,10 @@
the merge command ignore the existing
mergeinfo!</para>
</footnote>
- </para>
- </listitem>
- </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</sect2>
@@ -1560,10 +1569,10 @@
always apply <quote>cleanly</quote> to your working copy.
The server produces the delta by comparing two trees: a
virtual snapshot of your working copy, and the revision tree
- you're interested in. Because the left-hand side of the
+ you're interested in. Because the left hand side of the
comparison is exactly equal to what you already have, the
delta is guaranteed to correctly convert your working copy
- into the right-hand tree.</para>
+ into the right hand tree.</para>
<para>But <command>svn merge</command> has no such guarantees
and can be much more chaotic: the advanced user can ask the
@@ -1592,13 +1601,13 @@
(h) help for more options:
</screen>
- <para>In the previous example it might be the case that
+ <para>In the previous example, it might be the case that
<filename>baz.c</filename> exists in both snapshots of the
- branch being compared, and the resulting delta wants to
+ branch being compared, and the resultant delta wants to
change the file's contents, but the file doesn't exist in
the working copy. Whatever the case, the
<quote>skipped</quote> message means that the user is most
- likely comparing the wrong two trees; they're the classic
+ likely comparing the wrong two trees; it's the classic
sign of user error. When this happens, it's easy to
recursively revert all the changes created by the merge
(<userinput>svn revert . --recursive</userinput>), delete any
@@ -1606,7 +1615,7 @@
revert, and rerun <command>svn merge</command> with
different arguments.</para>
- <para>Also notice that the previous example shows a conflict
+ <para>Also notice that the preceeding example shows a conflict
happening on <filename>glorb.h</filename>. We already
stated that the working copy has no local edits: how can a
conflict possibly happen? Again, because the user can use
@@ -1616,7 +1625,7 @@
the file has no local modifications.</para>
<para>Another small difference between <command>svn
- update</command> and <command>svn merge</command> are the
+ update</command> and <command>svn merge</command> is the
names of the full-text files created when a conflict
happens. In <xref linkend="svn.tour.cycle.resolve"/>, we saw
that an update produces files named
@@ -1631,7 +1640,7 @@
describing which side of the double-tree comparison the file
came from. In any case, these differing names will help you
distinguish between conflicts that happened as a result of an
- update versus ones that happened as a result of a
+ update and ones that happened as a result of a
merge.</para>
</sect2>
@@ -1646,13 +1655,13 @@
<filename>/trunk</filename>, but to be more conservative about
backporting changes to a stable branch you use for releasing
to the public. On one extreme, you can manually cherrypick
- single changesets from trunk to the branch—just the
+ single changesets from the trunk to the branch—just the
changes that are stable enough to pass muster. Maybe things
aren't quite that strict, though; perhaps most of the time
you'd like to just let <command>svn merge</command>
automatically merge most changes from trunk to branch. In
this case, you'd like a way to mask a few specific changes
- out, i.e. prevent them from ever being automatically
+ out, that is, prevent them from ever being automatically
merged.</para>
<para>In Subversion 1.5, the only way to block a changeset is to
@@ -1690,7 +1699,7 @@
the change wasn't actually merged, it just wasn't wanted.
There's no way to ask Subversion for a list of <quote>blocked
changelists.</quote> If you want to track them (so that you
- can unblock them someday.) you'll need to record them in a
+ can unblock them someday). you'll need to record them in a
text file somewhere, or perhaps in an invented property. In
Subversion 1.5, unfortunately, this is the only way to manage
blocked revisions; the plans are to make a better interface
@@ -1707,13 +1716,13 @@
The <command>svn log</command> and <command>svn
blame</command> commands are just the tools for this: when
invoked on individual files, they show not only the history of
- changesets that affected the file, but exactly which user
- wrote which line of code, and when they did it.</para>
+ changesets that affected the file, but also exactly which user
+ wrote which line of code, and when she did it.</para>
<para>When changes start getting replicated between branches,
however, things start to get complicated. For example, if you
were to ask <command>svn log</command> about the history of
- your feature branch, it shows exactly every revision that ever
+ your feature branch, it would show exactly every revision that ever
affected the branch:</para>
<screen>
@@ -1743,9 +1752,9 @@
<para>But is this really an accurate picture of all the changes
that happened on the branch? What's being left out here is
the fact that revisions 390, 381, and 357 were actually the
- results of merging changes from trunk. If you look at a one
+ results of merging changes from the trunk. If you look at one
of these logs in detail, the multiple trunk changesets that
- comprised the branch change are nowhere to be seen.</para>
+ comprised the branch change are nowhere to be seen:</para>
<screen>
$ svn log -v -r 390
@@ -1791,14 +1800,14 @@
</screen>
<para>By making the log operation use merge history, we see not
- just the revision we queried (r390), but the two revisions
+ just the revision we queried (r390), but also the two revisions
that came along on the ride with it—a couple of changes
made by Sally to the trunk. This is a much more complete
picture of history!</para>
<para>The <command>svn blame</command> command also takes the
<option>--use-merge-history</option> (<option>-g</option>)
- option. If this option is neglected, then somebody looking at
+ option. If this option is neglected, somebody looking at
a line-by-line annotation of <filename>button.c</filename> may
get the mistaken impression that you were responsible for the
lines that fixed a certain error:</para>
@@ -1838,7 +1847,7 @@
very likely hear reference to the term
<firstterm>ancestry</firstterm>. This word is used to
describe the relationship between two objects in a
- repository: if they're related to each other, then one
+ repository: if they're related to each other, one
object is said to be an ancestor of the other.</para>
<para>For example, suppose you commit revision 100, which
@@ -1899,11 +1908,11 @@
<title>Merges and Moves</title>
<para>A common desire is to refactor source code, especially
- in Java-based software projects. Files and directories are
+ in Java™-based software projects. Files and directories are
shuffled around and renamed, often causing great disruption
to everyone working on the project. Sounds like a perfect
case to use a branch, doesn't it? Just create a branch,
- shuffle things around, then merge the branch back to the
+ shuffle things around, and then merge the branch back to the
trunk, right?</para>
<para>Alas, this scenario doesn't work so well right now and
@@ -1918,7 +1927,7 @@
is running <command>svn update</command> or <command>svn
merge</command>. Instead of telling the client, <quote>Copy
that file you already have to this new location,</quote> it
- instead sends down an entirely new file. This can lead to
+ sends down an entirely new file. This can lead to
problems, especially because the same thing happens with
renamed files. A lesser-known fact about Subversion is that
it lacks <quote>true renames</quote>—the <command>svn
@@ -1970,7 +1979,7 @@
<title>Blocking Merge-Unaware Clients</title>
<para>If you've just upgraded your server to Subversion 1.5 or
- later, then there's a significant risk that pre-1.5 Subversion
+ later, there's a significant risk that pre-1.5 Subversion
clients can mess up your automated merge tracking. Why is
this? When a pre-1.5 Subversion client performs <command>svn
merge</command>, it doesn't modify the value of
@@ -1983,7 +1992,7 @@
resulting from repeated merges.</para>
<para>If you and your team are relying on the merge-tracking
- features of Subversion, then you may want to configure your
+ features of Subversion, you may want to configure your
repository to prevent older clients from committing changes.
The easy way to do this is by inspecting
the <quote>capabilities</quote> parameter in
@@ -2007,8 +2016,8 @@
feature has an extremely complex internal implementation, and
the <literal>svn:mergeinfo</literal> property is the only
window the user has into the machinery. Because the feature
- is relatively new, there are numbers of edge cases and
- possible unexpected behaviors that may pop up.</para>
+ is relatively new, a numbers of edge cases and
+ possible unexpected behaviors may pop up.</para>
<para>For example, sometimes mergeinfo will be generated when
running a simple <command>svn copy</command> or <command>svn
@@ -2020,7 +2029,7 @@
as <quote>explicit</quote> versus <quote>implicit</quote>
mergeinfo, <quote>operative</quote>
versus <quote>inoperative</quote> revisions, specific
- mechanisms of mergeinfo <quote>elision</quote>, and
+ mechanisms of mergeinfo <quote>elision,</quote> and
even <quote>inheritance</quote> from parent to child
directories.</para>
@@ -2038,7 +2047,7 @@
<para>For now, if you want to steer clear of bugs and odd
behaviors in automatic merging, the CollabNet article
- recommends you stick to these simple best practices:</para>
+ recommends that you stick to these simple best practices:</para>
<itemizedlist>
<listitem>
@@ -2048,14 +2057,14 @@
</listitem>
<listitem>
<para>For long-lived release branches (as described in
- <xref linkend="svn.branchmerge.commonpatterns"/>), only
- perform merges on the root of the branch, not on
+ <xref linkend="svn.branchmerge.commonpatterns"/>),
+ perform merges only on the root of the branch, not on
subdirectories.</para>
</listitem>
<listitem>
<para>Never merge into working copies with a mixture of
working revision numbers, or with
- <quote>switched</quote> subdirectories (as described
+ <quote>switched</quote> subdirectories (as described next
in <xref linkend="svn.branchmerge.switchwc"/>). A merge
target should be a working copy which represents
a <emphasis>single</emphasis> location in the repository
@@ -2112,9 +2121,9 @@
</screen>
<para>After <quote>switching</quote> to the branch, your working
- copy is no different than what you would get from doing a fresh
+ copy is no different from what you would get from doing a fresh
checkout of the directory. And it's usually more efficient to
- use this command, because often branches differ only by a small
+ use this command, because often branches differ by only a small
degree. The server sends only the minimal set of changes
necessary to make your working copy reflect the branch
directory.</para>
@@ -2140,18 +2149,18 @@
</listitem>
</orderedlist>
- <para>In other words, if a user knows that the branch-work needs
- only to happen on a specific subdirectory, they use
+ <para>In other words, if a user knows that the branch work needs
+ to happen on only a specific subdirectory, she uses
<command>svn switch</command> to move only that subdirectory to
the branch. (Or sometimes users will switch just a single
- working file to the branch!) That way, they can continue to
- receive normal <quote>trunk</quote> updates to most of their
+ working file to the branch!) That way, the user can continue to
+ receive normal <quote>trunk</quote> updates to most of her
working copy, but the switched portions will remain immune
- (unless someone commits a change to their branch). This feature
+ (unless someone commits a change to her branch). This feature
adds a whole new dimension to the concept of a <quote>mixed
working copy</quote>—not only can working copies contain a
- mixture of working revisions, but a mixture of repository
- locations as well.</para>
+ mixture of working revisions, but they can also contain a
+ mixture of repository locations as well.</para>
<para>If your working copy contains a number of switched subtrees
from different repository locations, it continues to function as
@@ -2163,8 +2172,7 @@
mixture of repository locations, these locations must all be
within the <emphasis>same</emphasis> repository. Subversion
repositories aren't yet able to communicate with one another;
- that's a feature planned for the
- future.
+ that feature is planned for the future.
<footnote>
<para>You <emphasis>can</emphasis>, however, use <command>svn
switch</command> with the <option>--relocate</option> option
@@ -2179,7 +2187,7 @@
<title>Switches and Updates</title>
<para>Have you noticed that the output of <command>svn
- switch</command> and <command>svn update</command> look the
+ switch</command> and <command>svn update</command> looks the
same? The switch command is actually a superset of the update
command.</para>
@@ -2192,12 +2200,12 @@
paths.</para>
<para>That is, if your working copy is a mirror of
- <filename>/calc/trunk</filename>, then <command>svn
+ <filename>/calc/trunk</filename>, <command>svn
update</command> will automatically compare your working copy
of <filename>/calc/trunk</filename> to
<filename>/calc/trunk</filename> in the
<literal>HEAD</literal> revision. If you're switching your
- working copy to a branch, then <command>svn switch</command>
+ working copy to a branch, <command>svn switch</command>
will compare your working copy of
<filename>/calc/trunk</filename> to some
<emphasis>other</emphasis> branch directory in the
@@ -2267,7 +2275,7 @@
<para>Once again, <command>svn copy</command> comes to the
rescue. If you want to create a snapshot of
<filename>/calc/trunk</filename> exactly as it looks in the
- <literal>HEAD</literal> revision, then make a copy of it:</para>
+ <literal>HEAD</literal> revision, make a copy of it:</para>
<screen>
$ svn copy http://svn.example.com/repos/calc/trunk \
@@ -2284,7 +2292,7 @@
<filename>release-1.0</filename> directory is forever a
snapshot of how the <filename>/trunk</filename> directory
looked in the <literal>HEAD</literal> revision at the time you
- made the copy. Of course you might want to be more precise
+ made the copy. Of course, you might want to be more precise
about exactly which revision you copy, in case somebody else
may have committed changes to the project when you weren't
looking. So if you know that revision 901 of
@@ -2292,7 +2300,7 @@
want, you can specify it by passing <option>-r 901</option> to
the <command>svn copy</command> command.</para>
- <para>But wait a moment: isn't this tag-creation procedure the
+ <para>But wait a moment: isn't this tag creation procedure the
same procedure we used to create a branch? Yes, in fact, it
is. In Subversion, there's no difference between a tag and a
branch. Both are just ordinary directories that are created
@@ -2309,7 +2317,7 @@
decide where your tags will live, and make sure all users know
how to treat the directories they copy. (That is, make sure
they know not to commit to them.) The second approach is more
- paranoid: you can use one of the access-control scripts
+ paranoid: you can use one of the access control scripts
provided with Subversion to prevent anyone from doing anything
but creating new copies in the tags area (see
<xref linkend="svn.serverconfig"/>). The paranoid approach,
@@ -2349,7 +2357,7 @@
Luckily, <command>svn copy</command> actually has four
different uses (which you can read about in <xref
linkend="svn.ref"/>), including the ability to copy a
- working-copy tree to the repository:</para>
+ working copy tree to the repository:</para>
<screen>
$ ls
@@ -2365,14 +2373,14 @@
<para>Now there is a new directory in the repository,
<filename>/calc/tags/mytag</filename>, which is an exact
snapshot of your working copy—mixed revisions, URLs,
- local changes and all.</para>
+ local changes, and all.</para>
<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
collaborator to see them. Instead of running <command>svn
diff</command> and sending a patch file (which won't capture
- directory, symlink, or property changes), you can instead
+ directory, symlink, or property changes), you can
use <command>svn copy</command> to <quote>upload</quote> your
working copy to a private area of the repository. Your
collaborator can then either check out a verbatim copy of your
@@ -2382,7 +2390,7 @@
<para>While this is a nice method for uploading a quick snapshot
of your working copy, note that this is <emphasis>not</emphasis>
a good way to initially create a branch. Branch creation should
- be an event onto itself, and this method conflates the creation
+ be an event unto itself, and this method conflates the creation
of a branch with extra changes to files, all within a single revision.
This makes it very difficult (later on) to identify a single
revision number as a branch point.</para>
@@ -2414,7 +2422,7 @@
directory to hold the <quote>main line</quote> of development,
a <filename>branches</filename> directory to contain branch
copies, and a <filename>tags</filename> directory to contain
- tag copies. If a repository holds only one project, then
+ tag copies. If a repository holds only one project,
often people create these top-level directories:</para>
<screen>
@@ -2482,7 +2490,7 @@
Committed revision 375.
</screen>
- <para>And now your branch is gone. Of course it's not really
+ <para>And now your branch is gone. Of course, it's not really
gone: the directory is simply missing from the
<literal>HEAD</literal> revision, no longer distracting
anyone. If you use <command>svn checkout</command>,
@@ -2569,16 +2577,16 @@
<sect2 id="svn.branchmerge.commonpatterns.release">
<title>Release Branches</title>
- <para>Most software has a typical lifecycle: code, test,
+ <para>Most software has a typical life cycle: code, test,
release, repeat. There are two problems with this process.
First, developers need to keep writing new features while
- quality-assurance teams take time to test supposedly stable
+ quality assurance teams take time to test supposedly stable
versions of the software. New work cannot halt while the
software is tested. Second, the team almost always needs to
support older, released versions of software; if a bug is
discovered in the latest code, it most likely exists in
released versions as well, and customers will want to get
- that bugfix without having to wait for a major new
+ that bug fix without having to wait for a major new
release.</para>
<para>Here's where version control can help. The typical
@@ -2591,7 +2599,7 @@
trunk.</emphasis>
Day-to-day changes are committed to
- <filename>/trunk</filename>: new features, bugfixes, and
+ <filename>/trunk</filename>: new features, bug fixes, and
so on.</para>
</listitem>
@@ -2600,7 +2608,7 @@
<quote>release</quote> branch.</emphasis>
When the team thinks the software is ready for release
- (say, a 1.0 release), then <filename>/trunk</filename>
+ (say, a 1.0 release), <filename>/trunk</filename>
might be copied to
<filename>/branches/1.0</filename>.</para>
</listitem>
@@ -2631,10 +2639,10 @@
<para><emphasis>The branch is maintained over time.</emphasis>
While work continues on <filename>/trunk</filename> for
- version 2.0, bugfixes continue to be ported from
+ version 2.0, bug fixes continue to be ported from
<filename>/trunk</filename> to
<filename>/branches/1.0</filename>. When enough
- bugfixes have accumulated, management may decide to do a
+ bug fixes have accumulated, management may decide to do a
1.0.1 release: <filename>/branches/1.0</filename> is
copied to <filename>/tags/1.0.1</filename>, and the tag
is packaged and released.</para>
@@ -2663,7 +2671,7 @@
stability of <filename>/trunk</filename>. Unlike release
branches (which may need to be supported forever), feature
branches are born, used for a while, merged back to the trunk,
- then ultimately deleted. They have a finite span of
+ and then ultimately deleted. They have a finite span of
usefulness.</para>
<para>Again, project policies vary widely concerning exactly
@@ -2684,13 +2692,13 @@
<para>Most projects take a middle-of-the-road approach. They
commonly insist that <filename>/trunk</filename> compile and
pass regression tests at all times. A feature branch is
- only required when a change requires a large number of
+ required only when a change requires a large number of
destabilizing commits. A good rule of thumb is to ask this
question: if the developer worked for days in isolation and
then committed the large change all at once (so that
<filename>/trunk</filename> were never destabilized), would it
be too large a change to review? If the answer to that
- question is <quote>yes,</quote> then the change should be
+ question is <quote>yes,</quote> the change should be
developed on a feature branch. As the developer commits
incremental changes to the branch, they can be easily reviewed
by peers.</para>
@@ -2737,8 +2745,8 @@
final merge step is analogous to running <command>svn
commit</command> from a working copy. After all, what else
<emphasis>is</emphasis> a working copy but a very shallow
- private branch? It's a branch that's only capable of
- storing one change at a time.</para>
+ private branch? It's a branch that's capable of
+ storing only one change at a time.</para>
</sect2>
@@ -2762,7 +2770,7 @@
<para>For example, software developers might be working on an
application that makes use of a third-party library. Subversion
- has just such a relationship with the Apache Portable Runtime
+ has just such a relationship with the Apache Portable Runtime (APR)
library (see <xref linkend="svn.developer.usingapi.apr" />).
The Subversion source code depends on the APR library for all
its portability needs. In earlier stages of Subversion's
@@ -2773,16 +2781,17 @@
API only at well-tested, stable release points.</para>
<para>Now, if your project depends on someone else's information,
- there are several ways that you could attempt to synchronize that
- information with your own. Most painfully, you could issue oral
- or written instructions to all the contributors of your project,
- telling them to make sure that they have the specific versions
+ you could attempt to synchronize that information with your own
+ in several ways. Most painfully, you could issue oral or
+ written instructions to all the contributors of your project,
+ telling them to make sure they have the specific versions
of that third-party information that your project needs. If the
third-party information is maintained in a Subversion
repository, you could also use Subversion's externals
definitions to effectively <quote>pin down</quote> specific
versions of that information to some location in your own
- working copy directory (see <xref linkend="svn.advanced.externals" />).</para>
+ working copy directory (see
+ <xref linkend="svn.advanced.externals" />).</para>
<para>But sometimes you want to maintain custom modifications to
third-party code in your own version control system. Returning
@@ -2798,7 +2807,7 @@
<para>Now you face an interesting situation. Your project could
house its custom modifications to the third-party data in some
disjointed fashion, such as using patch files or full-fledged
- alternate versions of files and directories. But these quickly
+ alternative versions of files and directories. But these quickly
become maintenance headaches, requiring some mechanism by which
to apply your custom changes to the third-party code and
necessitating regeneration of those changes with each successive
@@ -2813,10 +2822,10 @@
<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
+ system, you ensure that the members of your project never need to question
whether they have the right version of the vendor's data. They
simply receive that correct version as part of their regular
- working copy updates. Secondly, because the data lives in your
+ working copy updates. Second, because the data lives in your
own Subversion repository, you can store your custom changes to
it in-place—you have no more need of an automated (or
worse, manual) method for swapping in your customizations.</para>
@@ -2830,7 +2839,7 @@
<filename>/vendor</filename>) to hold the vendor branches.
Then you import the third-party code into a subdirectory of
that top-level directory. You then copy that subdirectory
- into your main development branch (for example,
+ into your main development branch (e.g.,
<filename>/trunk</filename>) at the appropriate location. You
always make your local changes in the main development branch.
With each new release of the code you are tracking, you bring
@@ -2886,7 +2895,7 @@
modified version of libcomplex is now completely integrated
into our calculator program.
<footnote>
- <para>And entirely bug-free, of course!</para>
+ <para>And is entirely bug-free, of course!</para>
</footnote>
</para>
@@ -2963,7 +2972,7 @@
releases of software. This complicates the process of
ensuring that our modifications are still valid for the new
version of code, and things can quickly degrade into a
- situation where we have to manually recreate our
+ situation where we have to manually re-create our
customizations in the new version. Once Subversion knows
about the history of a given source file—including all
its previous locations—the process of merging in the new
@@ -2988,7 +2997,7 @@
Subversion supplies the <command>svn_load_dirs.pl</command>
script to assist with this process. This script automates the
importing steps we mentioned in the general vendor branch
- management procedure to make sure that mistakes are minimized.
+ management procedure to make sure mistakes are minimized.
You will still be responsible for using the merge commands to
merge the new versions of the third-party data into your main
development branch, but <command>svn_load_dirs.pl</command>
@@ -3027,7 +3036,7 @@
current vendor drop will be imported. Finally, the third
argument is the local directory to import. Using our previous
example, a typical run of <command>svn_load_dirs.pl</command>
- might look like:</para>
+ might look like this:</para>
<screen>
$ svn_load_dirs.pl http://svn.example.com/repos/vendor/libcomplex \
@@ -3053,7 +3062,7 @@
<para>When you run <command>svn_load_dirs.pl</command>, it
examines the contents of your existing <quote>current</quote>
vendor drop and compares them with the proposed new vendor
- drop. In the trivial case, there will be no files that are in
+ drop. In the trivial case, no files will be in
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,
@@ -3072,8 +3081,8 @@
<command>svn_load_dirs.pl</command> using the
<option>-p</option> command-line option. Each line of the
configuration file is a whitespace-delimited set of two or
- four values: a Perl-style regular expression to match the
- added path against, a control keyword (either
+ four values: a Perl-style regular expression against which to match the
+ added path, a control keyword (either
<literal>break</literal> or <literal>cont</literal>), and then
optionally a property name and value.</para>
@@ -3091,12 +3100,12 @@
(which means that no more property changes should be applied
to that path). If the control specification is
<literal>cont</literal>—an abbreviation for
- <literal>continue</literal>—then matching will continue
+ <literal>continue</literal>—matching will continue
with the next line of the configuration file.</para>
<para>Any whitespace in the regular expression, property name,
or property value must be surrounded by either single or
- double quote characters. You can escape quote characters that
+ double quotes. You can escape quotes that
are not used for wrapping whitespace by preceding them with a
backslash (<literal>\</literal>) character. The backslash
escapes only quotes when parsing the configuration file, so do
@@ -3112,22 +3121,22 @@
<sect1 id="svn.branchmerge.summary">
<title>Summary</title>
- <para>We've covered a lot of ground in this chapter. We've
+ <para>We covered a lot of ground in this chapter. We
discussed the concepts of tags and branches and demonstrated
how Subversion implements these concepts by copying directories
- with the <command>svn copy</command> command. We've shown how
+ with the <command>svn copy</command> command. We showed how
to use <command>svn merge</command> to copy changes from one
- branch to another or roll back bad changes. We've gone over
+ branch to another or roll back bad changes. We went over
the use of <command>svn switch</command> to create
- mixed-location working copies. And we've talked about how one
+ mixed-location working copies. And we talked about how one
might manage the organization and lifetimes of branches in a
repository.</para>
<para>Remember the Subversion mantra: branches and tags are cheap.
So don't be afraid to use them when needed!</para>
- <para>As a helpful reminder of all the operations we've discussed,
- the following table is a handy reference that you can consult as
+ <para>As a helpful reminder of all the operations we discussed,
+ here is handy reference table you can consult as
you begin to make use of branches.</para>
<table id="svn.branchemerge.summary.tbl-1">
@@ -3141,82 +3150,82 @@
</thead>
<tbody>
<row>
- <entry>Create a branch or tag</entry>
+ <entry>Create a branch or tag.</entry>
<entry>svn copy URL1 URL2</entry>
</row>
<row>
- <entry>Switch a working copy to a branch or tag</entry>
+ <entry>Switch a working copy to a branch or tag.</entry>
<entry>svn switch URL</entry>
</row>
<row>
- <entry>Synchronize a branch with trunk</entry>
+ <entry>Synchronize a branch with trunk.</entry>
<entry>svn merge trunkURL; svn commit</entry>
</row>
<row>
- <entry>See merge history or eligible changesets</entry>
+ <entry>See merge history or eligible changesets.</entry>
<entry>svn mergeinfo target [--from-source=URL]</entry>
</row>
<row>
- <entry>Merge a branch back into trunk</entry>
+ <entry>Merge a branch back into trunk.</entry>
<entry>svn merge --reintegrate branchURL; svn commit</entry>
</row>
<row>
- <entry>Merge one specific change</entry>
+ <entry>Merge one specific change.</entry>
<entry>svn merge -c REV URL; svn commit</entry>
</row>
<row>
- <entry>Merge a range of changes</entry>
+ <entry>Merge a range of changes.</entry>
<entry>svn merge -r REV1:REV2 URL; svn commit</entry>
</row>
<row>
- <entry>Block a change from automatic merging</entry>
+ <entry>Block a change from automatic merging.</entry>
<entry>svn merge -c REV --record-only URL; svn commit</entry>
</row>
<row>
- <entry>Preview a merge</entry>
+ <entry>Preview a merge.</entry>
<entry>svn merge URL --dry-run</entry>
</row>
<row>
- <entry>Abandon merge results</entry>
+ <entry>Abandon merge results.</entry>
<entry>svn revert -R .</entry>
</row>
<row>
- <entry>Resurrect something from history</entry>
+ <entry>Resurrect something from history.</entry>
<entry>svn copy URL at REV local-path</entry>
</row>
<row>
- <entry>Undo a committed change</entry>
+ <entry>Undo a committed change.</entry>
<entry>svn merge -c -REV URL; svn commit</entry>
</row>
<row>
- <entry>Examine merge-sensitive history</entry>
+ <entry>Examine merge-sensitive history.</entry>
<entry>svn log -g; svn blame -g</entry>
</row>
<row>
- <entry>Create a tag from a working copy</entry>
+ <entry>Create a tag from a working copy.</entry>
<entry>svn copy . tagURL</entry>
</row>
<row>
- <entry>Rearrange a branch or tag</entry>
+ <entry>Rearrange a branch or tag.</entry>
<entry>svn mv URL1 URL2</entry>
</row>
<row>
- <entry>Remove a branch or tag</entry>
+ <entry>Remove a branch or tag.</entry>
<entry>svn rm URL</entry>
</row>
</tbody>
More information about the svnbook-dev
mailing list