Diff for "WritingExtensions"

Mercurial features an extension mechanism for adding new commands. It allows you to create new features and use them directly from the main hg command line.

Existing extensions

The following extensions are distributed with Mercurial.

1. gpg

Extension for signing and checking signatures.

2. bisect

Extension for binary searching in O(log2(n)) for the changeset introducing a (mis)feature.

3. mq

Mercurial Queue management extension - see MqExtension.

4. patchbomb

Extension providing the hg email command for sending a collection of Mercurial changesets as a series of patch emails.

5. win32text

Extension for line ending conversion filters for the Windows platform.

Enabling an extension

To load an extension, you add it to the "extensions" section of your [http://www.selenic.com/mercurial/hgrc.5.html .hgrc] file.

Mercurial vil scan the default python library path for a file named hgk.py if you set hgk empty:

[extensions]
hgk=

Extensions are usually located in the hgext directory, in which case you can load them like:

[extensions]
hgext.patchbomb=

You can also specify an absolute path:

[extensions]
hgk=/usr/local/lib/hgk.py

Extensions can often be configured further in an extension specific section in the same configuration file.

Writing your own extension

To write your own extension, your python module can provide an optional dict named cmdtable with entries describing each command, and an optional callback named reposetup. The reposetup callback is called after the main Mercurial repository initialization, and can be used to setup any local state the extension might need. Below is an example extension to help demonstrate how things work:

   1 #!/usr/bin/env python
   2 
   3 from mercurial import hg
   4 
   5 # every command must take a ui and and repo as arguments.
   6 # opts is a dict where you can find other command line flags
   7 #
   8 # Other parameters are taken in order from items on the command line that
   9 # don't start with a dash.  If no default value is given in the parameter list,
  10 # they are required.
  11 def print_parents(ui, repo, node, **opts):
  12     # The doc string below will show up in hg help
  13     """Print parent information"""
  14 
  15     # repo.lookup can lookup based on tags, an sha1, or a revision number
  16     node = repo.lookup(node)
  17     parents = repo.changelog.parents(node)
  18 
  19     if opts['short']:
  20         # hg.short will return a smaller portion of the sha1
  21         print "short %s %s" % (hg.short(parents[0]), hg.short(parents[1]))
  22     elif opts['long']:
  23         # hg.hex will return the full sha1
  24         print "long %s %s" % (hg.hex(parents[0]), hg.hex(parents[1]))
  25     else:
  26         print "default %s %s" % (hg.short(parents[0]), hg.short(parents[1]))
  27 
  28 cmdtable = {
  29     # cmd name        function call
  30     "print-parents": (print_parents,
  31                      # see mercurial/fancyopts.py for all of the command
  32                      # flag options.
  33                      [('s', 'short', None, 'print short form'),
  34                       ('l', 'long', None, 'print long form')],
  35                      "hg print-parents [options] node")
  36 }

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.