Mercurial > hgbook
annotate ja/hgext.tex @ 358:1348ce7d2d77
more hgext.tex
author | Yoshiki Yazawa <yaz@honeyplanet.jp> |
---|---|
date | Tue, 02 Sep 2008 19:03:38 +0900 |
parents | ef197f25f11e |
children | 81116699a510 |
rev | line source |
---|---|
355 | 1 %\chapter{Adding functionality with extensions} |
2 \chapter{$B3HD%$K$h$k5!G=$NDI2C(B} | |
223
4c9b9416cd23
Skeleton for chapter on extensions.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
3 \label{chap:hgext} |
4c9b9416cd23
Skeleton for chapter on extensions.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
4 |
355 | 5 %While the core of Mercurial is quite complete from a functionality |
6 %standpoint, it's deliberately shorn of fancy features. This approach | |
7 %of preserving simplicity keeps the software easy to deal with for both | |
8 %maintainers and users. | |
9 | |
10 $B5!G=$N4QE@$+$i8+$k$H(BMercurial$B$O$+$J$j40Hw$7$F$$$k$,!$GI<j$J5!G=$K$D$$$F$O(B | |
11 $B0U?^E*$KGS=|$7$F$$$k!%(BMercurial$B$N%a%s%F%J$H%f!<%6$NAPJ}$K$H$C$FC1=c$5$rJ](B | |
12 $B$D$?$a$K$3$N%"%W%m!<%A$r<h$C$F$$$k!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
13 |
355 | 14 %However, Mercurial doesn't box you in with an inflexible command set: |
15 %you can add features to it as \emph{extensions} (sometimes known as | |
16 %\emph{plugins}). We've already discussed a few of these extensions in | |
17 %earlier chapters. | |
18 | |
19 $B$7$+$7$J$,$i!$(BMercurial$B$OM;DL$NMx$+$J$$%3%^%s%I%;%C%H$rDs6!$7$F$$$k$N$G$O(B | |
20 $B$J$$!%(B\emph{extensions}$B!J$"$k$$$O(B\emph{plugins}$B$H8F$P$l$k$3$H$b$"$k!K$K$h$C(B | |
21 $B$F5!G=$rDI2C$9$k$3$H$,$G$-$k!%$3$l$i$N$$$/$D$+$K$D$$$F$O!$0JA0$N>O$G8+$F(B | |
22 $B$$$k!%(B | |
23 | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
24 \begin{itemize} |
355 | 25 %\item Section~\ref{sec:tour-merge:fetch} covers the \hgext{fetch} |
26 % extension; this combines pulling new changes and merging them with | |
27 % local changes into a single command, \hgxcmd{fetch}{fetch}. | |
28 \item $B%;%/%7%g%s(B\ref{sec:tour-merge:fetch}$B$O(B\hgext{fetch}$B%(%/%9%F%s%7%g%s(B | |
29 $B$r%+%P!<$7$F$$$k!%$3$l$O?7$7$$JQ99$r(Bpull$B$7!$%m!<%+%k$JJQ99$H%^!<%8(B | |
30 $B$rC10l$N%3%^%s%I(B\hgxcmd{fetch}{fetch}$B$G<B9T$9$k!%(B | |
31 %\item In chapter~\ref{chap:hook}, we covered several extensions that | |
32 % are useful for hook-related functionality: \hgext{acl} adds access | |
33 % control lists; \hgext{bugzilla} adds integration with the Bugzilla | |
34 % bug tracking system; and \hgext{notify} sends notification emails on | |
35 % new changes. | |
36 \item \ref{chap:hook}$B$G$O!$%U%C%/$K4XO"$7$?$$$/$D$+$N3HD%$K$D$$$F07$&!%(B | |
37 \hgext{acl}$B$O%"%/%;%9@)8f%j%9%H$rDI2C$9$k!%(B\hgext{bugzilla}$B$O(BBugzilla$B5!G=(B | |
38 $B$NE}9g5!G=$rDs6!$9$k!%(B\hgext{notify}$B$O!$?7$?$JJQ99$N:]$KDLCNEE;R%a!<%k$r(B | |
39 $BAw$k5!G=$rDs6!$9$k!%(B | |
40 %\item The Mercurial Queues patch management extension is so invaluable | |
41 % that it merits two chapters and an appendix all to itself. | |
42 % Chapter~\ref{chap:mq} covers the basics; | |
43 % chapter~\ref{chap:mq-collab} discusses advanced topics; and | |
44 % appendix~\ref{chap:mqref} goes into detail on each command. | |
45 \item Mercurial Queue$B$H$$$&%Q%C%A%^%M!<%8%a%s%H3HD%$O!$Hs>o$K=EMW$J$N$G(B2 | |
46 $B>O$HIUO?(B1$B>O$rHq$d$7$F@bL@$9$k!%(B | |
47 Chapter~\ref{chap:mq}$B$O4pK\E*$J5!G=$r@bL@$9$k!%(B | |
48 chapter~\ref{chap:mq-collab}$B$G$O9bEY$J5!G=$K$D$$$F@bL@$7!$(B | |
49 appendix~\ref{chap:mqref}$B$G$O3F%3%^%s%I$N>\:Y$r@bL@$9$k!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
50 \end{itemize} |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
51 |
355 | 52 %In this chapter, we'll cover some of the other extensions that are |
53 %available for Mercurial, and briefly touch on some of the machinery | |
54 %you'll need to know about if you want to write an extension of your | |
55 %own. | |
56 $B$3$N>O$G$O(BMercurial$B$GMxMQ2DG=$J$=$NB>$N3HD%$K$D$$$F<h$j07$$!$$^$?<+J,$G(B | |
57 Mercurial$B3HD%$r=q$/;~$KLrN)$DFbIt$N5!9=$K$D$$$F$b@bL@$9$k!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
58 \begin{itemize} |
355 | 59 %\item In section~\ref{sec:hgext:inotify}, we'll discuss the |
60 % possibility of \emph{huge} performance improvements using the | |
61 % \hgext{inotify} extension. | |
62 \item \ref{sec:hgext:inotify}$B@a$G$O(B\hgext{inotify}$B3HD%$rMQ$$$k$3$H$GF@$i(B | |
63 $B$l$k(B\emph{$BBg$-$J(B}$B@-G=8~>e$K$D$$$F=R$Y$k!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
64 \end{itemize} |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
65 |
355 | 66 %\section{Improve performance with the \hgext{inotify} extension} |
67 \section{\hgext{inotify}$B3HD%$K$h$k@-G=8~>e(B} | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
68 \label{sec:hgext:inotify} |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
69 |
355 | 70 %Are you interested in having some of the most common Mercurial |
71 %operations run as much as a hundred times faster? Read on! | |
72 Mercurial$B$N:G$bB?MQ$5$l$k%3%^%s%I$N$$$/$D$+$,?tI4G\B.$/$J$k$3$H$K6=L#$,$"(B | |
73 $B$k$J$i$P$<$RFI$s$GM_$7$$!*(B | |
74 | |
75 %Mercurial has great performance under normal circumstances. For | |
76 %example, when you run the \hgcmd{status} command, Mercurial has to | |
77 %scan almost every directory and file in your repository so that it can | |
78 %display file status. Many other Mercurial commands need to do the | |
79 %same work behind the scenes; for example, the \hgcmd{diff} command | |
80 %uses the status machinery to avoid doing an expensive comparison | |
81 %operation on files that obviously haven't changed. | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
82 |
355 | 83 $BDL>o$N>r7o2<$G(BMercurial$B$O9b$$@-G=$r;}$C$F$$$k$,!$(B \hgcmd{status}$B%3%^%s%I(B |
84 $B$r<B9T$7$?;~!$(BMercurial$B$O$[$\A4$F$N%G%#%l%/%H%j$H%U%!%$%k$r%9%-%c%s$9$k$3(B | |
85 $B$H$K$J$k!%B>$NB?$/$N(BMercurial$B%3%^%s%I$O!$$3$N$h$&$JA`:n$r0U<1$5$;$J$$$h$&(B | |
86 $B$K$J$C$F$$$k!%Nc$($P(B\hgcmd{diff}$B$O%9%F!<%?%95!9=$rMQ$$$F!$L@$i$+$KJQ99$5(B | |
87 $B$l$F$$$J$$%U%!%$%k$NHf3S$rHr$1$F$$$k!%(B | |
88 | |
89 %Because obtaining file status is crucial to good performance, the | |
90 %authors of Mercurial have optimised this code to within an inch of its | |
91 %life. However, there's no avoiding the fact that when you run | |
92 %\hgcmd{status}, Mercurial is going to have to perform at least one | |
93 %expensive system call for each managed file to determine whether it's | |
94 %changed since the last time Mercurial checked. For a sufficiently | |
95 %large repository, this can take a long time. | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
96 |
355 | 97 $BNI$$@-G=$rF@$k$?$a$K$O!$%U%!%$%k%9%F!<%?%9$N<hF@$,=EMW$J4X?4;v$H$J$k$?(B |
98 $B$a!$(BMercurial$B$N:n<T$?$A$O$3$l$r$.$j$.$j$N$H$3$m$^$G:GE,2=$7$F$$$k!%$7$+$7(B | |
99 \hgcmd{status}$B%3%^%s%I$G$O$3$l$rHr$1$k<jN)$F$,$J$$!%(B Mercurial$B$O!$4IM}$7(B | |
100 $B$F$$$k%U%!%$%k$,:G8e$K%A%'%C%/$7$?;~$+$iJQ99$5$l$F$$$k$+D4$Y$k$?$a$K!$>/(B | |
101 $B$J$/$H$b0l$D$N9b2A$J%7%9%F%`%3!<%k$r$9$kI,MW$,$"$k!%$"$kDxEY0J>eBg$-$J%j(B | |
102 $B%]%8%H%j$G$O!$$3$NA`:n$K$OD9$$;~4V$rMW$9$k!%(B | |
103 | |
104 %To put a number on the magnitude of this effect, I created a | |
105 %repository containing 150,000 managed files. I timed \hgcmd{status} | |
106 %as taking ten seconds to run, even when \emph{none} of those files had | |
107 %been modified. | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
108 |
355 | 109 $B$3$N1F6A$K$D$$$FD4$Y$k$?$a$K(B150,000$B$N%U%!%$%k$rMJ$9$k%j%]%8%H%j$r:n@.$7(B |
110 $B$?!%(B\emph{$B$^$C$?$/(B}$BJQ99$,$J$$>l9g$G$b(B\hgcmd{status}$B%3%^%s%I$N<B9T$K$O(B10 | |
111 $BIC$rMW$7$?!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
112 |
355 | 113 %Many modern operating systems contain a file notification facility. |
114 %If a program signs up to an appropriate service, the operating system | |
115 %will notify it every time a file of interest is created, modified, or | |
116 %deleted. On Linux systems, the kernel component that does this is | |
117 %called \texttt{inotify}. | |
118 | |
119 $B6aG/$N%*%Z%l!<%F%#%s%0%7%9%F%`$O!$%U%!%$%kDLCN$N5!9=$rHw$($F$$$k!%%W%m%0(B | |
120 $B%i%`$,E,@Z$J%5!<%S%9$KEPO?$9$k$H!$%*%Z%l!<%F%#%s%0%7%9%F%`$OBP>]$H$J$k%U%!(B | |
121 $B%$%k$N:n@.!$JQ99!$:o=|$r%W%m%0%i%`$KDLCN$9$k!%(B Linux$B%7%9%F%`$G$O$3$l$r9T(B | |
122 $B$&%+!<%M%k%3%s%]!<%M%s%H$O(B\texttt{inotify}$B$H8F$P$l$k!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
123 |
355 | 124 %Mercurial's \hgext{inotify} extension talks to the kernel's |
125 %\texttt{inotify} component to optimise \hgcmd{status} commands. The | |
126 %extension has two components. A daemon sits in the background and | |
127 %receives notifications from the \texttt{inotify} subsystem. It also | |
128 %listens for connections from a regular Mercurial command. The | |
129 %extension modifies Mercurial's behaviour so that instead of scanning | |
130 %the filesystem, it queries the daemon. Since the daemon has perfect | |
131 %information about the state of the repository, it can respond with a | |
132 %result instantaneously, avoiding the need to scan every directory and | |
133 %file in the repository. | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
134 |
355 | 135 Mercurial$B$N(B\hgext{inotify}$B3HD%$O!$(B\hgcmd{status}$B%3%^%s%I$r:GE,2=$9$k$?$a(B |
136 $B$K!$%+!<%M%k$N(B\texttt{inotify}$B%3%s%]!<%M%s%H$X%"%/%;%9$9$k!%$3$N3HD%$O(B2$B$D(B | |
137 $B$N%3%s%]!<%M%s%H$+$i$J$k!%(B \texttt{inotify}$B%5%V%7%9%F%`$+$iDLCN$r<u$1<h$k(B | |
138 $B$?$a$N%G!<%b%s$,%P%C%/%0%i%s%I$GF0:n$9$k!%$3$N%G!<%b%s$O(BMercurial$B$NB>$N%3(B | |
139 $B%^%s%I$+$i$N@\B3$b<u$1IU$1$k!%$3$N3HD%$O(BMercurial$B$N5sF0$rJQ99$7!$%U%!%$%k(B | |
140 $B%7%9%F%`$r%9%-%c%s$9$k$N$G$O$J$/!$%G!<%b%s$X$NLd$$9g$o$;$r9T$&$h$&$K$9(B | |
141 $B$k!%%G!<%b%s$O%j%]%8%H%j$N>uBV$r40A4$KGD0.$7$F$$$k$N$G!$D>$A$KLd$$9g$o$;(B | |
142 $B$KJVEz$9$k$3$H$,$G$-!$%j%]%8%H%j$N%G%#%l%/%H%j$H%U%!%$%k$N%9%-%c%s$rHr$1(B | |
143 $B$k$3$H$,$G$-$k!%(B | |
144 | |
145 %Recall the ten seconds that I measured plain Mercurial as taking to | |
146 %run \hgcmd{status} on a 150,000 file repository. With the | |
147 %\hgext{inotify} extension enabled, the time dropped to 0.1~seconds, a | |
148 %factor of \emph{one hundred} faster. | |
149 | |
150 $B%W%l!<%s$J(BMercurial$B$G$O(B\hgcmd{status}$B%3%^%s%I$,(B150,000$B%U%!%$%k$N%j%]%8%H(B | |
151 $B%j$KBP$7$F(B10$BIC$rMW$7$F$$$?$3$H$r;W$$=P$7$FM_$7$$!#(B | |
152 \hgext{inotify}$B3HD%$r;H$C$?>l9g!"=jMW;~4V$O(B0.1$BIC$K2<$,$j!$(B\emph{100}$BG\B.(B | |
153 $B$/$J$C$F$$$k$3$H$,J,$+$k!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
154 |
355 | 155 %Before we continue, please pay attention to some caveats. |
156 $B$5$i$K?J$`A0$K!$Cm0UE@$r5s$2$k!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
157 \begin{itemize} |
355 | 158 %\item The \hgext{inotify} extension is Linux-specific. Because it |
159 % interfaces directly to the Linux kernel's \texttt{inotify} | |
160 % subsystem, it does not work on other operating systems. | |
161 \item \hgext{inotify}$B3HD%$O(BLinux$BFCM-$N$b$N$G$"$k!%$3$N5!G=3HD%$O(BLinux$B$N(B | |
162 \texttt{inotify}$B%5%V%7%9%F%`$KD>@\%"%/%;%9$9$k$?$a!$B>$N%*%Z%l!<(B | |
163 $B%F%#%s%0%7%9%F%`$G$OF0:n$7$J$$!%(B | |
164 | |
165 %\item It should work on any Linux distribution that was released after | |
166 % early~2005. Older distributions are likely to have a kernel that | |
167 % lacks \texttt{inotify}, or a version of \texttt{glibc} that does not | |
168 % have the necessary interfacing support. | |
169 \item 2005$BG/=i$a0J9_$K%j%j!<%9$5$l$?$I$N$h$&$J(BLinux$B%G%#%9%H%j%S%e!<%7%g(B | |
170 $B%s$G$bF0:n$9$k$O$:$@$,!$8E$$%G%#%9%H%j%S%e!<%7%g%s$G$O(B | |
171 \texttt{inotify}$B$r7g$$$F$$$?$j!$I,MW$J%$%s%?!<%U%'!<%9%5%]!<%H$r(B | |
172 \texttt{glibc}$B$,Ds6!$7$F$$$J$+$C$?$j$9$k2DG=@-$,$"$k!%(B | |
173 | |
174 %\item Not all filesystems are suitable for use with the | |
175 % \hgext{inotify} extension. Network filesystems such as NFS are a | |
176 % non-starter, for example, particularly if you're running Mercurial | |
177 | |
178 % on several systems, all mounting the same network filesystem. The | |
179 % kernel's \texttt{inotify} system has no way of knowing about changes | |
180 % made on another system. Most local filesystems (e.g.~ext3, XFS, | |
181 % ReiserFS) should work fine. | |
182 \item $BA4$F$N%U%!%$%k%7%9%F%`$,(B\hgext{inotify}$B3HD%$GMxMQ2DG=$J$o$1$G$O$J(B | |
183 $B$$!%Nc$((B | |
184 $B$P(BMercurial$B$r$$$/$D$+$N%7%9%F%`$GF0:n$5$;$F$$$k>l9g!$F10l$N%M%C%H%o!<%/%U%!(B | |
185 $B%$%k%7%9%F%`$r3F!9$N%7%9%F%`$G%^%&%s%H$7$F$$$k$3$H$,B?$$$,!$(B NFS$B$J$I$N%M%C(B | |
186 $B%H%o!<%/%U%!%$%k%7%9%F%`$O9MN8$5$l$F$$$J$$!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
187 \end{itemize} |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
188 |
357 | 189 %The \hgext{inotify} extension is not yet shipped with Mercurial as of |
190 %May~2007, so it's a little more involved to set up than other | |
191 %extensions. But the performance improvement is worth it! | |
192 | |
193 2007$BG/(B5$B7n$^$G$O(B\hgext{inotify}$B3HD%$O(BMercurial$B$KF1:-$5$l$F$$$J$+$C$?!%$=$N(B | |
194 $B$?$a!$%;%C%H%"%C%W$OB>$N3HD%$KHf$Y$F$d$dJ#;($@$,!$F@$i$l$k@-G=8~>e$O$K$O(B | |
195 $B$=$l$@$1$N2ACM$,$"$k!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
196 |
357 | 197 %The extension currently comes in two parts: a set of patches to the |
198 %Mercurial source code, and a library of Python bindings to the | |
199 %\texttt{inotify} subsystem. | |
200 | |
201 $B8=:_!$3HD%$O(B2$B$D$N%Q!<%H$KJ,$+$l$F$$$k!%(BMercurial$B%=!<%9%3!<%I$X$N%Q%C%A$H(B | |
202 \texttt{inotify}$B%5%V%7%9%F%`$X$N(BPython$B%P%$%s%G%#%s%0%i%$%V%i%j$G$"$k!%(B | |
203 | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
204 \begin{note} |
357 | 205 % There are \emph{two} Python \texttt{inotify} binding libraries. One |
206 % of them is called \texttt{pyinotify}, and is packaged by some Linux | |
207 % distributions as \texttt{python-inotify}. This is \emph{not} the | |
208 % one you'll need, as it is too buggy and inefficient to be practical. | |
209 | |
210 Python$B$N(B\texttt{inotify}$B%P%$%s%G%#%s%0%i%$%V%i%j$O(B\emph{2$B$D(B}$B$"$k!%(B1$B$D$O(B | |
211 \texttt{pyinotify}$B$G$"$j!$$$$/$D$+$N(BLinux$B%G%#%9%H%j%S%e!<%7%g%s$G$O(B | |
212 \texttt{python-inotify}$B$H$7$F%Q%C%1!<%82=$5$l$F$$$k!%$3$l$O%P%0$,Hs>o$KB?(B | |
213 $B$/!$<BMQ$9$k$K$OHs8zN(E*$G$"$j!$;H$&$Y$-$G(B\emph{$B$J$$(B}$B!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
214 \end{note} |
357 | 215 %To get going, it's best to already have a functioning copy of |
216 %Mercurial installed. | |
217 $B@h$X?J$`$KEv$C$F!$@5$7$/5!G=$9$k(BMercurial$B$,%$%s%9%H!<%k$5$l$F$$$k$3$H$,(B | |
218 $BK>$^$7$$!%(B | |
219 | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
220 \begin{note} |
357 | 221 % If you follow the instructions below, you'll be \emph{replacing} and |
222 % overwriting any existing installation of Mercurial that you might | |
223 % already have, using the latest ``bleeding edge'' Mercurial code. | |
224 % Don't say you weren't warned! | |
225 $B0J2<$N;X<($K=>$C$F%$%s%9%H!<%k$7$?(BMercurial$B$r!$:G?7$N(BMercurial$B%3!<%I$G(B | |
226 \emph{$BCV$-49$($k(B}$B$3$H$,$G$-$k!%!J7Y9p$5$l$J$+$C$?$H$O8@$o$J$$$3$H!K(B | |
227 | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
228 \end{note} |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
229 \begin{enumerate} |
357 | 230 %\item Clone the Python \texttt{inotify} binding repository. Build and |
231 % install it. | |
232 \item Python \texttt{inotify}$B%P%$%s%G%#%s%0$N%j%]%8%H%j$r%/%m!<%s$7!$%S(B | |
233 $B%k%I$H%$%s%9%H!<%k$r9T$&!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
234 \begin{codesample4} |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
235 hg clone http://hg.kublai.com/python/inotify |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
236 cd inotify |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
237 python setup.py build --force |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
238 sudo python setup.py install --skip-build |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
239 \end{codesample4} |
357 | 240 %\item Clone the \dirname{crew} Mercurial repository. Clone the |
241 % \hgext{inotify} patch repository so that Mercurial Queues will be | |
242 % able to apply patches to your cope of the \dirname{crew} repository. | |
243 \item Merecurial$B$N(B\dirname{crew}$B%j%]%8%H%j$r%/%m!<%s$9(B | |
244 $B$k!%(B\hgext{inotify}$B%Q%C%A%j%]%8%H%j$r%/%m!<%s$7!$(BMercurial Queues | |
245 $B$,(B\dirname{crew}$B%j%]%8%H%j$K%Q%C%A$rEv$F$i$l$k$h$&$K$9$k!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
246 \begin{codesample4} |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
247 hg clone http://hg.intevation.org/mercurial/crew |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
248 hg clone crew inotify |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
249 hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
250 \end{codesample4} |
357 | 251 %\item Make sure that you have the Mercurial Queues extension, |
252 % \hgext{mq}, enabled. If you've never used MQ, read | |
253 % section~\ref{sec:mq:start} to get started quickly. | |
254 | |
255 \item Mercurial Queues$B3HD%!J(B\hgext{mq}$B!K$,M-8z$K$J$C$F$$$k$3$H$r3NG'$9(B | |
256 $B$k!%(BMQ$B$r;H$C$?$3$H$,$J$1$l$P!$(B\ref{sec:mq:start}$B$r0lFI$9$k$3$H$r$*(B | |
257 $B$9$9$a$9$k!%(B | |
258 | |
259 %\item Go into the \dirname{inotify} repo, and apply all of the | |
260 % \hgext{inotify} patches using the \hgxopt{mq}{qpush}{-a} option to | |
261 % the \hgxcmd{mq}{qpush} command. | |
262 \item \dirname{inotify}$B%j%]%8%H%j$X9T$-!$(B\hgxcmd{mq}{qpush}$B%3%^%s%I$K(B | |
263 \hgxopt{mq}{qpush}{-a}$B%*%W%7%g%s$r;H$C$F(B\hgext{inotify}$B$N%Q%C%A$r$9(B | |
264 $B$Y$FE,MQ$9$k!%(B | |
265 | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
266 \begin{codesample4} |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
267 cd inotify |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
268 hg qpush -a |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
269 \end{codesample4} |
357 | 270 % If you get an error message from \hgxcmd{mq}{qpush}, you should not |
271 % continue. Instead, ask for help. | |
272 | |
273 \hgxcmd{mq}{qpush}$B$G%(%i!<$,5/$-$?>l9g!$@h$X?J$^$:$K=u8@$r5a$a$FM_$7$$!%(B | |
274 | |
275 %\item Build and install the patched version of Mercurial. | |
276 \item $B%Q%C%A$rEv$F$?(BMercurial$B$r%S%k%I$7$F%$%s%9%H!<%k$9$k!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
277 \begin{codesample4} |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
278 python setup.py build --force |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
279 sudo python setup.py install --skip-build |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
280 \end{codesample4} |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
281 \end{enumerate} |
357 | 282 %Once you've build a suitably patched version of Mercurial, all you |
283 %need to do to enable the \hgext{inotify} extension is add an entry to | |
284 %your \hgrc. | |
285 | |
286 $BE,@Z$J%Q%C%A$NEv$C$?(BMercurial$B$r%S%k%I$9$l$P!$8e$O(B\hgext{inotify}$B3HD%$rMx(B | |
287 $BMQ$9$k$h$&$K(B\hgrc $B$r@_Dj$9$k$@$1$G$"$k!%(B | |
288 | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
289 \begin{codesample2} |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
290 [extensions] |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
291 inotify = |
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
292 \end{codesample2} |
357 | 293 %When the \hgext{inotify} extension is enabled, Mercurial will |
294 %automatically and transparently start the status daemon the first time | |
295 %you run a command that needs status in a repository. It runs one | |
296 %status daemon per repository. | |
297 | |
298 \hgext{inotify}$B$,M-8z$K$J$C$F$$$k$H!$(BMercurial$B$O%j%]%8%H%jFb$G%3%^%s%I$,(B | |
299 $B:G=i$K<B9T$5$l$?;~$K<+F0E*$+$DF)2aE*$K%9%F!<%?%9%G!<%b%s$r5/F0$9$k!%%j%](B | |
300 $B%8%H%j(B1$B$D$4$H$K(B1$B$D$N%9%F!<%?%9%G!<%b%s$,5/F0$5$l$k!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
301 |
357 | 302 %The status daemon is started silently, and runs in the background. If |
303 %you look at a list of running processes after you've enabled the | |
304 %\hgext{inotify} extension and run a few commands in different | |
305 %repositories, you'll thus see a few \texttt{hg} processes sitting | |
306 %around, waiting for updates from the kernel and queries from | |
307 %Mercurial. | |
308 | |
309 $B%9%F!<%?%9%G!<%b%s$O2?$b=PNO$r9T$o$:!$%P%C%/%0%i%&%s%I$GF0:n$9(B | |
310 $B$k!%(B\hgext{inotify}$B3HD%$rM-8z$K$7$?8e$GJL$N%j%]%8%H%jFb$G$$$/$D$+%3%^%s%I(B | |
311 $B$r<B9T$7!$<B9TCf$N%W%m%;%9$N%j%9%H$r8+$k$H!$$$$/$D$+$N(B\texttt{hg}$B%W%m%;%9(B | |
312 $B$,%+!<%M%k$+$i$N%"%C%W%G!<%H$H(BMercurial$B$+$i$NLd$$9g$o$;$rBT$C$F$$$k$N$,(B | |
313 $B8+$i$l$k$@$m$&!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
314 |
357 | 315 %The first time you run a Mercurial command in a repository when you |
316 %have the \hgext{inotify} extension enabled, it will run with about the | |
317 %same performance as a normal Mercurial command. This is because the | |
318 %status daemon needs to perform a normal status scan so that it has a | |
319 %baseline against which to apply later updates from the kernel. | |
320 %However, \emph{every} subsequent command that does any kind of status | |
321 %check should be noticeably faster on repositories of even fairly | |
322 %modest size. Better yet, the bigger your repository is, the greater a | |
323 %performance advantage you'll see. The \hgext{inotify} daemon makes | |
324 %status operations almost instantaneous on repositories of all sizes! | |
325 | |
326 \hgext{inotify}$B3HD%$rM-8z$K$7!$%j%]%8%H%jFb$G(BMercurial$B%3%^%s%I$r:G=i$K<B(B | |
327 $B9T$7$?;~$ODL>o$N(BMercurial$B%3%^%s%I$HF1MM$N@-G=$GF0$/!%%9%F!<%?%9%G!<%b%s$O(B | |
328 $BDL>o$N%9%F!<%?%9%9%-%c%s$r9T$$!$%+!<%M%k$+$i99?7$NDLCN$r<u$1$k$?$a$N%Y!<(B | |
329 $B%9%i%$%s$r<hF@$7$F$*$+$J$1$l$P$J$i$J$$$+$i$G$"$k!%0lJ}$G!$8eB3$N%9%F!<%?(B | |
330 $B%9%A%'%C%/$r9T$&(B\emph{$B$9$Y$F$N(B}$B%3%^%s%I$O!$$=$3$=$3$NBg$-$5$N%j%]%8%H%j$K(B | |
331 $BBP$7$F$bL\$K8+$($F9bB.2=$5$l$k!%$5$i$K%j%]%8%H%j$,Bg$-$/$J$k$KO"$l$F@-G=(B | |
332 $B$N8~>e$OBg$-$/$J$k!%(B\hgext{inotify}$B%G!<%b%s$O!$%j%]%8%H%j$N%5%$%:$K4X$o$i(B | |
333 $B$:!$%9%F!<%?%9<hF@$r$[$\=V;~$K9T$&$3$H$,$G$-$k!%(B | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
334 |
357 | 335 %If you like, you can manually start a status daemon using the |
336 %\hgxcmd{inotify}{inserve} command. This gives you slightly finer | |
337 %control over how the daemon ought to run. This command will of course | |
338 %only be available when the \hgext{inotify} extension is enabled. | |
339 | |
340 \hgxcmd{inotify}{inserve}$B%3%^%s%I$r;H$C$F%9%F!<%?%9%G!<%b%s$r<jF0$G<B9T$9(B | |
341 $B$k$3$H$b2DG=$G$"$k!%$3$l$K$h$j!$%G!<%b%s$,$I$N$h$&$KF0:n$9$k$N$+$r$d$d:Y(B | |
342 $B$+$/%3%s%H%m!<%k$9$k$3$H$,$G$-$k!%EvA3$J$,$i!$$3$N%3%^%s%I$O(B | |
343 \hgext{inotify}$B$,M-8z$N>l9g$N$_MxMQ2DG=$G$"$k!%(B | |
344 | |
224
34943a3d50d6
Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents:
223
diff
changeset
|
345 |
357 | 346 %When you're using the \hgext{inotify} extension, you should notice |
347 %\emph{no difference at all} in Mercurial's behaviour, with the sole | |
348 %exception of status-related commands running a whole lot faster than | |
349 %they used to. You should specifically expect that commands will not | |
350 %print different output; neither should they give different results. | |
351 %If either of these situations occurs, please report a bug. | |
352 | |
353 \hgext{inotify}$B3HD%$r;H$C$F$$$k;~$O(BMercurial$B$N(B\emph{$BA4$/JQ2=$J$7(B}$B$H$$$&F0(B | |
354 $B:n$K5$IU$/$@$m$&!%%9%F!<%?%9$K4X78$9$k%3%^%s%I$O0JA0$h$j$:$C$H9bB.$K$J$C(B | |
355 $B$F$$$k$H$$$&0l$D$NNc30$r=|$$$F%3%^%s%I$OFCJL$N=PNO$b7k2L$b=PNO$7$J$$$3$H(B | |
356 $B$KN10U$5$l$?$$!%2?$+FCJL$J$3$H$,5/$-$?$i%P%0$H$7$FJs9p$7$FM_$7$$!%(B | |
223
4c9b9416cd23
Skeleton for chapter on extensions.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
357 |
355 | 358 %\section{Flexible diff support with the \hgext{extdiff} extension} |
359 \section{\hgext{extdiff}$B3HD%$K$h$k=@Fp$J(Bdiff$B%5%]!<%H(B} | |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
360 \label{sec:hgext:extdiff} |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
361 |
358 | 362 %Mercurial's built-in \hgcmd{diff} command outputs plaintext unified |
363 %diffs. | |
364 %\interaction{extdiff.diff} | |
365 %If you would like to use an external tool to display modifications, | |
366 %you'll want to use the \hgext{extdiff} extension. This will let you | |
367 %use, for example, a graphical diff tool. | |
368 | |
369 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 | |
370 $B%-%9%H$G=PNO$9$k!%(B | |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
371 \interaction{extdiff.diff} |
358 | 372 $BJQ99$r30It%D!<%k$r;H$C$FI=<($7$?$$$J$i$P!$(B\hgext{extdiff}$B3HD%$r;H$&$HNI(B |
373 $B$$!%$3$N3HD%$ONc$($P%0%i%U%#%+%k$J(Bdiff$BI=<($r9T$&!%(B | |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
374 |
358 | 375 %The \hgext{extdiff} extension is bundled with Mercurial, so it's easy |
376 %to set up. In the \rcsection{extensions} section of your \hgrc, | |
377 %simply add a one-line entry to enable the extension. | |
378 | |
379 \hgext{extdiff}$B3HD%$O(BMercurial$B$KF1:-$5$l$F$$$k$N$G!$%;%C%H%"%C%W$OMF0W$G(B | |
380 $B$"$k!%(B\hgrc $B$NCf$N(B\rcsection{extensions}$B%;%/%7%g%s$K(B1$B9T$N@_Dj$rDI2C$9$k(B | |
381 $B$@$1$GNI$$!%(B | |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
382 \begin{codesample2} |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
383 [extensions] |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
384 extdiff = |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
385 \end{codesample2} |
358 | 386 |
387 %This introduces a command named \hgxcmd{extdiff}{extdiff}, which by | |
388 %default uses your system's \command{diff} command to generate a | |
389 %unified diff in the same form as the built-in \hgcmd{diff} command. | |
390 %\interaction{extdiff.extdiff} | |
391 %The result won't be exactly the same as with the built-in \hgcmd{diff} | |
392 %variations, because the output of \command{diff} varies from one | |
393 %system to another, even when passed the same options. | |
394 | |
395 $B$3$N3HD%$G(B\hgxcmd{extdiff}{extdiff}$B$H$$$&%3%^%s%I$,;H$($k$h$&$K$J$k!%(B | |
396 $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 | |
397 $B%s%I$HF1MM$N(Bunified$B7A<0$N(Bdiff$B$r@8@.$9$k!%(B | |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
398 \interaction{extdiff.extdiff} |
358 | 399 $BF@$i$l$k@.2LJ*$OAH$_9~$_$N(B\hgcmd{diff}$B$HA4$/F1$8$K$O$J$i$J$$$@$m$&!%M}M3(B |
400 $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 | |
401 $B$8=PNO$r$9$k$H$O8B$i$J$$$+$i$@!%(B | |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
402 |
358 | 403 %As the ``\texttt{making snapshot}'' lines of output above imply, the |
404 %\hgxcmd{extdiff}{extdiff} command works by creating two snapshots of | |
405 %your source tree. The first snapshot is of the source revision; the | |
406 %second, of the target revision or working directory. The | |
407 %\hgxcmd{extdiff}{extdiff} command generates these snapshots in a | |
408 %temporary directory, passes the name of each directory to an external | |
409 %diff viewer, then deletes the temporary directory. For efficiency, it | |
410 %only snapshots the directories and files that have changed between the | |
411 %two revisions. | |
412 | |
413 $B=PNO$N(B``\texttt{making snapshot}''$B9T$,<gD%$9$k$h$&(B | |
414 $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 | |
415 $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 | |
416 $B%o!<%-%s%0%G%#%l%/%H%j$N%?!<%2%C%H%j%S%8%g%s$G$"$k!%(B | |
417 \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 | |
418 $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 | |
419 $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 | |
420 $B99$N$"$C$?%G%#%l%/%H%j$H%U%!%$%k$N%9%J%C%W%7%g%C%H$@$1$r<h$k!%(B | |
421 | |
422 %Snapshot directory names have the same base name as your repository. | |
423 %If your repository path is \dirname{/quux/bar/foo}, then \dirname{foo} | |
424 %will be the name of each snapshot directory. Each snapshot directory | |
425 %name has its changeset ID appended, if appropriate. If a snapshot is | |
426 %of revision \texttt{a631aca1083f}, the directory will be named | |
427 %\dirname{foo.a631aca1083f}. A snapshot of the working directory won't | |
428 %have a changeset ID appended, so it would just be \dirname{foo} in | |
429 | |
430 %this example. To see what this looks like in practice, look again at | |
431 %the \hgxcmd{extdiff}{extdiff} example above. Notice that the diff has | |
432 %the snapshot directory names embedded in its header. | |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
433 |
358 | 434 $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 |
435 $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 | |
436 $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 | |
437 $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 | |
438 $B%j$O(B\dirname{foo.a631aca1083f}$B$H$J$k!%%o!<%-%s%0%G%#%l%/%H%j$N%9%J%C%W(B | |
439 $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 | |
440 $BA0$K$J$k!%<B:]$NF0:n$r8+$k$K$O!$>e5-$N(B\hgxcmd{extdiff}{extdiff}$B$r;2>H$5$l(B | |
441 $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 | |
442 $B$KN10U$5$l$?$$!%(B | |
443 | |
444 %The \hgxcmd{extdiff}{extdiff} command accepts two important options. | |
445 %The \hgxopt{extdiff}{extdiff}{-p} option lets you choose a program to | |
446 %view differences with, instead of \command{diff}. With the | |
447 %\hgxopt{extdiff}{extdiff}{-o} option, you can change the options that | |
448 %\hgxcmd{extdiff}{extdiff} passes to the program (by default, these | |
449 %options are ``\texttt{-Npru}'', which only make sense if you're | |
450 %running \command{diff}). In other respects, the | |
451 %\hgxcmd{extdiff}{extdiff} command acts similarly to the built-in | |
452 %\hgcmd{diff} command: you use the same option names, syntax, and | |
453 %arguments to specify the revisions you want, the files you want, and | |
454 %so on. | |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
455 |
358 | 456 \hgxcmd{extdiff}{extdiff}$B%3%^%s%I$K$O=EMW$J%*%W%7%g%s$,(B2$B$D$"$k!%(B |
457 \hgxopt{extdiff}{extdiff}{-p}$B%*%W%7%g%s$G:9J,$r<h$k%3%^%s%I$H$7$F(B | |
458 \command{diff}$B0J30$N%3%^%s%I$r;XDj$G$-$k!%(B \hgxopt{extdiff}{extdiff}{-o} | |
459 $B%*%W%7%g%s$G(B\hgxcmd{extdiff}{extdiff}$B$,30It%W%m%0%i%`$KEO$9%*%W%7%g%s$rJQ(B | |
460 $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 | |
461 \command{diff}$B$,5/F0$5$l$k;~$N$_0UL#$r;}$D!%!K$=$NB>$NE@$G$O(B | |
462 \hgxcmd{extdiff}{extdiff}$B%3%^%s%I$O%S%k%H%$%s$N(B\hgcmd{diff}$B$HF1MM$NF0:n$r(B | |
463 $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 | |
464 $B<0$J$I$r;}$D!%(B | |
465 | |
466 %As an example, here's how to run the normal system \command{diff} | |
467 %command, getting it to generate context diffs (using the | |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
468 |
358 | 469 %\cmdopt{diff}{-c} option) instead of unified diffs, and five lines of |
470 %context instead of the default three (passing \texttt{5} as the | |
471 %argument to the \cmdopt{diff}{-C} option). | |
472 %\interaction{extdiff.extdiff-ctx} | |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
473 |
358 | 474 $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 |
475 $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 | |
476 $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 | |
477 $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 | |
478 $B$h$&$K$9$k!%(B | |
479 | |
480 %Launching a visual diff tool is just as easy. Here's how to launch | |
481 %the \command{kdiff3} viewer. | |
482 $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 | |
483 $B5/F0J}K!$r<($9!%(B | |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
484 \begin{codesample2} |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
485 hg extdiff -p kdiff3 -o '' |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
486 \end{codesample2} |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
487 |
358 | 488 %If your diff viewing command can't deal with directories, you can |
489 %easily work around this with a little scripting. For an example of | |
490 %such scripting in action with the \hgext{mq} extension and the | |
491 %\command{interdiff} command, see | |
492 %section~\ref{mq-collab:tips:interdiff}. | |
493 | |
494 $BMxMQ$7$h$&$H$9$k(Bdiff$B%S%e!<%3%^%s%I$,%G%#%l%/%H%j$r07$($J$$>l9g!$$o$:$+$J(B | |
495 $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 | |
496 $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 | |
497 $B4V$N$b$N$,$"$k!%$3$l$K$D$$$F$O(B\ref{mq-collab:tips:interdiff}$B$r;2>H$5$l$?(B | |
498 $B$$!%(B | |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
499 |
355 | 500 %\subsection{Defining command aliases} |
501 \subsection{$B%3%^%s%I$N%(%$%j%"%9$r:n$k(B} | |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
502 |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
503 It can be cumbersome to remember the options to both the |
231
28ddbf9f3729
Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents:
226
diff
changeset
|
504 \hgxcmd{extdiff}{extdiff} command and the diff viewer you want to use, |
28ddbf9f3729
Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents:
226
diff
changeset
|
505 so the \hgext{extdiff} extension lets you define \emph{new} commands |
28ddbf9f3729
Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents:
226
diff
changeset
|
506 that will invoke your diff viewer with exactly the right options. |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
507 |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
508 All you need to do is edit your \hgrc, and add a section named |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
509 \rcsection{extdiff}. Inside this section, you can define multiple |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
510 commands. Here's how to add a \texttt{kdiff3} command. Once you've |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
511 defined this, you can type ``\texttt{hg kdiff3}'' and the |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
512 \hgext{extdiff} extension will run \command{kdiff3} for you. |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
513 \begin{codesample2} |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
514 [extdiff] |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
515 cmd.kdiff3 = |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
516 \end{codesample2} |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
517 If you leave the right hand side of the definition empty, as above, |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
518 the \hgext{extdiff} extension uses the name of the command you defined |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
519 as the name of the external program to run. But these names don't |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
520 have to be the same. Here, we define a command named ``\texttt{hg |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
521 wibble}'', which runs \command{kdiff3}. |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
522 \begin{codesample2} |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
523 [extdiff] |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
524 cmd.wibble = kdiff3 |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
525 \end{codesample2} |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
526 |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
527 You can also specify the default options that you want to invoke your |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
528 diff viewing program with. The prefix to use is ``\texttt{opts.}'', |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
529 followed by the name of the command to which the options apply. This |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
530 example defines a ``\texttt{hg vimdiff}'' command that runs the |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
531 \command{vim} editor's \texttt{DirDiff} extension. |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
532 \begin{codesample2} |
355 | 533 [extdiff] |
226
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
534 cmd.vimdiff = vim |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
535 opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)' |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
536 \end{codesample2} |
eef2171243e8
Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
224
diff
changeset
|
537 |
355 | 538 %\section{Cherrypicking changes with the \hgext{transplant} extension} |
539 \section{\hgext{transplant}$B3HD%$rMQ$$$?%A%'%j!<%T%C%-%s%099?7(B} | |
232
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
540 \label{sec:hgext:transplant} |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
541 |
355 | 542 %Need to have a long chat with Brendan about this. |
543 $B!J(BBrendan$B$H$h$/OC$r$9$kI,MW$,$"$k!%!K(B | |
232
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
544 |
355 | 545 %\section{Send changes via email with the \hgext{patchbomb} extension} |
546 \section{\hgext{patchbomb}$B3HD%$K$h$C$FJQ99$r%a!<%k$9$k(B} | |
232
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
547 \label{sec:hgext:patchbomb} |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
548 |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
549 Many projects have a culture of ``change review'', in which people |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
550 send their modifications to a mailing list for others to read and |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
551 comment on before they commit the final version to a shared |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
552 repository. Some projects have people who act as gatekeepers; they |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
553 apply changes from other people to a repository to which those others |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
554 don't have access. |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
555 |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
556 Mercurial makes it easy to send changes over email for review or |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
557 application, via its \hgext{patchbomb} extension. The extension is so |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
558 namd because changes are formatted as patches, and it's usual to send |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
559 one changeset per email message. Sending a long series of changes by |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
560 email is thus much like ``bombing'' the recipient's inbox, hence |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
561 ``patchbomb''. |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
562 |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
563 As usual, the basic configuration of the \hgext{patchbomb} extension |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
564 takes just one or two lines in your \hgrc. |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
565 \begin{codesample2} |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
566 [extensions] |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
567 patchbomb = |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
568 \end{codesample2} |
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
569 Once you've enabled the extension, you will have a new command |
241
09d5897ad935
Fix a few more errors in the index.
Bryan O'Sullivan <bos@serpentine.com>
parents:
232
diff
changeset
|
570 available, named \hgxcmd{patchbomb}{email}. |
232
2469608b4a08
Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
231
diff
changeset
|
571 |
243
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
572 The safest and best way to invoke the \hgxcmd{patchbomb}{email} |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
573 command is to \emph{always} run it first with the |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
574 \hgxopt{patchbomb}{email}{-n} option. This will show you what the |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
575 command \emph{would} send, without actually sending anything. Once |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
576 you've had a quick glance over the changes and verified that you are |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
577 sending the right ones, you can rerun the same command, with the |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
578 \hgxopt{patchbomb}{email}{-n} option removed. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
579 |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
580 The \hgxcmd{patchbomb}{email} command accepts the same kind of |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
581 revision syntax as every other Mercurial command. For example, this |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
582 command will send every revision between 7 and \texttt{tip}, |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
583 inclusive. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
584 \begin{codesample2} |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
585 hg email -n 7:tip |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
586 \end{codesample2} |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
587 You can also specify a \emph{repository} to compare with. If you |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
588 provide a repository but no revisions, the \hgxcmd{patchbomb}{email} |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
589 command will send all revisions in the local repository that are not |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
590 present in the remote repository. If you additionally specify |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
591 revisions or a branch name (the latter using the |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
592 \hgxopt{patchbomb}{email}{-b} option), this will constrain the |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
593 revisions sent. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
594 |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
595 It's perfectly safe to run the \hgxcmd{patchbomb}{email} command |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
596 without the names of the people you want to send to: if you do this, |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
597 it will just prompt you for those values interactively. (If you're |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
598 using a Linux or Unix-like system, you should have enhanced |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
599 \texttt{readline}-style editing capabilities when entering those |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
600 headers, too, which is useful.) |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
601 |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
602 When you are sending just one revision, the \hgxcmd{patchbomb}{email} |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
603 command will by default use the first line of the changeset |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
604 description as the subject of the single email message it sends. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
605 |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
606 If you send multiple revisions, the \hgxcmd{patchbomb}{email} command |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
607 will usually send one message per changeset. It will preface the |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
608 series with an introductory message, in which you should describe the |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
609 purpose of the series of changes you're sending. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
610 |
355 | 611 %\subsection{Changing the behaviour of patchbombs} |
612 \subsection{patchbombs$B$N5sF0$rJQ99$9$k(B} | |
243
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
613 |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
614 Not every project has exactly the same conventions for sending changes |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
615 in email; the \hgext{patchbomb} extension tries to accommodate a |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
616 number of variations through command line options. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
617 \begin{itemize} |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
618 \item You can write a subject for the introductory message on the |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
619 command line using the \hgxopt{patchbomb}{email}{-s} option. This |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
620 takes one argument, the text of the subject to use. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
621 \item To change the email address from which the messages originate, |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
622 use the \hgxopt{patchbomb}{email}{-f} option. This takes one |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
623 argument, the email address to use. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
624 \item The default behaviour is to send unified diffs (see |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
625 section~\ref{sec:mq:patch} for a description of the format), one per |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
626 message. You can send a binary bundle instead with the |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
627 \hgxopt{patchbomb}{email}{-b} option. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
628 \item Unified diffs are normally prefaced with a metadata header. You |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
629 can omit this, and send unadorned diffs, with the |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
630 \hgxopt{patchbomb}{email}{--plain} option. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
631 \item Diffs are normally sent ``inline'', in the same body part as the |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
632 description of a patch. This makes it easiest for the largest |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
633 number of readers to quote and respond to parts of a diff, as some |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
634 mail clients will only quote the first MIME body part in a message. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
635 If you'd prefer to send the description and the diff in separate |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
636 body parts, use the \hgxopt{patchbomb}{email}{-a} option. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
637 \item Instead of sending mail messages, you can write them to an |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
638 \texttt{mbox}-format mail folder using the |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
639 \hgxopt{patchbomb}{email}{-m} option. That option takes one |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
640 argument, the name of the file to write to. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
641 \item If you would like to add a \command{diffstat}-format summary to |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
642 each patch, and one to the introductory message, use the |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
643 \hgxopt{patchbomb}{email}{-d} option. The \command{diffstat} |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
644 command displays a table containing the name of each file patched, |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
645 the number of lines affected, and a histogram showing how much each |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
646 file is modified. This gives readers a qualitative glance at how |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
647 complex a patch is. |
7df934d3dcb5
Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents:
241
diff
changeset
|
648 \end{itemize} |
231
28ddbf9f3729
Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents:
226
diff
changeset
|
649 |
355 | 650 %%% Local Variables: |
293
3b1291f24c0d
- replaved latex-mode to yatex-mode
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
290
diff
changeset
|
651 %%% mode: yatex |
223
4c9b9416cd23
Skeleton for chapter on extensions.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
652 %%% TeX-master: "00book" |
355 | 653 %%% End: |