[svnbook commit] r1526 - in trunk/src/en: . book
cmpilato
svnbook-dev at red-bean.com
Thu Jul 7 03:32:33 CDT 2005
Author: cmpilato
Date: Thu Jul 7 03:32:31 2005
New Revision: 1526
Modified:
trunk/src/en/TODO
trunk/src/en/book/ch07.xml
Log:
Finish talking about external diff and merge tools. Whew!
* src/en/TODO
Note completion of the external diff/diff3 section.
* src/en/book/ch07.xml
(Using External Differencing Tools): Add a note about the
interaction between svn:mime-type and diff/merge tools.
(External diff, External diff3): Add examples and flesh out more of
the descriptive text.
Modified: trunk/src/en/TODO
==============================================================================
--- trunk/src/en/TODO (original)
+++ trunk/src/en/TODO Thu Jul 7 03:32:31 2005
@@ -110,8 +110,6 @@
* appA: explain why 'svn commit; svn log' won't show the commit. [BEN]
- * 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
external is done more judiciously, and so that backdating your own
Modified: trunk/src/en/book/ch07.xml
==============================================================================
--- trunk/src/en/book/ch07.xml (original)
+++ trunk/src/en/book/ch07.xml Thu Jul 7 03:32:31 2005
@@ -3305,20 +3305,22 @@
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. -->
-
+ <note>
+ <para>The decision on when to fire off a contextual diff or
+ merge as part of a larger Subversion operation is made
+ entirely by Subversion, and is affected by, among other
+ things, whether or not the files being operated on are
+ human-readable as determined by their
+ <literal>svn:mime-type</literal> property. This means, for
+ example, that even if you had the niftiest Microsoft
+ Word-aware differencing or merging tool in the Universe, it
+ would never be invoked by Subversion so long as your versioned
+ Word documents had a configured MIME type that denoted that
+ they were not human-readable (such as
+ <literal>application/msword</literal>). For more about MIME
+ type settings, see <xref
+ linkend="svn.advanced.props.special.mime-type"/></para>
+ </note>
<!-- =============================================================== -->
<sect2 id="svn.advanced.externaldifftools.diff">
@@ -3334,8 +3336,66 @@
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>
-
+ simultaneously. Finally, Subversion expects that your program
+ return an errorcode of 0 if your program detected differences,
+ or 1 if it did not—any other errorcode is considered a
+ fatal error.
+ <footnote>
+ <para>The GNU diff manual page puts it this way: <quote>An
+ exit status of 0 means no differences were found, 1 means some
+ differences were found, and 2 means trouble.</quote></para>
+ </footnote>
+ </para>
+
+ <para><xref linkend="svn.advanced.externaldifftools.diff.ex-1"/>
+ and <xref linkend="svn.advanced.externaldifftools.diff.ex-2"/>
+ are templates for external diff tool wrappers in the Bourne
+ shell and Windows batch scripting languages,
+ respectively.</para>
+
+ <example id="svn.advanced.externaldifftools.diff.ex-1">
+ <title>diffwrap.sh</title>
+ <programlisting>
+#!/bin/sh
+
+# Configure your favorite diff program here.
+DIFF="/usr/local/bin/my-diff-tool"
+
+# Subversion provides the paths we need as the sixth and seventh
+# parameters.
+LEFT=${6}
+RIGHT=${7}
+
+# Call the diff command (change the following line to make sense for
+# your merge program).
+$DIFF --left $LEFT --right $RIGHT
+
+# Return an errorcode of 0 if no differences were detected, 1 if some were.
+# Any other errorcode will be treated as fatal.
+</programlisting>
+ </example>
+
+ <example id="svn.advanced.externaldifftools.diff.ex-2">
+ <title>diffwrap.bat</title>
+ <programlisting>
+ at ECHO OFF
+
+REM Configure your favorite diff program here.
+SET DIFF="C:\Program Files\Funky Stuff\My Diff Tool.exe"
+
+REM Subversion provides the paths we need as the sixth and seventh
+REM parameters.
+SET LEFT=%6
+SET RIGHT=%7
+
+REM Call the diff command (change the following line to make sense for
+REM your merge program).
+%DIFF% --left %LEFT% --right %RIGHT%
+
+REM Return an errorcode of 0 if no differences were detected, 1 if some were.
+REM Any other errorcode will be treated as fatal.
+</programlisting>
+ </example>
</sect2>
<!-- =============================================================== -->
@@ -3355,7 +3415,68 @@
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>
+ Subversion. When it finally does exit, it should return an
+ errorcode of 0 if the merge was successful, or 1 if unresolved
+ conflicts remain in the output—any other errorcode is
+ considered a fatal error.</para>
+
+ <para><xref linkend="svn.advanced.externaldifftools.diff3.ex-1"/>
+ and <xref linkend="svn.advanced.externaldifftools.diff3.ex-2"/> are
+ templates for external merge tool wrappers in the Bourne shell
+ and Windows batch scripting languages, respectively.</para>
+
+ <example id="svn.advanced.externaldifftools.diff3.ex-1">
+ <title>diff3wrap.sh</title>
+ <programlisting>
+#!/bin/sh
+
+# Configure your favorite diff3/merge program here.
+DIFF3="/usr/local/bin/my-merge-tool"
+
+# Subversion provides the paths we need as the ninth, tenth, and eleventh
+# parameters.
+MINE=${9}
+OLDER=${10}
+YOURS=${11}
+
+# Call the merge command (change the following line to make sense for
+# your merge program).
+$DIFF3 --older $OLDER --mine $MINE --yours $YOURS
+
+# After performing the merge, this script needs to print the contents
+# of the merged file to stdout. Do that in whatever way you see fit.
+# Return an errorcode of 0 on successful merge, 1 if unresolved conflicts
+# remain in the result. Any other errorcode will be treated as fatal.
+</programlisting>
+ </example>
+
+ <example id="svn.advanced.externaldifftools.diff3.ex-2">
+ <title>diff3wrap.bat</title>
+ <programlisting>
+ at ECHO OFF
+
+REM Configure your favorite diff3/merge program here.
+SET DIFF3="C:\Program Files\Funky Stuff\My Merge Tool.exe"
+
+REM Subversion provides the paths we need as the ninth, tenth, and eleventh
+REM parameters. But we only have access to nine parameters at a time, so we
+REM shift our nine-parameter window twice to let us get to what we need.
+SHIFT
+SHIFT
+SET MINE=%7
+SET OLDER=%8
+SET YOURS=%9
+
+REM Call the merge command (change the following line to make sense for
+REM your merge program).
+%DIFF3% --older %OLDER% --mine %MINE% --yours %YOURS%
+
+REM After performing the merge, this script needs to print the contents
+REM of the merged file to stdout. Do that in whatever way you see fit.
+REM Return an errorcode of 0 on successful merge, 1 if unresolved conflicts
+REM remain in the result. Any other errorcode will be treated as fatal.
+</programlisting>
+ </example>
</sect2>
</sect1>
More information about the svnbook-dev
mailing list