1.1 --- a/en/Makefile	Tue May 15 16:40:08 2007 -0700
     1.2 +++ b/en/Makefile	Sat May 26 11:52:18 2007 -0700
     1.3 @@ -67,6 +67,7 @@
     1.4  	daily.files \
     1.5  	daily.rename \
     1.6  	daily.revert \
     1.7 +	extdiff \
     1.8  	filenames \
     1.9  	hook.msglen \
    1.10  	hook.simple \

     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/en/examples/extdiff	Sat May 26 11:52:18 2007 -0700
     2.3 @@ -0,0 +1,26 @@
     2.4 +#!/bin/bash
     2.5 +
     2.6 +echo '[extensions]' >> $HGRC
     2.7 +echo 'extdiff =' >> $HGRC
     2.8 +
     2.9 +hg init a
    2.10 +cd a
    2.11 +echo 'The first line.' > myfile
    2.12 +hg ci -Ama
    2.13 +echo 'The second line.' >> myfile
    2.14 +
    2.15 +#$ name: diff
    2.16 +
    2.17 +hg diff
    2.18 +
    2.19 +#$ name: extdiff
    2.20 +
    2.21 +hg extdiff
    2.22 +
    2.23 +#$ name: extdiff-ctx
    2.24 +
    2.25 +hg extdiff -o -NprcC5
    2.26 +
    2.27 +#$ name:
    2.28 +
    2.29 +exit 0

     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/en/examples/extdiff.diff.out	Sat May 26 11:52:18 2007 -0700
     3.3 @@ -0,0 +1,7 @@
     3.4 +$ \textbf{hg diff}
     3.5 +diff -r  myfile
     3.6 +
     3.7 +
     3.8 +@@ -1,1 +1,2 @@ The first line.
     3.9 + The first line.
    3.10 ++The second line.

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/en/examples/extdiff.extdiff-ctx.out	Sat May 26 11:52:18 2007 -0700
     4.3 @@ -0,0 +1,11 @@
     4.4 +$ \textbf{hg extdiff -o -NprcC5}
     4.5 +making snapshot of 1 files from rev 
     4.6 +making snapshot of 1 files from working dir
     4.7 +diff -NprcC5 a./myfile a/myfile
     4.8 +*** a./myfile	Sat May 26 18:14:31 2007
     4.9 +
    4.10 +***************
    4.11 +*** 1 ****
    4.12 +
    4.13 +  The first line.
    4.14 ++ The second line.

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/examples/extdiff.extdiff.out	Sat May 26 11:52:18 2007 -0700
     5.3 @@ -0,0 +1,9 @@
     5.4 +$ \textbf{hg extdiff}
     5.5 +making snapshot of 1 files from rev 
     5.6 +making snapshot of 1 files from working dir
     5.7 +diff -Npru a./myfile a/myfile
     5.8 +
     5.9 +
    5.10 +@@ -1 +1,2 @@
    5.11 + The first line.
    5.12 ++The second line.

     6.1 --- a/en/hgext.tex	Tue May 15 16:40:08 2007 -0700
     6.2 +++ b/en/hgext.tex	Sat May 26 11:52:18 2007 -0700
     6.3 @@ -204,6 +204,118 @@
     6.4  print different output; neither should they give different results.
     6.5  If either of these situations occurs, please report a bug.
     6.6  
     6.7 +\section{Flexible diff support with the \hgext{extdiff} extension}
     6.8 +\label{sec:hgext:extdiff}
     6.9 +
    6.10 +Mercurial's built-in \hgcmd{diff} command outputs plaintext unified
    6.11 +diffs.
    6.12 +\interaction{extdiff.diff}
    6.13 +If you would like to use an external tool to display modifications,
    6.14 +you'll want to use the \hgext{extdiff} extension.  This will let you
    6.15 +use, for example, a graphical diff tool.
    6.16 +
    6.17 +The \hgext{extdiff} extension is bundled with Mercurial, so it's easy
    6.18 +to set up.  In the \rcsection{extensions} section of your \hgrc,
    6.19 +simply add a one-line entry to enable the extension.
    6.20 +\begin{codesample2}
    6.21 +  [extensions]
    6.22 +  extdiff =
    6.23 +\end{codesample2}
    6.24 +This introduces a command named \hgcmd{extdiff}, which by default uses
    6.25 +your system's \command{diff} command to generate a unified diff in the
    6.26 +same form as the built-in \hgcmd{diff} command.  
    6.27 +\interaction{extdiff.extdiff}
    6.28 +The result won't be exactly the same as with the built-in \hgcmd{diff}
    6.29 +variations, because the output of \command{diff} varies from one
    6.30 +system to another, even when passed the same options.
    6.31 +
    6.32 +As the ``\texttt{making snapshot}'' lines of output above imply, the
    6.33 +\hgcmd{extdiff} command works by creating two snapshots of your source
    6.34 +tree.  The first snapshot is of the source revision; the second, of
    6.35 +the target revision or working directory.  The \hgcmd{extdiff} command
    6.36 +generates these snapshots in a temporary directory, passes the name of
    6.37 +each directory to an external diff viewer, then deletes the temporary
    6.38 +directory.  For efficiency, it only snapshots the directories and
    6.39 +files that have changed between the two revisions.  
    6.40 +
    6.41 +Snapshot directory names have the same base name as your repository.
    6.42 +If your repository path is \dirname{/quux/bar/foo}, then \dirname{foo}
    6.43 +will be the name of each snapshot directory.  Each snapshot directory
    6.44 +name has its changeset ID appended, if appropriate.  If a snapshot is
    6.45 +of revision \texttt{a631aca1083f}, the directory will be named
    6.46 +\dirname{foo.a631aca1083f}.  A snapshot of the working directory won't
    6.47 +have a changeset ID appended, so it would just be \dirname{foo} in
    6.48 +this example.  To see what this looks like in practice, look again at
    6.49 +the \hgcmd{extdiff} example above.  Notice that the diff has the
    6.50 +snapshot directory names embedded in its header.
    6.51 +
    6.52 +The \hgcmd{extdiff} command accepts two important options.  The
    6.53 +\hgopt{extdiff}{-p} option lets you choose a program to view
    6.54 +differences with, instead of \command{diff}.  With the
    6.55 +\hgopt{extdiff}{-o} option, you can change the options that
    6.56 +\hgcmd{extdiff} passes to the program (by default, these options are
    6.57 +``\texttt{-Npru}'', which only make sense if you're running
    6.58 +\command{diff}).  In other respects, the \hgcmd{extdiff} acts
    6.59 +similarly to the built-in \hgcmd{diff} command: you use the same
    6.60 +option names, syntax, and arguments to specify the revisions you want,
    6.61 +the files you want, and so on.
    6.62 +
    6.63 +As an example, here's how to run the normal system \command{diff}
    6.64 +command, getting it to generate context diffs (using the
    6.65 +\cmdopt{diff}{-c} option) instead of unified diffs, and five lines of
    6.66 +context instead of the default three (passing \texttt{5} as the
    6.67 +argument to the \cmdopt{diff}{-C} option).
    6.68 +\interaction{extdiff.extdiff-ctx}
    6.69 +
    6.70 +Launching a visual diff tool is just as easy.  Here's how to launch
    6.71 +the \command{kdiff3} viewer.
    6.72 +\begin{codesample2}
    6.73 +  hg extdiff -p kdiff3 -o ''
    6.74 +\end{codesample2}
    6.75 +
    6.76 +If your diff viewing command can't deal with directories, you can
    6.77 +easily work around this with a little scripting.  For an example of
    6.78 +such scripting in action with the \hgext{mq} extension and the
    6.79 +\command{interdiff} command, see
    6.80 +section~\ref{mq-collab:tips:interdiff}.
    6.81 +
    6.82 +\subsection{Defining command aliases}
    6.83 +
    6.84 +It can be cumbersome to remember the options to both the
    6.85 +\hgcmd{extdiff} command and the diff viewer you want to use, so the
    6.86 +\hgext{extdiff} extension lets you define \emph{new} commands that
    6.87 +will invoke your diff viewer with exactly the right options.
    6.88 +
    6.89 +All you need to do is edit your \hgrc, and add a section named
    6.90 +\rcsection{extdiff}.  Inside this section, you can define multiple
    6.91 +commands.  Here's how to add a \texttt{kdiff3} command.  Once you've
    6.92 +defined this, you can type ``\texttt{hg kdiff3}'' and the
    6.93 +\hgext{extdiff} extension will run \command{kdiff3} for you.
    6.94 +\begin{codesample2}
    6.95 +  [extdiff]
    6.96 +  cmd.kdiff3 =
    6.97 +\end{codesample2}
    6.98 +If you leave the right hand side of the definition empty, as above,
    6.99 +the \hgext{extdiff} extension uses the name of the command you defined
   6.100 +as the name of the external program to run.  But these names don't
   6.101 +have to be the same.  Here, we define a command named ``\texttt{hg
   6.102 +  wibble}'', which runs \command{kdiff3}.
   6.103 +\begin{codesample2}
   6.104 +  [extdiff]
   6.105 +  cmd.wibble = kdiff3
   6.106 +\end{codesample2}
   6.107 +
   6.108 +You can also specify the default options that you want to invoke your
   6.109 +diff viewing program with.  The prefix to use is ``\texttt{opts.}'',
   6.110 +followed by the name of the command to which the options apply.  This
   6.111 +example defines a ``\texttt{hg vimdiff}'' command that runs the
   6.112 +\command{vim} editor's \texttt{DirDiff} extension.
   6.113 +\begin{codesample2}
   6.114 +  [extdiff]  
   6.115 +  cmd.vimdiff = vim
   6.116 +  opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'
   6.117 +\end{codesample2}
   6.118 +
   6.119  %%% Local Variables: 
   6.120  %%% mode: latex
   6.121  %%% TeX-master: "00book"