[svnbook commit] r2916 - trunk/src/en/book
fitz
noreply at red-bean.com
Fri Dec 14 01:09:42 CST 2007
Author: fitz
Date: Fri Dec 14 01:09:41 2007
New Revision: 2916
Log:
First pass at documenting interactive conflict resolution. Still
needs a little cleaning up, and I haven't gotten to chapter 9 yet.
Fixes most of Issue#77
* src/en/book/ch02-basic-usage.xml: ..Hmmm...This thing is really
VIBRATING! ..It's getting WARM, too!
Modified:
trunk/src/en/book/ch02-basic-usage.xml
Modified: trunk/src/en/book/ch02-basic-usage.xml
==============================================================================
--- trunk/src/en/book/ch02-basic-usage.xml (original)
+++ trunk/src/en/book/ch02-basic-usage.xml Fri Dec 14 01:09:41 2007
@@ -761,12 +761,15 @@
<varlistentry>
<term><computeroutput>C item</computeroutput></term>
<listitem>
+
<para>The file <filename>item</filename> is in a state
of conflict. That is, changes received from the
server during an update overlap with local changes
- that you have in your working copy. You must resolve
- this conflict before committing your changes to the
+ that you have in your working copy (and weren't
+ resolved during the update). You must resolve this
+ conflict before committing your changes to the
repository.</para>
+
</listitem>
</varlistentry>
@@ -1034,8 +1037,8 @@
$ svn update
U INSTALL
G README
-C bar.c
-Updated to revision 46.
+Conflict discovered in 'bar.c.
+Select: (p)ostpone, (d)iff, (e)dit, (h)elp for more options :
</screen>
<para>The <computeroutput>U</computeroutput> and
@@ -1050,93 +1053,320 @@
changes coming from the repository didn't overlap with the local
changes.</para>
- <para>But the <computeroutput>C</computeroutput> stands for
- <computeroutput>c</computeroutput>onflict. This means that the
- changes from the server overlapped with your own, and now you
- have to manually choose between them.</para>
+ <para>But the next line is part of a feature new in Subversion
+ 1.5 called interactive conflict resolution. This means that
+ the changes from the server overlapped with your own, and you
+ have the opportunity to resolve this conflict. The most
+ commonly used options are displayed, but you can see all of
+ the options by typing <replaceable>h</replaceable>: </para>
- <para>Whenever a conflict occurs, three things typically occur
- to assist you in noticing and resolving that conflict:</para>
+ <screen>
+...
+ (p)ostpone - mark the conflict to be resolved later
+ (d)iff - show all changes made to merged file
+ (e)dit - change merged file in an editor
+ (r)esolved - accept merged version of file
+ (m)ine - accept my version of file
+ (t)heirs - accept their version of file
+ (l)aunch - use third-party tool to resolve conflict
+ (h)elp - show this list
+</screen>
- <itemizedlist>
+ <para>Let's briefly review each of these options before we go
+ into detail on what each option means.</para>
- <listitem>
- <para>Subversion prints a <computeroutput>C</computeroutput>
- during the update, and remembers that the file is in a
- state of conflict.</para>
- </listitem>
+ <variablelist>
+ <varlistentry>
+ <term><computeroutput>(p)ostpone</computeroutput></term>
+ <listitem>
- <listitem>
- <para>If Subversion considers the file to be mergeable,
- it places <firstterm>conflict
- markers</firstterm>—special strings of text which
- delimit the <quote>sides</quote> of the
- conflict—into the file to visibly demonstrate the
- overlapping areas. (Subversion uses the
- <literal>svn:mime-type</literal> property to decide if a
- file is capable of contextual, line-based merging. See
- <xref linkend="svn.advanced.props.special.mime-type"/> to learn more.)</para>
- </listitem>
+ <para>Leaves the file in a conflicted state for you to
+ resolve after your update is complete.</para>
- <listitem>
- <para>For every conflicted file, Subversion places three
- extra unversioned files in your working copy:</para>
+ </listitem>
+ </varlistentry>
- <variablelist>
- <varlistentry>
- <term><filename>filename.mine</filename></term>
- <listitem>
- <para>This is your file as it existed in your working
- copy before you updated your working copy—that
- is, without conflict markers. This file has only
- your latest changes in it. (If Subversion considers
- the file to be unmergeable, then the
- <filename>.mine</filename> file isn't created, since
- it would be identical to the working file.)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><filename>filename.rOLDREV</filename></term>
- <listitem>
- <para>This is the file that was the
- <literal>BASE</literal> revision before you updated
- your working copy. That is, the file that you
- checked out before you made your latest
- edits.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><filename>filename.rNEWREV</filename></term>
- <listitem>
- <para>This is the file that your Subversion client
- just received from the server when you updated your
- working copy. This file corresponds to the
- <literal>HEAD</literal> revision of the
- repository.</para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <para>Here <literal>OLDREV</literal> is the revision number
- of the file in your <filename>.svn</filename> directory
- and <literal>NEWREV</literal> is the revision number of
- the repository <literal>HEAD</literal>.</para>
- </listitem>
- </itemizedlist>
+ <varlistentry>
+ <term><computeroutput>(d)iff</computeroutput></term>
+ <listitem>
- <para>For example, Sally makes changes to the file
- <filename>sandwich.txt</filename> in the repository. Harry has
- just changed the file in his working copy and checked it in.
- Sally updates her working copy before checking in and she gets
- a conflict:</para>
+ <para>Display the differences between the base revision
+ and the conflicted file itself in unified diff format.</para>
- <screen>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term><computeroutput>(e)dit</computeroutput></term>
+ <listitem>
+
+ <para>Open the file in conflict with your favorite editor,
+ as set in the environment variable
+ <literal>EDITOR</literal>.</para>
+
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term><computeroutput>(r)esolved</computeroutput></term>
+ <listitem>
+
+ <para>After editing a file, choosing this command tells
+ <command>svn</command> that you've resolved the
+ conflicts in the file and that it should accept the
+ current contents—basically that you've
+ <quote>resolved</quote> the conflict.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>(m)ine</computeroutput></term>
+ <listitem>
+
+ <para>Discard the newly received changes from the server
+ and use only your local changes for the file under review.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>(t)heirs</computeroutput></term>
+ <listitem>
+
+ <para>Discard your local changes to the file under review
+ and use only the newly received changes from the
+ server.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>(l)aunch</computeroutput></term>
+ <listitem>
+
+ <para>Launch an external program to perform the conflict
+ resolution. This requires a bit of preparation
+ beforehand.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>(h)elp</computeroutput></term>
+ <listitem>
+
+ <para>Shows the list of all possible commands you can use
+ in interactive conflict resolution.</para>
+
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>We'll cover these commands in more detail now, grouping
+ them together by related functionality.</para>
+
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+ <sect3 id="svn.tour.cycle.resolve.diff">
+
+ <title>Viewing Conflict Differences Interactively</title>
+
+ <para>Before deciding how to attack a conflict interactively,
+ odds are that you'd like to see what exactly is in conflict,
+ and the diff command (<command>d</command>) is what you'll
+ use for this:</para>
+
+ <screen>
+...
+Select: (p)ostpone, (d)iff, (e)dit, (h)elp for more options : d
+--- .svn/text-base/sandwich.txt.svn-base Tue Dec 11 21:33:57 2007
++++ .svn/tmp/tempfile.32.tmp Tue Dec 11 21:34:33 2007
+@@ -1 +1,5 @@
+-Just buy a sandwich.
++<<<<<<< .mine
++Go pickup a cheesesteak.
++=======
++Bring me a taco!
++>>>>>>> .r32
+...
+</screen>
+
+ <para>The first line of the diff content shows the previous
+ contents of the working copy (the <literal>BASE</literal>
+ revision), the next content line is your change, and the
+ last content line is the change that was just received from
+ the server (<emphasis>usually</emphasis> the
+ <literal>HEAD</literal> revision). With this information in
+ hand, you're ready to move on to the next action.</para>
+
+ </sect3>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+ <sect3 id="svn.tour.cycle.resolve.resolve">
+
+ <title>Resolving Conflict Differences Interactively</title>
+
+ <para>There are four different ways to resolve conflicts
+ interactively—two of which allow you to selectively
+ merge and edit changes, and two of which allow you to simply
+ pick a version of the file and move along.</para>
+
+ <para>If you wish to choose some combination of your local
+ changes, you can use the <quote>edit</quote> command
+ (<command>e</command>) to manually edit the file with
+ conflict markers in a text editor (determined by the
+ <literal>EDITOR</literal> environment variable). Editing
+ the file by hand in your favorite text editor is a somewhat
+ low-tech way of remedying conflicts (see <xref
+ linkend="svn.tour.cycle.resolve.byhand"/> for a
+ walkthrough), so some people like to use fancy graphical
+ merge tools instead.</para>
+
+ <para>In order to use a merge tool, you need to either set the
+ <literal>SVN_MERGE</literal> environment variable, or define
+ the <literal>merge-tool-cmd</literal> option in your
+ Subversion configuration file (see <xref
+ linkend="svn.advanced.confarea.opts"/> for more details).
+ Subversion will pass four arguments to the merge tool: The
+ <literal>BASE</literal> revision of the file, the revision
+ of the file received from the server as part of the update,
+ the copy of the file containing your local edits, and
+ lastly, the merged copy of the file (which contains conflict
+ markers). If your merge tool is expecting arguments in a
+ different order or format, you'll need to write a wrapper
+ script for Subversion to invoke. After you've edited the
+ file, if you're satisfied with the changes you've made, you
+ can tell Subversion that the edited file is no longer in
+ conflict by using the <quote>resolved</quote> command
+ (<literal>r</literal>).</para>
+
+ <!-- TODO(fitz): I think the above detail on the merge tool -->
+ <!-- should probably be in ch07 -->
+
+ <para>If you decide that you don't need to merge any changes,
+ but just want to accept one version of the file or the
+ other, you can either choose your changes (aka
+ <quote>mine</quote>) by using the <quote>mine</quote>
+ command (<command>m</command>) or choose theirs by using the
+ <quote>theirs</quote> command (<command>t</command>).</para>
+
+ </sect3>
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+ <sect3 id="svn.tour.cycle.resolve.pending">
+
+ <title>Postponing Conflict Resolution</title>
+
+ <para>This may sound like an appropriate section for avoiding
+ marital disagreements, but it's actually still about
+ Subversion, so read on. If you're doing an update and
+ encounter a conflict that you're not prepared to review or
+ resolve, you can type <command>p</command> to postpone
+ resolving a conflict on a file-by-file basis when you run
+ <command>svn update</command>. If you're running an update
+ and don't want to resolve any conflicts, you can pass the
+ <option>--non-interactive</option> option to <command>svn
+ update</command> and any file in conflict will be marked
+ with a <computeroutput>C</computeroutput>
+ automatically.</para>
+
+ <para>The <computeroutput>C</computeroutput> stands for
+ <computeroutput>c</computeroutput>onflict. This means that
+ the changes from the server overlapped with your own, and
+ now you have to manually choose between them after the
+ update has completed. When you postpone a conflict
+ resolution, <command>svn</command> typically does three
+ things to assist you in noticing and resolving that
+ conflict:</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>Subversion prints a <computeroutput>C</computeroutput>
+ during the update, and remembers that the file is in a
+ state of conflict.</para>
+ </listitem>
+
+ <listitem>
+ <para>If Subversion considers the file to be mergeable, it
+ places <firstterm>conflict
+ markers</firstterm>—special strings of text which
+ delimit the <quote>sides</quote> of the
+ conflict—into the file to visibly demonstrate the
+ overlapping areas. (Subversion uses the
+ <literal>svn:mime-type</literal> property to decide if a
+ file is capable of contextual, line-based merging. See
+ <xref linkend="svn.advanced.props.special.mime-type"/>
+ to learn more.)</para>
+ </listitem>
+
+ <listitem>
+ <para>For every conflicted file, Subversion places three
+ extra unversioned files in your working copy:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><filename>filename.mine</filename></term>
+ <listitem>
+ <para>This is your file as it existed in your working
+ copy before you updated your working copy—that
+ is, without conflict markers. This file has only
+ your latest changes in it. (If Subversion considers
+ the file to be unmergeable, then the
+ <filename>.mine</filename> file isn't created, since
+ it would be identical to the working file.)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>filename.rOLDREV</filename></term>
+ <listitem>
+ <para>This is the file that was the
+ <literal>BASE</literal> revision before you updated
+ your working copy. That is, the file that you
+ checked out before you made your latest
+ edits.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>filename.rNEWREV</filename></term>
+ <listitem>
+ <para>This is the file that your Subversion client
+ just received from the server when you updated your
+ working copy. This file corresponds to the
+ <literal>HEAD</literal> revision of the
+ repository.</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>Here <literal>OLDREV</literal> is the revision number
+ of the file in your <filename>.svn</filename> directory
+ and <literal>NEWREV</literal> is the revision number of
+ the repository <literal>HEAD</literal>.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>For example, Sally makes changes to the file
+ <filename>sandwich.txt</filename> in the repository. Harry has
+ just changed the file in his working copy and checked it in.
+ Sally updates her working copy before checking in and she gets
+ a conflict, which she postpones:</para>
+
+ <screen>
$ svn update
+Conflict discovered in 'sandwich.txt'.
+Select: (p)ostpone, (d)iff, (e)dit, (h)elp for more options : p
C sandwich.txt
Updated to revision 2.
$ ls -1
@@ -1146,53 +1376,56 @@
sandwich.txt.r2
</screen>
- <para>At this point, Subversion will <emphasis>not</emphasis>
- allow you to commit the file <filename>sandwich.txt</filename>
- until the three temporary files are removed.</para>
+ <para>At this point, Subversion will <emphasis>not</emphasis>
+ allow Sally to commit the file
+ <filename>sandwich.txt</filename> until the three temporary
+ files are removed.</para>
- <screen>
+ <screen>
$ svn commit -m "Add a few more things"
svn: Commit failed (details follow):
svn: Aborting commit: '/home/sally/svn-work/sandwich.txt' remains in conflict
</screen>
- <para>If you get a conflict, you need to do one of three
- things:</para>
+ <para>If you've postponed a conflict, you need to do one of three
+ things:</para>
- <itemizedlist>
+ <itemizedlist>
- <listitem>
- <para>Merge the conflicted text <quote>by hand</quote> (by
- examining and editing the conflict markers within the
- file).</para>
- </listitem>
+ <listitem>
+ <para>Merge the conflicted text <quote>by hand</quote> (by
+ examining and editing the conflict markers within the
+ file).</para>
+ </listitem>
- <listitem>
- <para>Copy one of the temporary files on top of your
- working file.</para>
- </listitem>
+ <listitem>
+ <para>Copy one of the temporary files on top of your
+ working file.</para>
+ </listitem>
- <listitem>
- <para>Run <command>svn revert <filename></command>
- to throw away all of your local changes.</para>
- </listitem>
+ <listitem>
+ <para>Run <command>svn revert <filename></command>
+ to throw away all of your local changes.</para>
+ </listitem>
- </itemizedlist>
+ </itemizedlist>
- <para>Once you've resolved the conflict, you need to let
- Subversion know by running <command>svn resolved</command>.
- This removes the three temporary files and Subversion no
- longer considers the file to be in a state of
- conflict.<footnote><para>You can always remove the temporary
- files yourself, but would you really want to do that when
- Subversion can do it for you? We didn't think so.</para>
- </footnote></para>
+ <para>Once you've resolved the conflict, you need to let
+ Subversion know by running <command>svn resolved</command>.
+ This removes the three temporary files and Subversion no
+ longer considers the file to be in a state of
+ conflict.<footnote><para>You can always remove the temporary
+ files yourself, but would you really want to do that when
+ Subversion can do it for you? We didn't think so.</para>
+ </footnote></para>
- <screen>
+ <screen>
$ svn resolved sandwich.txt
Resolved conflicted state of 'sandwich.txt'
</screen>
+ </sect3>
+
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<sect3 id="svn.tour.cycle.resolve.byhand">
<title>Merging Conflicts by Hand</title>
More information about the svnbook-dev
mailing list