Mercurial > hg
comparison mercurial/helptext/internals/extensions.txt @ 45931:f177fcd9cb96
helptext: byteify extensions examples
Make it easier on the copy/paste crowd. I haven't looked at the other help text
to see if there are other instances; I was just looking to confirm `buglink` is
meant to be bytes and this popped up along with the code.
Differential Revision: https://phab.mercurial-scm.org/D9367
author | Matt Harbison <matt_harbison@yahoo.com> |
---|---|
date | Sun, 22 Nov 2020 14:55:40 -0500 |
parents | cb728894f91d |
children | bc1b4eb21da9 |
comparison
equal
deleted
inserted
replaced
45930:cb728894f91d | 45931:f177fcd9cb96 |
---|---|
22 Command table | 22 Command table |
23 ============= | 23 ============= |
24 | 24 |
25 To write your own extension, your python module can provide an optional dict | 25 To write your own extension, your python module can provide an optional dict |
26 named ``cmdtable`` with entries describing each command. A command should be | 26 named ``cmdtable`` with entries describing each command. A command should be |
27 registered to the ``cmdtable`` by ``@command`` decorator. | 27 registered to the ``cmdtable`` by ``@command`` decorator. All string-like |
28 values must be the ``bytes`` type, and are thus prefixed with ``b``. | |
28 | 29 |
29 Example using ``@command`` decorator (requires Mercurial 1.9):: | 30 Example using ``@command`` decorator (requires Mercurial 1.9):: |
30 | 31 |
31 from mercurial.i18n import _ | 32 from mercurial.i18n import _ |
32 | 33 |
37 except (AttributeError, ImportError): | 38 except (AttributeError, ImportError): |
38 # Fallback to hg < 4.3 support | 39 # Fallback to hg < 4.3 support |
39 from mercurial import cmdutil | 40 from mercurial import cmdutil |
40 command = cmdutil.command(cmdtable) | 41 command = cmdutil.command(cmdtable) |
41 | 42 |
42 @command('print-parents', | 43 @command(b'print-parents', |
43 [('s', 'short', None, _('print short form')), | 44 [(b's', b'short', None, _(b'print short form')), |
44 ('l', 'long', None, _('print long form'))], | 45 (b'l', b'long', None, _(b'print long form'))], |
45 _('[options] node')) | 46 _(b'[options] node')) |
46 def printparents(ui, repo, node, **opts): | 47 def printparents(ui, repo, node, **opts): |
47 ... | 48 ... |
48 | 49 |
49 The cmdtable dictionary | 50 The cmdtable dictionary |
50 ----------------------- | 51 ----------------------- |
82 | 83 |
83 If there is no repo to be associated with the command and consequently no | 84 If there is no repo to be associated with the command and consequently no |
84 ``repo`` passed, then ``norepo=True`` should be passed to the ``@command`` | 85 ``repo`` passed, then ``norepo=True`` should be passed to the ``@command`` |
85 decorator:: | 86 decorator:: |
86 | 87 |
87 @command('mycommand', [], norepo=True) | 88 @command(b'mycommand', [], norepo=True) |
88 def mycommand(ui, **opts): | 89 def mycommand(ui, **opts): |
89 ... | 90 ... |
90 | 91 |
91 For examples of ``norepo``, see the convert extension. | 92 For examples of ``norepo``, see the convert extension. |
92 | 93 |
138 | 139 |
139 Communicating with the user | 140 Communicating with the user |
140 =========================== | 141 =========================== |
141 | 142 |
142 Besides the ``ui`` methods, like ``ui.write(*msg)`` or | 143 Besides the ``ui`` methods, like ``ui.write(*msg)`` or |
143 ``ui.prompt(msg, default="y")``, an extension can add help text for each | 144 ``ui.prompt(msg, default=b"y")``, an extension can add help text for each |
144 of its commands and the extension itself. | 145 of its commands and the extension itself. |
145 | 146 |
146 The module docstring will be used as help string when ``hg help extensionname`` | 147 The module docstring will be used as help string when ``hg help extensionname`` |
147 is used and, similarly, the help string for a command and the docstring | 148 is used and, similarly, the help string for a command and the docstring |
148 belonging to the function that's wrapped by the command will be shown when | 149 belonging to the function that's wrapped by the command will be shown when |
246 | 247 |
247 def uisetup(ui): | 248 def uisetup(ui): |
248 class echologui(ui.__class__): | 249 class echologui(ui.__class__): |
249 def log(self, service, *msg, **opts): | 250 def log(self, service, *msg, **opts): |
250 if msg: | 251 if msg: |
251 self.write('%s: %s\n' % (service, msg[0] % msg[1:])) | 252 self.write(b'%s: %s\n' % (service, msg[0] % msg[1:])) |
252 super(echologui, self).log(service, *msg, **opts) | 253 super(echologui, self).log(service, *msg, **opts) |
253 | 254 |
254 ui.__class__ = echologui | 255 ui.__class__ = echologui |
255 | 256 |
256 Configuring Hooks | 257 Configuring Hooks |
257 ================= | 258 ================= |
258 | 259 |
259 Some extensions must use hooks to do their work. These required hooks can | 260 Some extensions must use hooks to do their work. These required hooks can |
260 be configured manually by the user by modifying the ``[hook]`` section of | 261 be configured manually by the user by modifying the ``[hook]`` section of |
261 their hgrc, but they can also be configured automatically by calling the | 262 their hgrc, but they can also be configured automatically by calling the |
262 ``ui.setconfig('hooks', ...)`` function in one of the setup functions | 263 ``ui.setconfig(b'hooks', ...)`` function in one of the setup functions |
263 described above. | 264 described above. |
264 | 265 |
265 The main difference between manually modifying the hooks section in the hgrc | 266 The main difference between manually modifying the hooks section in the hgrc |
266 and using ``ui.setconfig()`` is that when using ``ui.setconfig()`` you have | 267 and using ``ui.setconfig()`` is that when using ``ui.setconfig()`` you have |
267 access to the actual hook function object, which you can pass directly to | 268 access to the actual hook function object, which you can pass directly to |
271 | 272 |
272 For example:: | 273 For example:: |
273 | 274 |
274 # Define hooks -- note that the actual function name it irrelevant. | 275 # Define hooks -- note that the actual function name it irrelevant. |
275 def preupdatehook(ui, repo, **kwargs): | 276 def preupdatehook(ui, repo, **kwargs): |
276 ui.write("Pre-update hook triggered\n") | 277 ui.write(b"Pre-update hook triggered\n") |
277 | 278 |
278 def updatehook(ui, repo, **kwargs): | 279 def updatehook(ui, repo, **kwargs): |
279 ui.write("Update hook triggered\n") | 280 ui.write(b"Update hook triggered\n") |
280 | 281 |
281 def uisetup(ui): | 282 def uisetup(ui): |
282 # When pre-<cmd> and post-<cmd> hooks are configured by means of | 283 # When pre-<cmd> and post-<cmd> hooks are configured by means of |
283 # the ui.setconfig() function, you must use the ui object passed | 284 # the ui.setconfig() function, you must use the ui object passed |
284 # to uisetup or extsetup. | 285 # to uisetup or extsetup. |
285 ui.setconfig("hooks", "pre-update.myextension", preupdatehook) | 286 ui.setconfig(b"hooks", b"pre-update.myextension", preupdatehook) |
286 | 287 |
287 def reposetup(ui, repo): | 288 def reposetup(ui, repo): |
288 # Repository-specific hooks can be configured here. These include | 289 # Repository-specific hooks can be configured here. These include |
289 # the update hook. | 290 # the update hook. |
290 ui.setconfig("hooks", "update.myextension", updatehook) | 291 ui.setconfig(b"hooks", b"update.myextension", updatehook) |
291 | 292 |
292 Note how different hooks may need to be configured in different setup | 293 Note how different hooks may need to be configured in different setup |
293 functions. In the example you can see that the ``update`` hook must be | 294 functions. In the example you can see that the ``update`` hook must be |
294 configured in the ``reposetup`` function, while the ``pre-update`` hook | 295 configured in the ``reposetup`` function, while the ``pre-update`` hook |
295 must be configured on the ``uisetup`` or the ``extsetup`` functions. | 296 must be configured on the ``uisetup`` or the ``extsetup`` functions. |
299 | 300 |
300 Every extension should use the ``testedwith`` variable to specify Mercurial | 301 Every extension should use the ``testedwith`` variable to specify Mercurial |
301 releases it's known to be compatible with. This helps us and users diagnose | 302 releases it's known to be compatible with. This helps us and users diagnose |
302 where problems are coming from:: | 303 where problems are coming from:: |
303 | 304 |
304 testedwith = '2.0 2.0.1 2.1 2.1.1 2.1.2' | 305 testedwith = b'2.0 2.0.1 2.1 2.1.1 2.1.2' |
305 | 306 |
306 Do not use the ``internal`` marker in third-party extensions; we will | 307 Do not use the ``internal`` marker in third-party extensions; we will |
307 immediately drop all bug reports mentioning your extension if we catch you | 308 immediately drop all bug reports mentioning your extension if we catch you |
308 doing this. | 309 doing this. |
309 | 310 |
310 Similarly, an extension can use the ``buglink`` variable to specify how users | 311 Similarly, an extension can use the ``buglink`` variable to specify how users |
311 should report issues with the extension. This link will be included in the | 312 should report issues with the extension. This link will be included in the |
312 error message if the extension produces errors:: | 313 error message if the extension produces errors:: |
313 | 314 |
314 buglink = 'https://bitbucket.org/USER/REPO/issues' | 315 buglink = b'https://bitbucket.org/USER/REPO/issues' |
315 | 316 |
316 If an extension requires a minimum version of Mercurial, it can be declared | 317 If an extension requires a minimum version of Mercurial, it can be declared |
317 with the ``minimumhgversion`` variable:: | 318 with the ``minimumhgversion`` variable:: |
318 | 319 |
319 minimumhgversion = '4.6' | 320 minimumhgversion = b'4.6' |
320 | 321 |
321 Older clients will print a warning that the extension requires a new version, | 322 Older clients will print a warning that the extension requires a new version, |
322 instead of attempting to load it. | 323 instead of attempting to load it. |
323 | 324 |
324 Wrap up: what belongs where? | 325 Wrap up: what belongs where? |
345 * ``pushkey`` setup | 346 * ``pushkey`` setup |
346 | 347 |
347 extsetup | 348 extsetup |
348 -------- | 349 -------- |
349 | 350 |
350 * Changes depending on the status of other extensions. (``if extensions.find('mq')``) | 351 * Changes depending on the status of other extensions. (``if extensions.find(b'mq')``) |
351 * Add a global option to all commands | 352 * Add a global option to all commands |
352 * Extend revsets | 353 * Extend revsets |
353 | 354 |
354 uipopulate | 355 uipopulate |
355 ---------- | 356 ---------- |