[svnbook commit] r1231 - in trunk/src/en: . book
sussman
svnbook-dev at red-bean.com
Sat Apr 23 13:30:51 CDT 2005
Author: sussman
Date: Sat Apr 23 13:30:50 2005
New Revision: 1231
Modified:
trunk/src/en/TODO
trunk/src/en/book/ch04.xml
Log:
* src/en/book/ch04.xml (The Key Concept Behind Merging): new section.
Also, rearrange subsequent section id's accordingly.
* src/en/TODO: remove TODO.
Modified: trunk/src/en/TODO
==============================================================================
--- trunk/src/en/TODO (original)
+++ trunk/src/en/TODO Sat Apr 23 13:30:50 2005
@@ -71,15 +71,12 @@
ch04:
- - "magic rule" of the merge command: "diff and apply". explain the
- 2 URLs + 1 WC arguments. compare URLs, apply diff to wc.
-
- - need a giant warning-box about how our lack of 'true renames' can
- be really irritating when doing merges. The classic case is when
- branchA moves things around, and branch B just changes file text.
- When you merge branchA into branchB, you deleting the newer file
- versions and adding-with-history the older file versions.
- Definitely a big 'gotcha' to watch out for.
+ - need a giant warning-box about issue #2282. how our lack of
+ 'true renames' can be really irritating when doing merges. The
+ classic case is when branchA moves things around, and branch B
+ just changes file text. When you merge branchA into branchB, you
+ deleting the newer file versions and adding-with-history the
+ older file versions. Definitely a big 'gotcha' to watch out for.
- "common use-cases for merging" shows -r405:HEAD. let's not
encourage HEAD, since that can be a dangerous practice. should
Modified: trunk/src/en/book/ch04.xml
==============================================================================
--- trunk/src/en/book/ch04.xml (original)
+++ trunk/src/en/book/ch04.xml Sat Apr 23 13:30:50 2005
@@ -688,9 +688,86 @@
</sect2>
<sect2 id="svn-ch-4-sect-3.2">
+ <title>The Key Concept Behind Merging</title>
+
+ <para>You've now seen an example of the <command>svn
+ merge</command> command, and you're about to see several
+ more. If you're feeling confused about exactly how merging
+ works, you're not alone. Many users (especially those new
+ to version control) are initially perplexed about the proper
+ syntax of the command, and about how and when the feature
+ should be used. But fear not, this command is actually much
+ simpler than you think! There's a very easy technique for
+ understanding exactly how <command>svn merge</command>
+ behaves.</para>
+
+ <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
+ 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
+ applied to a working copy.</para>
+
+ <para>The command takes three arguments:</para>
+
+ <orderedlist>
+
+ <listitem><para>An initial repository tree (often called the
+ <firstterm>left side</firstterm> of the
+ comparison),</para></listitem>
+
+ <listitem><para>An final repository tree (often called the
+ <firstterm>right side</firstterm> of the
+ comparison),</para></listitem>
+
+ <listitem><para>A working copy to accept the differences as
+ local changes (often called the <firstterm>target</firstterm>
+ of the merge.)</para></listitem>
+
+ </orderedlist>
+
+ <para>Once these three arguments are specified, the two trees
+ are compared, and the resulting 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
+ add</command> or <command>svn delete</command> commands
+ yourself. If you like the results, you can commit them. If
+ you don't like the results, you can simply <command>svn
+ revert</command> all of the changes.</para>
+
+ <para>The syntax of <command>svn merge</command> allows you to
+ specify the three necessary arguments rather flexibly. Here
+ are some examples:</para>
+
+<screen>
+$ svn merge http://svn.example.com/repos/branch1@150 \
+ http://svn.example.com/repos/branch2@212 \
+ my-working-copy
+
+$ svn merge -r 100:200 http://svn.example.com/repos/trunk my-working-copy
+
+$ svn merge -r 100:200 http://svn.example.com/repos/trunk
+</screen>
+
+ <para>The first syntax lays out all three arguments explictly,
+ naming each tree in the form <emphasis>URL at REV</emphasis> and
+ 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
+ defaults to the current directory.</para>
+
+
+ </sect2>
+
+ <sect2 id="svn-ch-4-sect-3.3">
<title>Best Practices for Merging</title>
- <sect3 id="svn-ch-4-sect-3.2.1">
+ <sect3 id="svn-ch-4-sect-3.3.1">
<title>Tracking Merges Manually</title>
<para>Merging changes sounds simple enough, but in practice it
@@ -735,7 +812,7 @@
</sect3>
- <sect3 id="svn-ch-4-sect-3.2.2">
+ <sect3 id="svn-ch-4-sect-3.3.2">
<title>Previewing Merges</title>
<para>Because merging only results in local modifications,
@@ -809,7 +886,7 @@
changeset #9238 into your working copy.</para>
</sidebar>
- <sect3 id="svn-ch-4-sect-3.2.3">
+ <sect3 id="svn-ch-4-sect-3.3.3">
<title>Merge Conflicts</title>
<para>Just like the <command>svn update</command> command,
@@ -898,7 +975,7 @@
</sect3>
- <sect3 id="svn-ch-4-sect-3.2.4">
+ <sect3 id="svn-ch-4-sect-3.3.4">
<title>Noticing or Ignoring Ancestry</title>
<para>When conversing with a Subversion developer, you might
@@ -1500,7 +1577,7 @@
merge the last week's worth of trunk changes to the branch.
Take care when doing this; the merging needs to be
hand-tracked to avoid the problem of repeated merges (as
- described in <xref linkend="svn-ch-4-sect-3.2.1"/>). You'll
+ described in <xref linkend="svn-ch-4-sect-3.3.1"/>). You'll
need to write careful log messages detailing exactly which
revision ranges have been been merged already (as
demonstrated in <xref linkend="svn-ch-4-sect-4.1"/>). It
More information about the svnbook-dev
mailing list