1.1 --- a/en/hgext.tex	Tue May 15 16:24:20 2007 -0700
     1.2 +++ b/en/hgext.tex	Sat May 26 11:52:18 2007 -0700
     1.3 @@ -204,6 +204,118 @@
     1.4  print different output; neither should they give different results.
     1.5  If either of these situations occurs, please report a bug.
     1.6  
     1.7 +\section{Flexible diff support with the \hgext{extdiff} extension}
     1.8 +\label{sec:hgext:extdiff}
     1.9 +
    1.10 +Mercurial's built-in \hgcmd{diff} command outputs plaintext unified
    1.11 +diffs.
    1.12 +\interaction{extdiff.diff}
    1.13 +If you would like to use an external tool to display modifications,
    1.14 +you'll want to use the \hgext{extdiff} extension.  This will let you
    1.15 +use, for example, a graphical diff tool.
    1.16 +
    1.17 +The \hgext{extdiff} extension is bundled with Mercurial, so it's easy
    1.18 +to set up.  In the \rcsection{extensions} section of your \hgrc,
    1.19 +simply add a one-line entry to enable the extension.
    1.20 +\begin{codesample2}
    1.21 +  [extensions]
    1.22 +  extdiff =
    1.23 +\end{codesample2}
    1.24 +This introduces a command named \hgcmd{extdiff}, which by default uses
    1.25 +your system's \command{diff} command to generate a unified diff in the
    1.26 +same form as the built-in \hgcmd{diff} command.  
    1.27 +\interaction{extdiff.extdiff}
    1.28 +The result won't be exactly the same as with the built-in \hgcmd{diff}
    1.29 +variations, because the output of \command{diff} varies from one
    1.30 +system to another, even when passed the same options.
    1.31 +
    1.32 +As the ``\texttt{making snapshot}'' lines of output above imply, the
    1.33 +\hgcmd{extdiff} command works by creating two snapshots of your source
    1.34 +tree.  The first snapshot is of the source revision; the second, of
    1.35 +the target revision or working directory.  The \hgcmd{extdiff} command
    1.36 +generates these snapshots in a temporary directory, passes the name of
    1.37 +each directory to an external diff viewer, then deletes the temporary
    1.38 +directory.  For efficiency, it only snapshots the directories and
    1.39 +files that have changed between the two revisions.  
    1.40 +
    1.41 +Snapshot directory names have the same base name as your repository.
    1.42 +If your repository path is \dirname{/quux/bar/foo}, then \dirname{foo}
    1.43 +will be the name of each snapshot directory.  Each snapshot directory
    1.44 +name has its changeset ID appended, if appropriate.  If a snapshot is
    1.45 +of revision \texttt{a631aca1083f}, the directory will be named
    1.46 +\dirname{foo.a631aca1083f}.  A snapshot of the working directory won't
    1.47 +have a changeset ID appended, so it would just be \dirname{foo} in
    1.48 +this example.  To see what this looks like in practice, look again at
    1.49 +the \hgcmd{extdiff} example above.  Notice that the diff has the
    1.50 +snapshot directory names embedded in its header.
    1.51 +
    1.52 +The \hgcmd{extdiff} command accepts two important options.  The
    1.53 +\hgopt{extdiff}{-p} option lets you choose a program to view
    1.54 +differences with, instead of \command{diff}.  With the
    1.55 +\hgopt{extdiff}{-o} option, you can change the options that
    1.56 +\hgcmd{extdiff} passes to the program (by default, these options are
    1.57 +``\texttt{-Npru}'', which only make sense if you're running
    1.58 +\command{diff}).  In other respects, the \hgcmd{extdiff} acts
    1.59 +similarly to the built-in \hgcmd{diff} command: you use the same
    1.60 +option names, syntax, and arguments to specify the revisions you want,
    1.61 +the files you want, and so on.
    1.62 +
    1.63 +As an example, here's how to run the normal system \command{diff}
    1.64 +command, getting it to generate context diffs (using the
    1.65 +\cmdopt{diff}{-c} option) instead of unified diffs, and five lines of
    1.66 +context instead of the default three (passing \texttt{5} as the
    1.67 +argument to the \cmdopt{diff}{-C} option).
    1.68 +\interaction{extdiff.extdiff-ctx}
    1.69 +
    1.70 +Launching a visual diff tool is just as easy.  Here's how to launch
    1.71 +the \command{kdiff3} viewer.
    1.72 +\begin{codesample2}
    1.73 +  hg extdiff -p kdiff3 -o ''
    1.74 +\end{codesample2}
    1.75 +
    1.76 +If your diff viewing command can't deal with directories, you can
    1.77 +easily work around this with a little scripting.  For an example of
    1.78 +such scripting in action with the \hgext{mq} extension and the
    1.79 +\command{interdiff} command, see
    1.80 +section~\ref{mq-collab:tips:interdiff}.
    1.81 +
    1.82 +\subsection{Defining command aliases}
    1.83 +
    1.84 +It can be cumbersome to remember the options to both the
    1.85 +\hgcmd{extdiff} command and the diff viewer you want to use, so the
    1.86 +\hgext{extdiff} extension lets you define \emph{new} commands that
    1.87 +will invoke your diff viewer with exactly the right options.
    1.88 +
    1.89 +All you need to do is edit your \hgrc, and add a section named
    1.90 +\rcsection{extdiff}.  Inside this section, you can define multiple
    1.91 +commands.  Here's how to add a \texttt{kdiff3} command.  Once you've
    1.92 +defined this, you can type ``\texttt{hg kdiff3}'' and the
    1.93 +\hgext{extdiff} extension will run \command{kdiff3} for you.
    1.94 +\begin{codesample2}
    1.95 +  [extdiff]
    1.96 +  cmd.kdiff3 =
    1.97 +\end{codesample2}
    1.98 +If you leave the right hand side of the definition empty, as above,
    1.99 +the \hgext{extdiff} extension uses the name of the command you defined
   1.100 +as the name of the external program to run.  But these names don't
   1.101 +have to be the same.  Here, we define a command named ``\texttt{hg
   1.102 +  wibble}'', which runs \command{kdiff3}.
   1.103 +\begin{codesample2}
   1.104 +  [extdiff]
   1.105 +  cmd.wibble = kdiff3
   1.106 +\end{codesample2}
   1.107 +
   1.108 +You can also specify the default options that you want to invoke your
   1.109 +diff viewing program with.  The prefix to use is ``\texttt{opts.}'',
   1.110 +followed by the name of the command to which the options apply.  This
   1.111 +example defines a ``\texttt{hg vimdiff}'' command that runs the
   1.112 +\command{vim} editor's \texttt{DirDiff} extension.
   1.113 +\begin{codesample2}
   1.114 +  [extdiff]  
   1.115 +  cmd.vimdiff = vim
   1.116 +  opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'
   1.117 +\end{codesample2}
   1.118 +
   1.119  %%% Local Variables: 
   1.120  %%% mode: latex
   1.121  %%% TeX-master: "00book"