Mercurial > hg
annotate mercurial/helptext/internals/extensions.txt @ 45960:bc1b4eb21da9
helptext: document the mechanism for extensions to report a version
Differential Revision: https://phab.mercurial-scm.org/D9448
author | Matt Harbison <matt_harbison@yahoo.com> |
---|---|
date | Sat, 28 Nov 2020 00:25:04 -0500 |
parents | f177fcd9cb96 |
children |
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 |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
27 registered to the ``cmdtable`` by ``@command`` decorator. All string-like |
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
28 values must be the ``bytes`` type, and are thus prefixed with ``b``. |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
29 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
30 Example using ``@command`` decorator (requires Mercurial 1.9):: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
31 |
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 = {} |
41293
86f6b441adea
help: modernize the example for command registration
Matt Harbison <matt_harbison@yahoo.com>
parents:
40729
diff
changeset
|
35 try: |
86f6b441adea
help: modernize the example for command registration
Matt Harbison <matt_harbison@yahoo.com>
parents:
40729
diff
changeset
|
36 from mercurial import registrar |
86f6b441adea
help: modernize the example for command registration
Matt Harbison <matt_harbison@yahoo.com>
parents:
40729
diff
changeset
|
37 command = registrar.command(cmdtable) |
86f6b441adea
help: modernize the example for command registration
Matt Harbison <matt_harbison@yahoo.com>
parents:
40729
diff
changeset
|
38 except (AttributeError, ImportError): |
86f6b441adea
help: modernize the example for command registration
Matt Harbison <matt_harbison@yahoo.com>
parents:
40729
diff
changeset
|
39 # Fallback to hg < 4.3 support |
86f6b441adea
help: modernize the example for command registration
Matt Harbison <matt_harbison@yahoo.com>
parents:
40729
diff
changeset
|
40 from mercurial import cmdutil |
86f6b441adea
help: modernize the example for command registration
Matt Harbison <matt_harbison@yahoo.com>
parents:
40729
diff
changeset
|
41 command = cmdutil.command(cmdtable) |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
42 |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
43 @command(b'print-parents', |
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
44 [(b's', b'short', None, _(b'print short form')), |
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
45 (b'l', b'long', None, _(b'print long form'))], |
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
46 _(b'[options] node')) |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
47 def printparents(ui, repo, node, **opts): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
48 ... |
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 The cmdtable dictionary |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
51 ----------------------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
52 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
53 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
|
54 a tuple containing: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
55 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
56 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
|
57 2. a list of options the command can take. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
58 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
|
59 the full help). |
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 List of options |
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 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
64 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
|
65 sources. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
66 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
67 The options list is a list of tuples containing: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
68 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
69 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
|
70 (for example, ``o`` for a ``-o`` option). |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
71 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
|
72 3. a default value for the option. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
73 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
|
74 part and only the options and parameter substring is needed). |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
75 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
76 Command function signatures |
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 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
79 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
|
80 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
|
81 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
|
82 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
|
83 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
84 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
|
85 ``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
|
86 decorator:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
87 |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
88 @command(b'mycommand', [], norepo=True) |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
89 def mycommand(ui, **opts): |
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 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
92 For examples of ``norepo``, see the convert extension. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
93 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
94 Command function docstrings |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
95 =========================== |
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 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
|
98 ``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
|
99 subset of reStructuredText markup. The supported constructs include: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
100 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
101 Paragraphs:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
102 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
103 This is a paragraph. |
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 Paragraphs are separated |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
106 by blank lines. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
107 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
108 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
|
109 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
|
110 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
111 Some text:: |
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 verbatim |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
114 text |
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 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
117 We have field lists:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
118 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
119 :key1: value1 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
120 :key2: value2 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
121 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
122 Bullet lists:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
123 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
124 - foo |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
125 - bar |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
126 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
127 Enumerated lists:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
128 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
129 1. foo |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
130 2. bar |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
131 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
132 Inline markup:: |
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 ``*bold*``, ``monospace``, :hg:`command` |
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 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
|
137 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
|
138 without too much trouble. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
139 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
140 Communicating with the user |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
141 =========================== |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
142 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
143 Besides the ``ui`` methods, like ``ui.write(*msg)`` or |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
144 ``ui.prompt(msg, default=b"y")``, an extension can add help text for each |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
145 of its commands and the extension itself. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
146 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
147 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
|
148 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
|
149 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
|
150 ``hg help command`` is invoked. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
151 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
152 Setup Callbacks |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
153 =============== |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
154 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
155 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
|
156 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
|
157 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
|
158 extensions with ``extensions.find`` in the following phases. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
159 |
40596
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
160 Extension setup |
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
161 --------------- |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
162 |
40596
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
163 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
|
164 ``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
|
165 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
|
166 one extension optionally depends on another extension. |
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
167 |
40597
04d08f17ce7a
help: document weird behavior of uisetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40596
diff
changeset
|
168 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
|
169 repository configuration:: |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
170 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
171 def uisetup(ui): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
172 # ... |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
173 |
40596
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
174 def extsetup(ui): |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
175 # ... |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
176 |
40597
04d08f17ce7a
help: document weird behavior of uisetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40596
diff
changeset
|
177 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
|
178 It's called only once per process, not per ``ui`` instance. Also, any changes |
45930
cb728894f91d
helptext: fix sentence in extensions documentation
Matt Harbison <matt_harbison@yahoo.com>
parents:
43632
diff
changeset
|
179 to the ``ui`` may be discarded because the ``ui`` here is a temporarily loaded |
40597
04d08f17ce7a
help: document weird behavior of uisetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40596
diff
changeset
|
180 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
|
181 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
|
182 and extending ``ui.__class__``. |
04d08f17ce7a
help: document weird behavior of uisetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40596
diff
changeset
|
183 |
40596
252396a6a3f2
help: merge section about uisetup() and extsetup()
Yuya Nishihara <yuya@tcha.org>
parents:
40595
diff
changeset
|
184 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
|
185 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
186 Command table setup |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
187 ------------------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
188 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
189 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
|
190 in Mercurial. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
191 |
40729
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
192 Ui instance setup |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
193 ----------------- |
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 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
|
196 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
|
197 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
|
198 |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
199 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
|
200 |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
201 ``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
|
202 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
|
203 ``lui`` |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
204 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
|
205 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
|
206 ``repo.ui`` |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
207 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
|
208 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
|
209 |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
210 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
|
211 ``ui`` instance. |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
212 |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
213 (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
|
214 |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
215 Repository setup |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
216 ---------------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
217 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
218 Extensions can implement an optional callback named ``reposetup``. It is |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
219 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
|
220 to setup any local state the extension might need. |
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 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
|
223 (no additional parameters for this, though):: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
224 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
225 def reposetup(ui, repo): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
226 #do initialization here. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
227 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
228 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
|
229 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
|
230 ``uisetup`` and ``extsetup`` functions. This is particularly important when |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
231 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
|
232 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
|
233 different setup functions. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
234 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
235 Wrapping methods on the ui and repo classes |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
236 ------------------------------------------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
237 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
238 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
|
239 ``extensions.wrapfunction()`` on methods of the ``ui`` and ``repo`` objects. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
240 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
|
241 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
|
242 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
|
243 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
|
244 extension is enabled (or copies thereof, reusing your new class). |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
245 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
246 For example:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
247 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
248 def uisetup(ui): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
249 class echologui(ui.__class__): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
250 def log(self, service, *msg, **opts): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
251 if msg: |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
252 self.write(b'%s: %s\n' % (service, msg[0] % msg[1:])) |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
253 super(echologui, self).log(service, *msg, **opts) |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
254 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
255 ui.__class__ = echologui |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
256 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
257 Configuring Hooks |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
258 ================= |
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 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
|
261 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
|
262 their hgrc, but they can also be configured automatically by calling the |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
263 ``ui.setconfig(b'hooks', ...)`` function in one of the setup functions |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
264 described above. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
265 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
266 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
|
267 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
|
268 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
|
269 ``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
|
270 you must refer to the hook function by using the |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
271 ``python:modulename.functioname`` idiom (e.g. ``python:hgext.notify.hook``). |
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 For example:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
274 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
275 # Define hooks -- note that the actual function name it irrelevant. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
276 def preupdatehook(ui, repo, **kwargs): |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
277 ui.write(b"Pre-update hook triggered\n") |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
278 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
279 def updatehook(ui, repo, **kwargs): |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
280 ui.write(b"Update hook triggered\n") |
40595
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 uisetup(ui): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
283 # 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
|
284 # 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
|
285 # to uisetup or extsetup. |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
286 ui.setconfig(b"hooks", b"pre-update.myextension", preupdatehook) |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
287 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
288 def reposetup(ui, repo): |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
289 # Repository-specific hooks can be configured here. These include |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
290 # the update hook. |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
291 ui.setconfig(b"hooks", b"update.myextension", updatehook) |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
292 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
293 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
|
294 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
|
295 configured in the ``reposetup`` function, while the ``pre-update`` hook |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
296 must be configured on the ``uisetup`` or the ``extsetup`` functions. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
297 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
298 Marking compatible versions |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
299 =========================== |
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 Every extension should use the ``testedwith`` variable to specify Mercurial |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
302 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
|
303 where problems are coming from:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
304 |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
305 testedwith = b'2.0 2.0.1 2.1 2.1.1 2.1.2' |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
306 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
307 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
|
308 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
|
309 doing this. |
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 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
|
312 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
|
313 error message if the extension produces errors:: |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
314 |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
315 buglink = b'https://bitbucket.org/USER/REPO/issues' |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
316 |
41294
b5d7413e4009
help: document the minimumhgversion variable for extensions
Matt Harbison <matt_harbison@yahoo.com>
parents:
41293
diff
changeset
|
317 If an extension requires a minimum version of Mercurial, it can be declared |
b5d7413e4009
help: document the minimumhgversion variable for extensions
Matt Harbison <matt_harbison@yahoo.com>
parents:
41293
diff
changeset
|
318 with the ``minimumhgversion`` variable:: |
b5d7413e4009
help: document the minimumhgversion variable for extensions
Matt Harbison <matt_harbison@yahoo.com>
parents:
41293
diff
changeset
|
319 |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
320 minimumhgversion = b'4.6' |
41294
b5d7413e4009
help: document the minimumhgversion variable for extensions
Matt Harbison <matt_harbison@yahoo.com>
parents:
41293
diff
changeset
|
321 |
b5d7413e4009
help: document the minimumhgversion variable for extensions
Matt Harbison <matt_harbison@yahoo.com>
parents:
41293
diff
changeset
|
322 Older clients will print a warning that the extension requires a new version, |
b5d7413e4009
help: document the minimumhgversion variable for extensions
Matt Harbison <matt_harbison@yahoo.com>
parents:
41293
diff
changeset
|
323 instead of attempting to load it. |
b5d7413e4009
help: document the minimumhgversion variable for extensions
Matt Harbison <matt_harbison@yahoo.com>
parents:
41293
diff
changeset
|
324 |
45960
bc1b4eb21da9
helptext: document the mechanism for extensions to report a version
Matt Harbison <matt_harbison@yahoo.com>
parents:
45931
diff
changeset
|
325 The extension itself can be assigned a version value through one of two module |
bc1b4eb21da9
helptext: document the mechanism for extensions to report a version
Matt Harbison <matt_harbison@yahoo.com>
parents:
45931
diff
changeset
|
326 attributes, and will be displayed in crash reports and :hg:`version -v`:: |
bc1b4eb21da9
helptext: document the mechanism for extensions to report a version
Matt Harbison <matt_harbison@yahoo.com>
parents:
45931
diff
changeset
|
327 |
bc1b4eb21da9
helptext: document the mechanism for extensions to report a version
Matt Harbison <matt_harbison@yahoo.com>
parents:
45931
diff
changeset
|
328 * ``__version__`` is a plain value |
bc1b4eb21da9
helptext: document the mechanism for extensions to report a version
Matt Harbison <matt_harbison@yahoo.com>
parents:
45931
diff
changeset
|
329 * ``getversion`` is a no argument ``Callable`` that returns a value |
bc1b4eb21da9
helptext: document the mechanism for extensions to report a version
Matt Harbison <matt_harbison@yahoo.com>
parents:
45931
diff
changeset
|
330 |
bc1b4eb21da9
helptext: document the mechanism for extensions to report a version
Matt Harbison <matt_harbison@yahoo.com>
parents:
45931
diff
changeset
|
331 In both cases, the value must be either a byte string, or a list or tuple of |
bc1b4eb21da9
helptext: document the mechanism for extensions to report a version
Matt Harbison <matt_harbison@yahoo.com>
parents:
45931
diff
changeset
|
332 numeric values which will be joined with ``.``. |
bc1b4eb21da9
helptext: document the mechanism for extensions to report a version
Matt Harbison <matt_harbison@yahoo.com>
parents:
45931
diff
changeset
|
333 |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
334 Wrap up: what belongs where? |
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 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
|
338 extensions included in Mercurial core. |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
339 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
340 uisetup |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
341 ------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
342 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
343 * 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
|
344 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
|
345 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
|
346 to ``runcommand`` |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
347 * Command wraps (``extensions.wrapcommand``) |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
348 * 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
|
349 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
|
350 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
|
351 * Monkeypatches or function wraps (``extensions.wrapfunction``) of ``dispatch`` |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
352 module members |
40729
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
353 * 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
|
354 preferred on Mercurial 4.9 and later.) |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
355 * ``pushkey`` setup |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
356 |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
357 extsetup |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
358 -------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
359 |
45931
f177fcd9cb96
helptext: byteify extensions examples
Matt Harbison <matt_harbison@yahoo.com>
parents:
45930
diff
changeset
|
360 * Changes depending on the status of other extensions. (``if extensions.find(b'mq')``) |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
361 * Add a global option to all commands |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
362 * Extend revsets |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
363 |
40729
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
364 uipopulate |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
365 ---------- |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
366 |
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
367 * 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
|
368 * 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
|
369 * 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
|
370 |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
371 reposetup |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
372 --------- |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
373 |
40729
c93d046d4300
extensions: add "uipopulate" hook, called per instance, not per process
Yuya Nishihara <yuya@tcha.org>
parents:
40597
diff
changeset
|
374 * 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
|
375 preferred on Mercurial 4.9 and later.) |
40595
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
376 * Modify configuration variables |
419d703115b0
help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents:
diff
changeset
|
377 * Changes to ``repo.__class__``, ``repo.dirstate.__class__`` |