hgbook
changeset 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 | a631aca1083f |
children | 9be45345065a |
files | en/Makefile en/examples/extdiff en/examples/extdiff.diff.out en/examples/extdiff.extdiff-ctx.out en/examples/extdiff.extdiff.out en/hgext.tex |
line diff
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"