Writing Mercurial extensions
Mercurial features an extension mechanism for adding new commands.
Extensions allow the creation of new features and using them directly from the main hg command line as if they were builtin commands.
Writing your own extension
File Layout
Extensions are usually written as simple python modules. Larger ones are better split into multiple modules of a single package (see ConvertExtension). The package root module gives its name to the extension and implements the cmdtable and optional callbacks described below.
Command table
To write your own extension, your python module can provide an optional dict named cmdtable with entries describing each command.
The `cmdtable` dictionary
The cmdtable dictionary uses as key the new command names, and, as value, a tuple containing:
- the function name to be called when the command is used.
- a list of options the command can take.
- a help string for the command.
List of options
Al the command flag options are documented in the mercurial/fancyopts.py sources.
The options list is a list of tuples containing:
a flag specifying if the option is of the short or long sort, like -o or --option.
- an option name.
- a default value for the option.
- a help string for the option.
Example `cmdtable`
cmdtable = {
# "command-name": (function-call, options-list, help-string)
"print-parents": (print_parents,
[('s', 'short', None, 'print short form'),
('l', 'long', None, 'print long form')],
"hg print-parents [options] node")
}
Command function signatures
Functions that implement new commands always receive a ui and usually a repo parameter. The rest of parameters are taken from the command line items that don't start with a dash and are passed in the same order they were written. If no default value is given in the parameter list they are required.
If there is no repo to be associated with the command and consequently no repo passed then commands should be imported from mercurial and the extension name should be added to commands.norep like this:
from mercurial import commands ... commands.norepo += " mycommand"
For an example of such an extension see the source code to [http://hg.intevation.org/mercurial/crew/file/f5f6b7dcd217/hgext/convert/__init__.py#l186 convert]
Extension setup
Extensions can implement an optional callback named extsetup. It is called after all the extension are pre-loaded, and can be useful in case one extension optionally depends on another extension.
Signature:
def extsetup():
# ...
Repository setup
Extensions can implement an optional callback named reposetup. It is called after the main Mercurial repository initialization, and can be used to setup any local state the extension might need.
As other command functions it receives an ui object and a repo object (no additional parameters for this, though):
def reposetup(ui, repo):
#do initialization here.
Example extension
1 #!/usr/bin/env python
2
3 from mercurial import hg
4 from mercurial.node import short, hex
5
6 # every command must take a ui and and repo as arguments.
7 # opts is a dict where you can find other command line flags
8 #
9 # Other parameters are taken in order from items on the command line that
10 # don't start with a dash. If no default value is given in the parameter list,
11 # they are required.
12 def print_parents(ui, repo, node, **opts):
13 # The doc string below will show up in hg help
14 """Print parent information"""
15
16 # repo.lookup can lookup based on tags, an sha1, or a revision number
17 node = repo.lookup(node)
18 parents = repo.changelog.parents(node)
19
20 if opts['short']:
21 # mercurial.node.short returns a smaller portion of the sha1
22 print "short %s %s" % (short(parents[0]), short(parents[1]))
23 elif opts['long']:
24 # mercurial.node.hex returns the full sha1
25 print "long %s %s" % (hex(parents[0]), hex(parents[1]))
26 else:
27 print "default %s %s" % (short(parents[0]), short(parents[1]))
28
29 cmdtable = {
30 # cmd name function call
31 "print-parents": (print_parents,
32 # see mercurial/fancyopts.py for all of the command
33 # flag options.
34 [('s', 'short', None, 'print short form'),
35 ('l', 'long', None, 'print long form')],
36 "hg print-parents [options] REV")
37 }
If cmdtable or reposetup is not present, your extension will still work. This means that an extension can work "silently", without making new functionality directly visible through the command line interface.
Where to put extensions in the source tree
As of a change shortly after the 0.7 release, the recommended location for installing extensions in the source tree is the hgext directory. If you put a file in there called foo.py, you will need to refer to it in the hgrc file as a qualified package name, hgext.foo.
The contents of the hgext directory will be installed by the top-level setup.py script along with the rest of Mercurial.
See CategoryExtension for related pages and ["UsingExtensions"] for a list of readily avaliable extensions bundled with Mercurial or provided by third parties.