Mercurial > hg
annotate mercurial/help/internals/extensions.txt @ 40729:c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
In short, this is the "reposetup" function for ui. It allows us to modify
ui attributes without extending ui.__class__. Before, the only way to do
that was to abuse the config dictionary, which is copied across ui instances.
See the next patch for usage example.
author | Yuya Nishihara <yuya@tcha.org> |
---|---|
date | Mon, 12 Nov 2018 21:10:51 +0900 |
parents | 04d08f17ce7a |
children | 86f6b441adea |
rev | line source |
---|---|
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
1 Extensions allow the creation of new features and using them directly from |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
2 the main hg command line as if they were built-in commands. The extensions |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
3 have full access to the *internal* API. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
4 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
5 Use of Mercurial's internal API very likely makes your code subject to |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
6 Mercurial's license. Before going any further, read the License page. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
7 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
8 There are NO guarantees that third-party code calling into Mercurial's |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
9 internals won't break from release to release. If you do use Mercurial's API |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
10 for published third-party code, we expect you to test your code before each |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
11 major Mercurial release. This will prevent various bug reports from your users |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
12 when they upgrade their copy of Mercurial. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
13 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
14 File Layout |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
15 =========== |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
16 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
17 Extensions are usually written as simple python modules. Larger ones are |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
18 better split into multiple modules of a single package (see the convert |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
19 extension). The package root module gives its name to the extension and |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
20 implements the ``cmdtable`` and optional callbacks described below. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
21 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
22 Command table |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
23 ============= |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
24 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
25 To write your own extension, your python module can provide an optional dict |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
26 named ``cmdtable`` with entries describing each command. A command should be |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
27 registered to the ``cmdtable`` by ``@command`` decorator. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
28 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
29 Example using ``@command`` decorator (requires Mercurial 1.9):: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
30 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
31 from mercurial import cmdutil |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
32 from mercurial.i18n import _ |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
33 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
34 cmdtable = {} |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
35 command = cmdutil.command(cmdtable) |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
36 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
37 @command('print-parents', |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
38 [('s', 'short', None, _('print short form')), |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
39 ('l', 'long', None, _('print long form'))], |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
40 _('[options] node')) |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
41 def printparents(ui, repo, node, **opts): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
42 ... |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
43 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
44 The cmdtable dictionary |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
45 ----------------------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
46 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
47 The ``cmdtable`` dictionary uses as key the new command names, and, as value, |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
48 a tuple containing: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
49 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
50 1. the function to be called when the command is used. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
51 2. a list of options the command can take. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
52 3. a command line synopsis for the command (the function docstring is used for |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
53 the full help). |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
54 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
55 List of options |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
56 --------------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
57 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
58 All the command flag options are documented in the mercurial/fancyopts.py |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
59 sources. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
60 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
61 The options list is a list of tuples containing: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
62 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
63 1. the short option letter, or ``''`` if no short option is available |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
64 (for example, ``o`` for a ``-o`` option). |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
65 2. the long option name (for example, ``option`` for a ``--option`` option). |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
66 3. a default value for the option. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
67 4. a help string for the option (it's possible to omit the "hg newcommand" |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
68 part and only the options and parameter substring is needed). |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
69 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
70 Command function signatures |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
71 --------------------------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
72 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
73 Functions that implement new commands always receive a ``ui`` and usually |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
74 a ``repo`` parameter. The rest of parameters are taken from the command line |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
75 items that don't start with a dash and are passed in the same order they were |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
76 written. If no default value is given in the parameter list they are required. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
77 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
78 If there is no repo to be associated with the command and consequently no |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
79 ``repo`` passed, then ``norepo=True`` should be passed to the ``@command`` |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
80 decorator:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
81 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
82 @command('mycommand', [], norepo=True) |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
83 def mycommand(ui, **opts): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
84 ... |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
85 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
86 For examples of ``norepo``, see the convert extension. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
87 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
88 Command function docstrings |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
89 =========================== |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
90 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
91 The docstring of your function is used as the main help text, shown by |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
92 ``hg help mycommand``. The docstring should be formatted using a simple |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
93 subset of reStructuredText markup. The supported constructs include: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
94 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
95 Paragraphs:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
96 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
97 This is a paragraph. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
98 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
99 Paragraphs are separated |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
100 by blank lines. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
101 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
102 A verbatim block is introduced with a double colon followed by an indented |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
103 block. The double colon is turned into a single colon on display:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
104 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
105 Some text:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
106 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
107 verbatim |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
108 text |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
109 !! |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
110 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
111 We have field lists:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
112 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
113 :key1: value1 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
114 :key2: value2 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
115 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
116 Bullet lists:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
117 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
118 - foo |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
119 - bar |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
120 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
121 Enumerated lists:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
122 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
123 1. foo |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
124 2. bar |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
125 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
126 Inline markup:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
127 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
128 ``*bold*``, ``monospace``, :hg:`command` |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
129 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
130 Mark Mercurial commands with ``:hg:`` to make a nice link to the corresponding |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
131 documentation. We'll expand the support if new constructs can be parsed |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
132 without too much trouble. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
133 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
134 Communicating with the user |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
135 =========================== |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
136 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
137 Besides the ``ui`` methods, like ``ui.write(*msg)`` or |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
138 ``ui.prompt(msg, default="y")``, an extension can add help text for each |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
139 of its commands and the extension itself. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
140 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
141 The module docstring will be used as help string when ``hg help extensionname`` |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
142 is used and, similarly, the help string for a command and the docstring |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
143 belonging to the function that's wrapped by the command will be shown when |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
144 ``hg help command`` is invoked. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
145 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
146 Setup Callbacks |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
147 =============== |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
148 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
149 Extensions are loaded in phases. All extensions are processed in a given phase |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
150 before the next phase begins. In the first phase, all extension modules are |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
151 loaded and registered with Mercurial. This means that you can find all enabled |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
152 extensions with ``extensions.find`` in the following phases. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
153 |
40596
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
154 Extension setup |
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
155 --------------- |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
156 |
40596
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
157 There are two callbacks to be called when extensions are loaded, named |
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
158 ``uisetup`` and ``extsetup``. ``uisetup`` is called first for each extension, |
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
159 then ``extsetup`` is called. This means ``extsetup`` can be useful in case |
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
160 one extension optionally depends on another extension. |
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
161 |
40597
04d08f17ce7a
help: document weird behavior of uisetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40596
diff
changeset
|
162 Both ``uisetup`` and ``extsetup`` receive a ui object with the local |
04d08f17ce7a
help: document weird behavior of uisetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40596
diff
changeset
|
163 repository configuration:: |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
164 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
165 def uisetup(ui): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
166 # ... |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
167 |
40596
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
168 def extsetup(ui): |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
169 # ... |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
170 |
40597
04d08f17ce7a
help: document weird behavior of uisetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40596
diff
changeset
|
171 Be aware that ``uisetup`` in NOT the function to configure a ``ui`` instance. |
04d08f17ce7a
help: document weird behavior of uisetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40596
diff
changeset
|
172 It's called only once per process, not per ``ui`` instance. Also, any changes |
04d08f17ce7a
help: document weird behavior of uisetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40596
diff
changeset
|
173 to the ``ui`` may be discarded because the ``ui`` here temporarily loaded |
04d08f17ce7a
help: document weird behavior of uisetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40596
diff
changeset
|
174 local configuration. So, it's generally wrong to do `ui.setconfig()` in |
04d08f17ce7a
help: document weird behavior of uisetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40596
diff
changeset
|
175 these callbacks. Notable exception is setting ``pre/post-<command>`` hooks |
04d08f17ce7a
help: document weird behavior of uisetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40596
diff
changeset
|
176 and extending ``ui.__class__``. |
04d08f17ce7a
help: document weird behavior of uisetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40596
diff
changeset
|
177 |
40596
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
178 In Mercurial 1.3.1 or earlier, ``extsetup`` takes no argument. |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
179 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
180 Command table setup |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
181 ------------------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
182 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
183 After ``extsetup``, the ``cmdtable`` is copied into the global command table |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
184 in Mercurial. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
185 |
40729
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
186 Ui instance setup |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
187 ----------------- |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
188 |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
189 The optional ``uipopulate`` is called for each ``ui`` instance after |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
190 configuration is loaded, where extensions can set up additional ui members, |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
191 update configuration by ``ui.setconfig()``, and extend the class dynamically. |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
192 |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
193 Typically there are three ``ui`` instances involved in command execution: |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
194 |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
195 ``req.ui`` (or ``repo.baseui``) |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
196 Only system and user configurations are loaded into it. |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
197 ``lui`` |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
198 Local repository configuration is loaded as well. This will be used at |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
199 early dispatching stage where a repository isn't available. |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
200 ``repo.ui`` |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
201 The fully-loaded ``ui`` used after a repository is instantiated. This |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
202 will be created from the ``req.ui`` per repository. |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
203 |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
204 In command server and hgweb, this may be called more than once for the same |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
205 ``ui`` instance. |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
206 |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
207 (New in Mercurial 4.9) |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
208 |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
209 Repository setup |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
210 ---------------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
211 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
212 Extensions can implement an optional callback named ``reposetup``. It is |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
213 called after the main Mercurial repository initialization, and can be used |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
214 to setup any local state the extension might need. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
215 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
216 As other command functions it receives an ``ui`` object and a ``repo`` object |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
217 (no additional parameters for this, though):: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
218 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
219 def reposetup(ui, repo): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
220 #do initialization here. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
221 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
222 It is important to take into account that the ``ui`` object that is received |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
223 by the ``reposetup`` function is not the same as the one received by the |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
224 ``uisetup`` and ``extsetup`` functions. This is particularly important when |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
225 setting up hooks as described in the following section, since not all hooks |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
226 use the same ``ui`` object and hence different hooks must be configured in |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
227 different setup functions. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
228 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
229 Wrapping methods on the ui and repo classes |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
230 ------------------------------------------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
231 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
232 Because extensions can be loaded *per repository*, you should avoid using |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
233 ``extensions.wrapfunction()`` on methods of the ``ui`` and ``repo`` objects. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
234 Instead, create a subclass of the specific class of the instance passed into |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
235 the ``*setup()`` hook; e.g. use ``ui.__class__`` as the base class, then |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
236 reassign your new class to ``ui.__class__`` again. Mercurial will then use |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
237 your updated ``ui`` or ``repo`` instance only for repositories where your |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
238 extension is enabled (or copies thereof, reusing your new class). |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
239 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
240 For example:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
241 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
242 def uisetup(ui): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
243 class echologui(ui.__class__): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
244 def log(self, service, *msg, **opts): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
245 if msg: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
246 self.write('%s: %s\n' % (service, msg[0] % msg[1:])) |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
247 super(echologui, self).log(service, *msg, **opts) |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
248 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
249 ui.__class__ = echologui |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
250 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
251 Configuring Hooks |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
252 ================= |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
253 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
254 Some extensions must use hooks to do their work. These required hooks can |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
255 be configured manually by the user by modifying the ``[hook]`` section of |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
256 their hgrc, but they can also be configured automatically by calling the |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
257 ``ui.setconfig('hooks', ...)`` function in one of the setup functions |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
258 described above. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
259 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
260 The main difference between manually modifying the hooks section in the hgrc |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
261 and using ``ui.setconfig()`` is that when using ``ui.setconfig()`` you have |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
262 access to the actual hook function object, which you can pass directly to |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
263 ``ui.setconfig()``, while when you use the hooks section of the hgrc file |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
264 you must refer to the hook function by using the |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
265 ``python:modulename.functioname`` idiom (e.g. ``python:hgext.notify.hook``). |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
266 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
267 For example:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
268 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
269 # Define hooks -- note that the actual function name it irrelevant. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
270 def preupdatehook(ui, repo, **kwargs): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
271 ui.write("Pre-update hook triggered\n") |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
272 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
273 def updatehook(ui, repo, **kwargs): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
274 ui.write("Update hook triggered\n") |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
275 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
276 def uisetup(ui): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
277 # When pre-<cmd> and post-<cmd> hooks are configured by means of |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
278 # the ui.setconfig() function, you must use the ui object passed |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
279 # to uisetup or extsetup. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
280 ui.setconfig("hooks", "pre-update.myextension", preupdatehook) |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
281 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
282 def reposetup(ui, repo): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
283 # Repository-specific hooks can be configured here. These include |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
284 # the update hook. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
285 ui.setconfig("hooks", "update.myextension", updatehook) |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
286 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
287 Note how different hooks may need to be configured in different setup |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
288 functions. In the example you can see that the ``update`` hook must be |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
289 configured in the ``reposetup`` function, while the ``pre-update`` hook |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
290 must be configured on the ``uisetup`` or the ``extsetup`` functions. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
291 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
292 Marking compatible versions |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
293 =========================== |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
294 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
295 Every extension should use the ``testedwith`` variable to specify Mercurial |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
296 releases it's known to be compatible with. This helps us and users diagnose |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
297 where problems are coming from:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
298 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
299 testedwith = '2.0 2.0.1 2.1 2.1.1 2.1.2' |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
300 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
301 Do not use the ``internal`` marker in third-party extensions; we will |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
302 immediately drop all bug reports mentioning your extension if we catch you |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
303 doing this. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
304 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
305 Similarly, an extension can use the ``buglink`` variable to specify how users |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
306 should report issues with the extension. This link will be included in the |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
307 error message if the extension produces errors:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
308 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
309 buglink = 'https://bitbucket.org/USER/REPO/issues' |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
310 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
311 Wrap up: what belongs where? |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
312 ============================ |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
313 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
314 You will find here a list of most common tasks, based on setups from the |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
315 extensions included in Mercurial core. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
316 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
317 uisetup |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
318 ------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
319 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
320 * Changes to ``ui.__class__`` . The ``ui`` object that will be used to run |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
321 the command has not yet been created. Changes made here will affect ``ui`` |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
322 objects created after this, and in particular the ``ui`` that will be passed |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
323 to ``runcommand`` |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
324 * Command wraps (``extensions.wrapcommand``) |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
325 * Changes that need to be visible by other extensions: because initialization |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
326 occurs in phases (all extensions run ``uisetup``, then all run ``extsetup``), |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
327 a change made here will be visible by other extensions during ``extsetup``. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
328 * Monkeypatches or function wraps (``extensions.wrapfunction``) of ``dispatch`` |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
329 module members |
40729
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
330 * Set up ``pre-*`` and ``post-*`` hooks. (DEPRECATED. ``uipopulate`` is |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
331 preferred on Mercurial 4.9 and later.) |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
332 * ``pushkey`` setup |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
333 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
334 extsetup |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
335 -------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
336 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
337 * Changes depending on the status of other extensions. (``if extensions.find('mq')``) |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
338 * Add a global option to all commands |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
339 * Extend revsets |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
340 |
40729
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
341 uipopulate |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
342 ---------- |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
343 |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
344 * Modify ``ui`` instance attributes and configuration variables. |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
345 * Changes to ``ui.__class__`` per instance. |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
346 * Set up all hooks per scoped configuration. |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
347 |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
348 reposetup |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
349 --------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
350 |
40729
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
351 * Set up all hooks but ``pre-*`` and ``post-*``. (DEPRECATED. ``uipopulate`` is |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
352 preferred on Mercurial 4.9 and later.) |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
353 * Modify configuration variables |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
354 * Changes to ``repo.__class__``, ``repo.dirstate.__class__`` |