hgbook
diff en/hgext.tex @ 226:eef2171243e8
Document the extdiff extension.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Sat May 26 11:52:18 2007 -0700 (2007-05-26) |
parents | 34943a3d50d6 |
children | 28ddbf9f3729 |
line diff
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"