[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
Comment:
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 @@
place.</para>
<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.
</screen>
- <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
and
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
documents.)</para>
+ <!-- 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>
ignores
+ 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 @@
linkend="svn.advanced.vendorbr"/>).
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
<literal>HEAD</literal>
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>
<screen>
$ 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