Mercurial > hgbook
annotate en/hgext.tex @ 437:58dfbe3e1620
clarification on the order of the list of translators
author | jerojasro@localhost |
---|---|
date | Sat, 18 Oct 2008 22:53:37 -0500 |
parents | 7a6bd93174bd |
children |
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: |
4c9b9416cd23
Skeleton for chapter on extensions.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
427 %%% mode: latex |
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: |