[svnbook commit] r1522 - in trunk/src/en: . book
cmpilato
svnbook-dev at red-bean.com
Wed Jul 6 02:10:00 CDT 2005
Author: cmpilato
Date: Wed Jul 6 02:09:59 2005
New Revision: 1522
Modified:
trunk/src/en/TODO
trunk/src/en/book/ch07.xml
Log:
Do some work on documenting the use of external differencing tools.
* src/en/TODO
Note partial completion of a TODO item.
* src/en/book/ch07.xml
(Config): Cross-reference the new section.
(Using External Differencing Tools): New section.
Modified: trunk/src/en/TODO
==============================================================================
--- trunk/src/en/TODO (original)
+++ trunk/src/en/TODO Wed Jul 6 02:09:59 2005
@@ -110,12 +110,7 @@
* appA: explain why 'svn commit; svn log' won't show the commit. [BEN]
- * ch07: explain the *exact* arguments that the svn client passes to
- external diff programs (in the section about --diff-cmd and
- friends runtime config stuffs), and show an example of how to
- write a wrapper script that rearranges the args. See Mike's
- scripts in Subversion's contrib/client-side/, diffwrap.bat and
- diff3wrap.bat. [Mike]
+ * ch07: finishing the external differencing tools section. [Mike]
* ch07: best-practice for svn:externals -- always use a specific
revision number in externals definitions so that tracking the
Modified: trunk/src/en/book/ch07.xml
==============================================================================
--- trunk/src/en/book/ch07.xml (original)
+++ trunk/src/en/book/ch07.xml Wed Jul 6 02:09:59 2005
@@ -499,7 +499,9 @@
<command>svn diff</command> command). By default
Subversion uses an internal differencing
library—setting this option will cause it to
- perform this task using an external program.</para>
+ perform this task using an external program. See
+ <xref linkend="svn.advanced.externaldifftools"/> for
+ more details on using such programs.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -511,7 +513,9 @@
from the repository. By default Subversion uses an
internal differencing library—setting this
option will cause it to perform this task using an
- external program.</para>
+ external program. See <xref
+ linkend="svn.advanced.externaldifftools"/> for more
+ details on using such programs.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -3082,7 +3086,7 @@
<!-- =============================================================== -->
<sect2 id="svn.advanced.l10n.understanding">
<title>Understanding locales</title>
-
+
<para>Most modern operating systems have a notion of the
<quote>current locale</quote>—that is, the region or
country whose localization conventions are honored. These
@@ -3242,6 +3246,123 @@
<!-- ================================================================= -->
<!-- ================================================================= -->
<!-- ================================================================= -->
+ <sect1 id="svn.advanced.externaldifftools">
+ <title>Using External Differencing Tools</title>
+
+ <para>The presence of <option>--diff-cmd</option> and
+ <option>--diff3-cmd</option> options, and similarly named
+ runtime configuration parameters (see <xref
+ linkend="svn.advanced.confarea.opts.config"/>), can lead to a
+ false notion of how easy it is to use external differencing (or
+ <quote>diff</quote>) and merge tools with Subversion. While
+ Subversion can use most of popular such tools available, the
+ effort invested in setting this up often turns out to be
+ non-trivial.</para>
+
+ <para>The interface between Subversion and external diff and merge
+ tools harkens back to a time when Subversion's only contextual
+ differencing capabilities were built around invocations of the
+ Gnu diffutils toolchain, specifically the
+ <command>diff</command> and <command>diff3</command> utilities.
+ To get the kind of behavior Subversion needed, it called these
+ utilities with more than a handful of options and parameters,
+ most of which were quite specific to the utilities. Some time
+ later, Subversion grew its own internal differencing library,
+ and as a failover mechanism,
+ <footnote>
+ <para>Subversion developers are good, but even the best make
+ mistakes.</para>
+ </footnote>
+ the <option>--diff-cmd</option> and <option>--diff3-cmd</option>
+ options were added to the Subversion command-line client so
+ users could more easily indicate that they preferred to use the
+ Gnu diff and diff3 utilities instead of the newfangled internal
+ diff library. If those options were used, Subversion would
+ simply ignore the internal diff library, and fall back to
+ running those external programs, lengthy argument lists and all.
+ And that's where things remain today.</para>
+
+ <para>It didn't take long for folks to realize that having such
+ easy configuration mechanisms for specifying that Subversion
+ should use the external Gnu diff and diff3 utilities located at
+ a particular place on the system could be applied toward the use
+ of other diff and merge tools, too. After all, Subversion
+ didn't actually verify that the things it was being told to run
+ were members of the Gnu diffutils toolchain. But the only
+ configurable aspect of using those external tools is their
+ location on the system—not the option set, parameter
+ order, etc. Subversion continues throwing all those Gnu utility
+ options at your external diff tool regardless of whether or not
+ that program can understand those options. And that's where
+ things get unintuitive for most users.</para>
+
+ <para>The key to using external diff and merge tools (other than
+ Gnu diff and diff3, of course) with Subversion is to use wrapper
+ scripts which convert the input from Subversion into something
+ that your differencing tool can understand, and then to convert
+ the output of your tool back into a format which Subversion
+ expects—the format that the Gnu tools would have used.
+ The following sections cover the specifics of those
+ expectations.</para>
+
+ <!-- ### TODO: Give examples of scripts in the sect2's below. The
+ diffwrap.bat and diff3wrap.bat scripts in Subversion's
+ contrib/client-side are good starting points. Might want to
+ point out why the SHIFT calls are there. Might want to point
+ out that the diff3 script mustn't exit before the result is
+ printed (so, can't background the "real" tool). Might want
+ to show Unix-y examples. Also, talk about magic errorcodes
+ (success, conflict, etc.) -->
+
+ <!-- ### TODO: For crying out loud, we might want to just fix
+ Subversion so that the diff-cmd option is a format string
+ which can employ %L, %R, %Y, %O and %M (left, right, yours,
+ older, and mine) as the case may be. -->
+
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.externaldifftools.diff">
+ <title>External diff</title>
+
+ <para>Subversion calls external diff programs with parameters
+ suitable for the Gnu diff utility, and expects only that the
+ external program return with a successful error code. For
+ most alternative diff program, only the sixth and seventh
+ arguments, the paths of the files which represent the left and
+ right sides of the diff, respectively, are of interest. Note
+ that Subversion runs the diff program once per modified file
+ covered by the Subversion operation, so if your program runs
+ in an asynchronous fashion (or <quote>backgrounded</quote>),
+ you might have several instances of it all running
+ simultaneously.</para>
+
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.advanced.externaldifftools.diff3">
+ <title>External diff3</title>
+
+ <para>Subversion calls external merge programs with parameters
+ suitable for the Gnu diff3 utility, expecting that the
+ external program return with a successful error code and that
+ the full file contents which result from the completed merge
+ operation are printed on the standard output stream (so that
+ Subversion can redirect them into the appropriate version
+ controlled file). For most alternative merge programs, only
+ the ninth, tenth, and eleventh arguments, the paths of the
+ files which represent the <quote>mine</quote>,
+ <quote>older</quote>, and <quote>yours</quote> inputs,
+ respectively, are of interest. Note that because Subversion
+ depends on the output of your merge program, you wrapper
+ script must not exit before that output has been delivered to
+ Subversion.</para>
+
+ </sect2>
+ </sect1>
+
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
+ <!-- ================================================================= -->
<sect1 id="svn.advanced.reposurls">
<title>Subversion Repository URLs</title>
More information about the svnbook-dev
mailing list