comparison ja/hgext.tex @ 358:1348ce7d2d77

more hgext.tex

357:ef197f25f11e

%\section{Flexible diff support with the \hgext{extdiff} extension}
\section{\hgext{extdiff}$B3HD%$K$h$k=@Fp$J(Bdiff$B%5%]!<%H(B}
\label{sec:hgext:extdiff}

Mercurial's built-in \hgcmd{diff} command outputs plaintext unified
diffs.
\interaction{extdiff.diff}
If you would like to use an external tool to display modifications,
you'll want to use the \hgext{extdiff} extension.  This will let you
use, for example, a graphical diff tool.

The \hgext{extdiff} extension is bundled with Mercurial, so it's easy
to set up.  In the \rcsection{extensions} section of your \hgrc,
simply add a one-line entry to enable the extension.
\begin{codesample2}
  [extensions]
  extdiff =
\end{codesample2}
This introduces a command named \hgxcmd{extdiff}{extdiff}, which by
default uses your system's \command{diff} command to generate a
unified diff in the same form as the built-in \hgcmd{diff} command.
\interaction{extdiff.extdiff}
The result won't be exactly the same as with the built-in \hgcmd{diff}
variations, because the output of \command{diff} varies from one
system to another, even when passed the same options.

As the ``\texttt{making snapshot}'' lines of output above imply, the
\hgxcmd{extdiff}{extdiff} command works by creating two snapshots of
your source tree.  The first snapshot is of the source revision; the
second, of the target revision or working directory.  The
\hgxcmd{extdiff}{extdiff} command generates these snapshots in a
temporary directory, passes the name of each directory to an external
diff viewer, then deletes the temporary directory.  For efficiency, it
only snapshots the directories and files that have changed between the
two revisions.

Snapshot directory names have the same base name as your repository.
If your repository path is \dirname{/quux/bar/foo}, then \dirname{foo}
will be the name of each snapshot directory.  Each snapshot directory
name has its changeset ID appended, if appropriate.  If a snapshot is
of revision \texttt{a631aca1083f}, the directory will be named
\dirname{foo.a631aca1083f}.  A snapshot of the working directory won't
have a changeset ID appended, so it would just be \dirname{foo} in
this example.  To see what this looks like in practice, look again at
the \hgxcmd{extdiff}{extdiff} example above.  Notice that the diff has
the snapshot directory names embedded in its header.

The \hgxcmd{extdiff}{extdiff} command accepts two important options.
The \hgxopt{extdiff}{extdiff}{-p} option lets you choose a program to
view differences with, instead of \command{diff}.  With the
\hgxopt{extdiff}{extdiff}{-o} option, you can change the options that
\hgxcmd{extdiff}{extdiff} passes to the program (by default, these
options are ``\texttt{-Npru}'', which only make sense if you're
running \command{diff}).  In other respects, the
\hgxcmd{extdiff}{extdiff} command acts similarly to the built-in
\hgcmd{diff} command: you use the same option names, syntax, and
arguments to specify the revisions you want, the files you want, and
so on.

As an example, here's how to run the normal system \command{diff}
command, getting it to generate context diffs (using the
\cmdopt{diff}{-c} option) instead of unified diffs, and five lines of
context instead of the default three (passing \texttt{5} as the
argument to the \cmdopt{diff}{-C} option).
\interaction{extdiff.extdiff-ctx}

Launching a visual diff tool is just as easy.  Here's how to launch
the \command{kdiff3} viewer.
\begin{codesample2}
  hg extdiff -p kdiff3 -o ''
\end{codesample2}

If your diff viewing command can't deal with directories, you can
easily work around this with a little scripting.  For an example of
such scripting in action with the \hgext{mq} extension and the
\command{interdiff} command, see
section~\ref{mq-collab:tips:interdiff}.

%\subsection{Defining command aliases}
\subsection{$B%3%^%s%I$N%(%$%j%"%9$r:n$k(B}

It can be cumbersome to remember the options to both the

358:1348ce7d2d77

%\section{Flexible diff support with the \hgext{extdiff} extension}
\section{\hgext{extdiff}$B3HD%$K$h$k=@Fp$J(Bdiff$B%5%]!<%H(B}
\label{sec:hgext:extdiff}

%Mercurial's built-in \hgcmd{diff} command outputs plaintext unified
%diffs.
%\interaction{extdiff.diff}
%If you would like to use an external tool to display modifications,
%you'll want to use the \hgext{extdiff} extension.  This will let you
%use, for example, a graphical diff tool.

Mercurial$B$N%S%k%H%$%s%3%^%s%I(B\hgcmd{diff}$B$O(Bunified$B7A<0$N(Bdiff$B$r%W%l!<%s%F(B
$B%-%9%H$G=PNO$9$k!%(B
\interaction{extdiff.diff}
$BJQ99$r30It%D!<%k$r;H$C$FI=<($7$?$$$J$i$P!$(B\hgext{extdiff}$B3HD%$r;H$&$HNI(B
$B$$!%$3$N3HD%$ONc$($P%0%i%U%#%+%k$J(Bdiff$BI=<($r9T$&!%(B

%The \hgext{extdiff} extension is bundled with Mercurial, so it's easy
%to set up.  In the \rcsection{extensions} section of your \hgrc,
%simply add a one-line entry to enable the extension.

\hgext{extdiff}$B3HD%$O(BMercurial$B$KF1:-$5$l$F$$$k$N$G!$%;%C%H%"%C%W$OMF0W$G(B
$B$"$k!%(B\hgrc $B$NCf$N(B\rcsection{extensions}$B%;%/%7%g%s$K(B1$B9T$N@_Dj$rDI2C$9$k(B
$B$@$1$GNI$$!%(B
\begin{codesample2}
  [extensions]
  extdiff =
\end{codesample2}

%This introduces a command named \hgxcmd{extdiff}{extdiff}, which by
%default uses your system's \command{diff} command to generate a
%unified diff in the same form as the built-in \hgcmd{diff} command.
%\interaction{extdiff.extdiff}
%The result won't be exactly the same as with the built-in \hgcmd{diff}
%variations, because the output of \command{diff} varies from one
%system to another, even when passed the same options.

$B$3$N3HD%$G(B\hgxcmd{extdiff}{extdiff}$B$H$$$&%3%^%s%I$,;H$($k$h$&$K$J$k!%(B
$B$3$N%3%^%s%I$O%7%9%F%`$N(B\command{diff}$B$r;H$C$FAH$_9~$_$N(B\hgcmd{diff}$B%3%^(B
$B%s%I$HF1MM$N(Bunified$B7A<0$N(Bdiff$B$r@8@.$9$k!%(B
\interaction{extdiff.extdiff}
$BF@$i$l$k@.2LJ*$OAH$_9~$_$N(B\hgcmd{diff}$B$HA4$/F1$8$K$O$J$i$J$$$@$m$&!%M}M3(B
$B$O(B\command{diff}$B%3%^%s%I$O%7%9%F%`Kh$K0[$J$j!$F1$8%*%W%7%g%s$rEO$7$F$bF1(B
$B$8=PNO$r$9$k$H$O8B$i$J$$$+$i$@!%(B

%As the ``\texttt{making snapshot}'' lines of output above imply, the
%\hgxcmd{extdiff}{extdiff} command works by creating two snapshots of
%your source tree.  The first snapshot is of the source revision; the
%second, of the target revision or working directory.  The
%\hgxcmd{extdiff}{extdiff} command generates these snapshots in a
%temporary directory, passes the name of each directory to an external
%diff viewer, then deletes the temporary directory.  For efficiency, it
%only snapshots the directories and files that have changed between the
%two revisions.

$B=PNO$N(B``\texttt{making snapshot}''$B9T$,<gD%$9$k$h$&(B
$B$K!$(B\hgxcmd{extdiff}{extdiff}$B%3%^%s%I$O%=!<%9%D%j!<$N(B2$B$D$N%9%J%C%W%7%g%C(B
$B%H$r:n$k$h$&$KF/$/!%(B 1$B$DL\$N%9%J%C%W%7%g%C%H$O%=!<%9%j%S%8%g%s$G!$(B2$B$DL\$O(B
$B%o!<%-%s%0%G%#%l%/%H%j$N%?!<%2%C%H%j%S%8%g%s$G$"$k!%(B
\hgxcmd{extdiff}{extdiff}$B%3%^%s%I$O$3$l$i$N%9%J%C%W%7%g%C%H$r%F%s%]%i%j%G%#(B
$B%l%/%H%j$K:n$j!$30It(Bdiff$B%S%e!<%"$K$=$l$>$l$N%G%#%l%/%H%j$NL>A0$rEO$9!%$=(B
$B$N8e!$%F%s%]%i%j%G%#%l%/%H%j$r>C5n$9$k!%8zN($N$?$a$K(B2$B$D$N%j%S%8%g%s4V$GJQ(B
$B99$N$"$C$?%G%#%l%/%H%j$H%U%!%$%k$N%9%J%C%W%7%g%C%H$@$1$r<h$k!%(B

%Snapshot directory names have the same base name as your repository.
%If your repository path is \dirname{/quux/bar/foo}, then \dirname{foo}
%will be the name of each snapshot directory.  Each snapshot directory
%name has its changeset ID appended, if appropriate.  If a snapshot is
%of revision \texttt{a631aca1083f}, the directory will be named
%\dirname{foo.a631aca1083f}.  A snapshot of the working directory won't
%have a changeset ID appended, so it would just be \dirname{foo} in

%this example.  To see what this looks like in practice, look again at
%the \hgxcmd{extdiff}{extdiff} example above.  Notice that the diff has
%the snapshot directory names embedded in its header.

$B%9%J%C%W%7%g%C%H%G%#%l%/%H%j$NL>A0$O%j%]%8%H%j$HF1$8%Y!<%9%M!<%`$r;}$D!%(B
$B%j%]%8%H%j$N%Q%9$,(B\dirname{/quux/bar/foo}$B$J$i$P!$(B\dirname{foo}$B$,%9%J%C%W(B
$B%7%g%C%H%G%#%l%/%H%j$N%Y!<%9%M!<%`$K$J$j!$$3$3$K%A%'%s%8%;%C%H(BID$B$,IU2C$5(B
$B$l$k!%%9%J%C%W%7%g%C%H$N%j%S%8%g%s$,(B\texttt{a631aca1083f}$B$J$i!$%G%#%l%/%H(B
$B%j$O(B\dirname{foo.a631aca1083f}$B$H$J$k!%%o!<%-%s%0%G%#%l%/%H%j$N%9%J%C%W(B
$B%7%g%C%H$O%A%'%s%8%;%C%H(BID$B$r;}$?$J$$$N$G!$$3$NNc$G$O(B\dirname{foo}$B$H$$$&L>(B
$BA0$K$J$k!%<B:]$NF0:n$r8+$k$K$O!$>e5-$N(B\hgxcmd{extdiff}{extdiff}$B$r;2>H$5$l(B
$B$?$$!%(B diff$B$N%X%C%@$K$O%9%J%C%W%7%g%C%H%G%#%l%/%H%jL>$,Kd$a9~$^$l$F$$$kE@(B
$B$KN10U$5$l$?$$!%(B

%The \hgxcmd{extdiff}{extdiff} command accepts two important options.
%The \hgxopt{extdiff}{extdiff}{-p} option lets you choose a program to
%view differences with, instead of \command{diff}.  With the
%\hgxopt{extdiff}{extdiff}{-o} option, you can change the options that
%\hgxcmd{extdiff}{extdiff} passes to the program (by default, these
%options are ``\texttt{-Npru}'', which only make sense if you're
%running \command{diff}).  In other respects, the
%\hgxcmd{extdiff}{extdiff} command acts similarly to the built-in
%\hgcmd{diff} command: you use the same option names, syntax, and
%arguments to specify the revisions you want, the files you want, and
%so on.

\hgxcmd{extdiff}{extdiff}$B%3%^%s%I$K$O=EMW$J%*%W%7%g%s$,(B2$B$D$"$k!%(B
\hgxopt{extdiff}{extdiff}{-p}$B%*%W%7%g%s$G:9J,$r<h$k%3%^%s%I$H$7$F(B
\command{diff}$B0J30$N%3%^%s%I$r;XDj$G$-$k!%(B \hgxopt{extdiff}{extdiff}{-o}
$B%*%W%7%g%s$G(B\hgxcmd{extdiff}{extdiff}$B$,30It%W%m%0%i%`$KEO$9%*%W%7%g%s$rJQ(B
$B99$9$k$3$H$,$G$-$k!%!J%G%U%)%k%H$G$O(B``\texttt{-Npru}''$B$,EO$5$l$k!%$3$l$O(B
\command{diff}$B$,5/F0$5$l$k;~$N$_0UL#$r;}$D!%!K$=$NB>$NE@$G$O(B
\hgxcmd{extdiff}{extdiff}$B%3%^%s%I$O%S%k%H%$%s$N(B\hgcmd{diff}$B$HF1MM$NF0:n$r(B
$B$9$k!%$9$J$o$A!$F1$8%*%W%7%g%sL>!$J8K!!$%j%S%8%g%s$d%U%!%$%k$r;XDj$9$k=q(B
$B<0$J$I$r;}$D!%(B

%As an example, here's how to run the normal system \command{diff}
%command, getting it to generate context diffs (using the

%\cmdopt{diff}{-c} option) instead of unified diffs, and five lines of
%context instead of the default three (passing \texttt{5} as the
%argument to the \cmdopt{diff}{-C} option).
%\interaction{extdiff.extdiff-ctx}

$B$3$3$G%7%9%F%`$NDL>o%3%^%s%I$N(B\command{diff}$B$r!$(Bunified diff$B7A<0$G$O$J(B
$B$/!$!J(B\cmdopt{diff}{-c}$B%*%W%7%g%s$r;H$C$F!K(Bcontext diff$B7A<0$r=PNO$5$;$kNc(B
$B$r8+$F$_$h$&!%(Bcontext diff$B$K4^$^$l$k%3%s%F%-%9%H$N9T?t$b%G%U%)%k%H$N(B3$B9T$G(B
$B$O$J$/!$!J(B\cmdopt{diff}{-C}$B$X(B\texttt{5}$B%*%W%7%g%s$rEO$7$F!K(B5$B9T=PNO$5$;$k(B
$B$h$&$K$9$k!%(B

%Launching a visual diff tool is just as easy.  Here's how to launch
%the \command{kdiff3} viewer.
$B%S%8%e%"%k(Bdiff$B%D!<%k$N5/F0$O$?$d$9$$!%$3$3$G$O(B\command{kdiff3}$B%S%e!<%"$N(B
$B5/F0J}K!$r<($9!%(B
\begin{codesample2}
  hg extdiff -p kdiff3 -o ''
\end{codesample2}

%If your diff viewing command can't deal with directories, you can
%easily work around this with a little scripting.  For an example of
%such scripting in action with the \hgext{mq} extension and the
%\command{interdiff} command, see
%section~\ref{mq-collab:tips:interdiff}.

$BMxMQ$7$h$&$H$9$k(Bdiff$B%S%e!<%3%^%s%I$,%G%#%l%/%H%j$r07$($J$$>l9g!$$o$:$+$J(B
$B%9%/%j%W%H$r=q$/$3$H$G4JC1$K$3$NLdBj$r2sHr$9$k$3$H$,$G$-$k!%<B:]$K;H$o$l(B
$B$F$$$k%9%/%j%W%HNc$H$7$F$O!$(B\hgext{mq}$B3HD%$H(B\command{interdiff}$B%3%^%s%I$N(B
$B4V$N$b$N$,$"$k!%$3$l$K$D$$$F$O(B\ref{mq-collab:tips:interdiff}$B$r;2>H$5$l$?(B
$B$$!%(B

%\subsection{Defining command aliases}
\subsection{$B%3%^%s%I$N%(%$%j%"%9$r:n$k(B}

It can be cumbersome to remember the options to both the