annotate ja/hgext.tex @ 293:3b1291f24c0d

- replaved latex-mode to yatex-mode - comment out a few lines
author Yoshiki Yazawa <yaz@cc.rim.or.jp>
date Thu, 07 Feb 2008 23:11:10 +0900
parents b0db5adf11c1
children 65aec2b27f64
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
223
4c9b9416cd23 Skeleton for chapter on extensions.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
1 \chapter{Adding functionality with extensions}
4c9b9416cd23 Skeleton for chapter on extensions.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
2 \label{chap:hgext}
4c9b9416cd23 Skeleton for chapter on extensions.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
3
224
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
4 While the core of Mercurial is quite complete from a functionality
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
5 standpoint, it's deliberately shorn of fancy features. This approach
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
6 of preserving simplicity keeps the software easy to deal with for both
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
7 maintainers and users.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
8
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
9 However, Mercurial doesn't box you in with an inflexible command set:
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
10 you can add features to it as \emph{extensions} (sometimes known as
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
11 \emph{plugins}). We've already discussed a few of these extensions in
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
12 earlier chapters.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
13 \begin{itemize}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
14 \item Section~\ref{sec:tour-merge:fetch} covers the \hgext{fetch}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
15 extension; this combines pulling new changes and merging them with
231
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
16 local changes into a single command, \hgxcmd{fetch}{fetch}.
224
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
17 \item In chapter~\ref{chap:hook}, we covered several extensions that
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
18 are useful for hook-related functionality: \hgext{acl} adds access
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
19 control lists; \hgext{bugzilla} adds integration with the Bugzilla
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
20 bug tracking system; and \hgext{notify} sends notification emails on
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
21 new changes.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
22 \item The Mercurial Queues patch management extension is so invaluable
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
23 that it merits two chapters and an appendix all to itself.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
24 Chapter~\ref{chap:mq} covers the basics;
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
25 chapter~\ref{chap:mq-collab} discusses advanced topics; and
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
26 appendix~\ref{chap:mqref} goes into detail on each command.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
27 \end{itemize}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
28
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
29 In this chapter, we'll cover some of the other extensions that are
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
30 available for Mercurial, and briefly touch on some of the machinery
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
31 you'll need to know about if you want to write an extension of your
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
32 own.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
33 \begin{itemize}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
34 \item In section~\ref{sec:hgext:inotify}, we'll discuss the
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
35 possibility of \emph{huge} performance improvements using the
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
36 \hgext{inotify} extension.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
37 \end{itemize}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
38
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
39 \section{Improve performance with the \hgext{inotify} extension}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
40 \label{sec:hgext:inotify}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
41
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
42 Are you interested in having some of the most common Mercurial
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
43 operations run as much as a hundred times faster? Read on!
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
44
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
45 Mercurial has great performance under normal circumstances. For
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
46 example, when you run the \hgcmd{status} command, Mercurial has to
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
47 scan almost every directory and file in your repository so that it can
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
48 display file status. Many other Mercurial commands need to do the
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
49 same work behind the scenes; for example, the \hgcmd{diff} command
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
50 uses the status machinery to avoid doing an expensive comparison
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
51 operation on files that obviously haven't changed.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
52
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
53 Because obtaining file status is crucial to good performance, the
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
54 authors of Mercurial have optimised this code to within an inch of its
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
55 life. However, there's no avoiding the fact that when you run
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
56 \hgcmd{status}, Mercurial is going to have to perform at least one
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
57 expensive system call for each managed file to determine whether it's
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
58 changed since the last time Mercurial checked. For a sufficiently
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
59 large repository, this can take a long time.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
60
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
61 To put a number on the magnitude of this effect, I created a
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
62 repository containing 150,000 managed files. I timed \hgcmd{status}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
63 as taking ten seconds to run, even when \emph{none} of those files had
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
64 been modified.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
65
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
66 Many modern operating systems contain a file notification facility.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
67 If a program signs up to an appropriate service, the operating system
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
68 will notify it every time a file of interest is created, modified, or
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
69 deleted. On Linux systems, the kernel component that does this is
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
70 called \texttt{inotify}.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
71
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
72 Mercurial's \hgext{inotify} extension talks to the kernel's
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
73 \texttt{inotify} component to optimise \hgcmd{status} commands. The
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
74 extension has two components. A daemon sits in the background and
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
75 receives notifications from the \texttt{inotify} subsystem. It also
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
76 listens for connections from a regular Mercurial command. The
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
77 extension modifies Mercurial's behaviour so that instead of scanning
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
78 the filesystem, it queries the daemon. Since the daemon has perfect
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
79 information about the state of the repository, it can respond with a
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
80 result instantaneously, avoiding the need to scan every directory and
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
81 file in the repository.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
82
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
83 Recall the ten seconds that I measured plain Mercurial as taking to
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
84 run \hgcmd{status} on a 150,000 file repository. With the
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
85 \hgext{inotify} extension enabled, the time dropped to 0.1~seconds, a
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
86 factor of \emph{one hundred} faster.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
87
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
88 Before we continue, please pay attention to some caveats.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
89 \begin{itemize}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
90 \item The \hgext{inotify} extension is Linux-specific. Because it
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
91 interfaces directly to the Linux kernel's \texttt{inotify}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
92 subsystem, it does not work on other operating systems.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
93 \item It should work on any Linux distribution that was released after
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
94 early~2005. Older distributions are likely to have a kernel that
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
95 lacks \texttt{inotify}, or a version of \texttt{glibc} that does not
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
96 have the necessary interfacing support.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
97 \item Not all filesystems are suitable for use with the
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
98 \hgext{inotify} extension. Network filesystems such as NFS are a
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
99 non-starter, for example, particularly if you're running Mercurial
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
100 on several systems, all mounting the same network filesystem. The
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
101 kernel's \texttt{inotify} system has no way of knowing about changes
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
102 made on another system. Most local filesystems (e.g.~ext3, XFS,
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
103 ReiserFS) should work fine.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
104 \end{itemize}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
105
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
106 The \hgext{inotify} extension is not yet shipped with Mercurial as of
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
107 May~2007, so it's a little more involved to set up than other
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
108 extensions. But the performance improvement is worth it!
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
109
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
110 The extension currently comes in two parts: a set of patches to the
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
111 Mercurial source code, and a library of Python bindings to the
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
112 \texttt{inotify} subsystem.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
113 \begin{note}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
114 There are \emph{two} Python \texttt{inotify} binding libraries. One
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
115 of them is called \texttt{pyinotify}, and is packaged by some Linux
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
116 distributions as \texttt{python-inotify}. This is \emph{not} the
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
117 one you'll need, as it is too buggy and inefficient to be practical.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
118 \end{note}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
119 To get going, it's best to already have a functioning copy of
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
120 Mercurial installed.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
121 \begin{note}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
122 If you follow the instructions below, you'll be \emph{replacing} and
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
123 overwriting any existing installation of Mercurial that you might
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
124 already have, using the latest ``bleeding edge'' Mercurial code.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
125 Don't say you weren't warned!
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
126 \end{note}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
127 \begin{enumerate}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
128 \item Clone the Python \texttt{inotify} binding repository. Build and
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
129 install it.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
130 \begin{codesample4}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
131 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
132 cd inotify
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
133 python setup.py build --force
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
134 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
135 \end{codesample4}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
136 \item Clone the \dirname{crew} Mercurial repository. Clone the
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
137 \hgext{inotify} patch repository so that Mercurial Queues will be
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
138 able to apply patches to your cope of the \dirname{crew} repository.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
139 \begin{codesample4}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
140 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
141 hg clone crew inotify
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
142 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
143 \end{codesample4}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
144 \item Make sure that you have the Mercurial Queues extension,
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
145 \hgext{mq}, enabled. If you've never used MQ, read
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
146 section~\ref{sec:mq:start} to get started quickly.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
147 \item Go into the \dirname{inotify} repo, and apply all of the
231
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
148 \hgext{inotify} patches using the \hgxopt{mq}{qpush}{-a} option to
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
149 the \hgxcmd{mq}{qpush} command.
224
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
150 \begin{codesample4}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
151 cd inotify
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
152 hg qpush -a
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
153 \end{codesample4}
231
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
154 If you get an error message from \hgxcmd{mq}{qpush}, you should not
224
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
155 continue. Instead, ask for help.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
156 \item Build and install the patched version of Mercurial.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
157 \begin{codesample4}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
158 python setup.py build --force
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
159 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
160 \end{codesample4}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
161 \end{enumerate}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
162 Once you've build a suitably patched version of Mercurial, all you
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
163 need to do to enable the \hgext{inotify} extension is add an entry to
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
164 your \hgrc.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
165 \begin{codesample2}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
166 [extensions]
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
167 inotify =
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
168 \end{codesample2}
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
169 When the \hgext{inotify} extension is enabled, Mercurial will
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
170 automatically and transparently start the status daemon the first time
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
171 you run a command that needs status in a repository. It runs one
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
172 status daemon per repository.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
173
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
174 The status daemon is started silently, and runs in the background. If
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
175 you look at a list of running processes after you've enabled the
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
176 \hgext{inotify} extension and run a few commands in different
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
177 repositories, you'll thus see a few \texttt{hg} processes sitting
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
178 around, waiting for updates from the kernel and queries from
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
179 Mercurial.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
180
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
181 The first time you run a Mercurial command in a repository when you
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
182 have the \hgext{inotify} extension enabled, it will run with about the
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
183 same performance as a normal Mercurial command. This is because the
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
184 status daemon needs to perform a normal status scan so that it has a
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
185 baseline against which to apply later updates from the kernel.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
186 However, \emph{every} subsequent command that does any kind of status
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
187 check should be noticeably faster on repositories of even fairly
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
188 modest size. Better yet, the bigger your repository is, the greater a
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
189 performance advantage you'll see. The \hgext{inotify} daemon makes
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
190 status operations almost instantaneous on repositories of all sizes!
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
191
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
192 If you like, you can manually start a status daemon using the
231
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
193 \hgxcmd{inotify}{inserve} command. This gives you slightly finer
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
194 control over how the daemon ought to run. This command will of course
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
195 only be available when the \hgext{inotify} extension is enabled.
224
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
196
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
197 When you're using the \hgext{inotify} extension, you should notice
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
198 \emph{no difference at all} in Mercurial's behaviour, with the sole
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
199 exception of status-related commands running a whole lot faster than
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
200 they used to. You should specifically expect that commands will not
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
201 print different output; neither should they give different results.
34943a3d50d6 Start writing up extensions. Begin with inotify.
Bryan O'Sullivan <bos@serpentine.com>
parents: 223
diff changeset
202 If either of these situations occurs, please report a bug.
223
4c9b9416cd23 Skeleton for chapter on extensions.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
203
226
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
204 \section{Flexible diff support with the \hgext{extdiff} extension}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
205 \label{sec:hgext:extdiff}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
206
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
207 Mercurial's built-in \hgcmd{diff} command outputs plaintext unified
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
208 diffs.
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
209 \interaction{extdiff.diff}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
210 If you would like to use an external tool to display modifications,
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
211 you'll want to use the \hgext{extdiff} extension. This will let you
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
212 use, for example, a graphical diff tool.
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
213
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
214 The \hgext{extdiff} extension is bundled with Mercurial, so it's easy
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
215 to set up. In the \rcsection{extensions} section of your \hgrc,
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
216 simply add a one-line entry to enable the extension.
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
217 \begin{codesample2}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
218 [extensions]
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
219 extdiff =
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
220 \end{codesample2}
231
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
221 This introduces a command named \hgxcmd{extdiff}{extdiff}, which by
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
222 default uses your system's \command{diff} command to generate a
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
223 unified diff in the same form as the built-in \hgcmd{diff} command.
226
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
224 \interaction{extdiff.extdiff}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
225 The result won't be exactly the same as with the built-in \hgcmd{diff}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
226 variations, because the output of \command{diff} varies from one
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
227 system to another, even when passed the same options.
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
228
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
229 As the ``\texttt{making snapshot}'' lines of output above imply, the
231
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
230 \hgxcmd{extdiff}{extdiff} command works by creating two snapshots of
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
231 your source tree. The first snapshot is of the source revision; the
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
232 second, of the target revision or working directory. The
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
233 \hgxcmd{extdiff}{extdiff} command generates these snapshots in a
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
234 temporary directory, passes the name of each directory to an external
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
235 diff viewer, then deletes the temporary directory. For efficiency, it
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
236 only snapshots the directories and files that have changed between the
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
237 two revisions.
226
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
238
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
239 Snapshot directory names have the same base name as your repository.
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
240 If your repository path is \dirname{/quux/bar/foo}, then \dirname{foo}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
241 will be the name of each snapshot directory. Each snapshot directory
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
242 name has its changeset ID appended, if appropriate. If a snapshot is
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
243 of revision \texttt{a631aca1083f}, the directory will be named
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
244 \dirname{foo.a631aca1083f}. A snapshot of the working directory won't
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
245 have a changeset ID appended, so it would just be \dirname{foo} in
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
246 this example. To see what this looks like in practice, look again at
231
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
247 the \hgxcmd{extdiff}{extdiff} example above. Notice that the diff has
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
248 the snapshot directory names embedded in its header.
226
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
249
231
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
250 The \hgxcmd{extdiff}{extdiff} command accepts two important options.
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
251 The \hgxopt{extdiff}{extdiff}{-p} option lets you choose a program to
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
252 view differences with, instead of \command{diff}. With the
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
253 \hgxopt{extdiff}{extdiff}{-o} option, you can change the options that
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
254 \hgxcmd{extdiff}{extdiff} passes to the program (by default, these
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
255 options are ``\texttt{-Npru}'', which only make sense if you're
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
256 running \command{diff}). In other respects, the
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
257 \hgxcmd{extdiff}{extdiff} command acts similarly to the built-in
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
258 \hgcmd{diff} command: you use the same option names, syntax, and
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
259 arguments to specify the revisions you want, the files you want, and
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
260 so on.
226
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
261
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
262 As an example, here's how to run the normal system \command{diff}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
263 command, getting it to generate context diffs (using the
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
264 \cmdopt{diff}{-c} option) instead of unified diffs, and five lines of
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
265 context instead of the default three (passing \texttt{5} as the
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
266 argument to the \cmdopt{diff}{-C} option).
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
267 \interaction{extdiff.extdiff-ctx}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
268
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
269 Launching a visual diff tool is just as easy. Here's how to launch
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
270 the \command{kdiff3} viewer.
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
271 \begin{codesample2}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
272 hg extdiff -p kdiff3 -o ''
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
273 \end{codesample2}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
274
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
275 If your diff viewing command can't deal with directories, you can
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
276 easily work around this with a little scripting. For an example of
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
277 such scripting in action with the \hgext{mq} extension and the
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
278 \command{interdiff} command, see
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
279 section~\ref{mq-collab:tips:interdiff}.
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
280
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
281 \subsection{Defining command aliases}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
282
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
283 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
284 \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
285 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
286 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
287
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
288 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
289 \rcsection{extdiff}. Inside this section, you can define multiple
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
290 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
291 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
292 \hgext{extdiff} extension will run \command{kdiff3} for you.
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
293 \begin{codesample2}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
294 [extdiff]
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
295 cmd.kdiff3 =
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
296 \end{codesample2}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
297 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
298 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
299 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
300 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
301 wibble}'', which runs \command{kdiff3}.
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
302 \begin{codesample2}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
303 [extdiff]
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
304 cmd.wibble = kdiff3
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
305 \end{codesample2}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
306
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
307 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
308 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
309 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
310 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
311 \command{vim} editor's \texttt{DirDiff} extension.
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
312 \begin{codesample2}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
313 [extdiff]
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
314 cmd.vimdiff = vim
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
315 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
316 \end{codesample2}
eef2171243e8 Document the extdiff extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 224
diff changeset
317
232
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
318 \section{Cherrypicking changes with the \hgext{transplant} extension}
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
319 \label{sec:hgext:transplant}
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
320
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
321 Need to have a long chat with Brendan about this.
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
322
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
323 \section{Send changes via email with the \hgext{patchbomb} extension}
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
324 \label{sec:hgext:patchbomb}
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
325
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
326 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
327 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
328 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
329 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
330 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
331 don't have access.
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
332
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
333 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
334 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
335 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
336 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
337 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
338 ``patchbomb''.
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
339
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
340 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
341 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
342 \begin{codesample2}
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
343 [extensions]
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
344 patchbomb =
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
345 \end{codesample2}
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
346 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
347 available, named \hgxcmd{patchbomb}{email}.
232
2469608b4a08 Start writing up the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 231
diff changeset
348
243
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
349 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
350 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
351 \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
352 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
353 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
354 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
355 \hgxopt{patchbomb}{email}{-n} option removed.
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
356
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
357 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
358 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
359 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
360 inclusive.
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
361 \begin{codesample2}
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
362 hg email -n 7:tip
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
363 \end{codesample2}
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
364 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
365 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
366 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
367 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
368 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
369 \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
370 revisions sent.
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
371
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
372 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
373 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
374 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
375 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
376 \texttt{readline}-style editing capabilities when entering those
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
377 headers, too, which is useful.)
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
378
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
379 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
380 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
381 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
382
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
383 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
384 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
385 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
386 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
387
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
388 \subsection{Changing the behaviour of patchbombs}
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
389
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
390 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
391 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
392 number of variations through command line options.
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
393 \begin{itemize}
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
394 \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
395 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
396 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
397 \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
398 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
399 argument, the email address to use.
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
400 \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
401 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
402 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
403 \hgxopt{patchbomb}{email}{-b} option.
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
404 \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
405 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
406 \hgxopt{patchbomb}{email}{--plain} option.
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
407 \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
408 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
409 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
410 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
411 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
412 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
413 \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
414 \texttt{mbox}-format mail folder using the
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
415 \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
416 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
417 \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
418 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
419 \hgxopt{patchbomb}{email}{-d} option. The \command{diffstat}
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
420 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
421 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
422 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
423 complex a patch is.
7df934d3dcb5 Further document the patchbomb extension.
Bryan O'Sullivan <bos@serpentine.com>
parents: 241
diff changeset
424 \end{itemize}
231
28ddbf9f3729 Use new \hgxcmd and \hgxopt commands in a few places.
Bryan O'Sullivan <bos@serpentine.com>
parents: 226
diff changeset
425
223
4c9b9416cd23 Skeleton for chapter on extensions.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
426 %%% Local Variables:
293
3b1291f24c0d - replaved latex-mode to yatex-mode
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents: 290
diff changeset
427 %%% mode: yatex
223
4c9b9416cd23 Skeleton for chapter on extensions.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
428 %%% TeX-master: "00book"
4c9b9416cd23 Skeleton for chapter on extensions.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
429 %%% End: