The Mercurial API

Please note - although this page describes the "public API" of Mercurial, there is no formally documented API. Any function could change, at any time. In practice, however, this will not happen, and the functions here can be considered as reasonably stable.

Also please note - this is the results of some very preliminary investigation, and may very well be wrong! I will update the documentation as I discover additional information, and I would be very grateful if others could correct mistakes where they might occur.

This page documents the Mercurial API as of version 1.0.

1. The High Level Interface

It is possible to call Mercurial commands directly from within your code. Every Mercurial command corresponds to a function defined in the mercurial.commands module, with the calling signature

    CMD(ui, repo, ...)

Here, ui and repo are the user interface and repository arguments passed into an extension function as standard (see WritingExtensions for more details). If you are not calling the Mercurial command functions from an extension, you will need to create suitable ui and repo objects yourself. The ui object can be instantiated from the ui class in mercurial.ui; the repo object can either be a localrepository, a httprepository, an sshrepository or a statichttprepository (each defined in their own modules), though it will most often be a localrepository.

The remainder of the parameters come in two groups:

• a sequence of positional parameters corresponding to the (non-option) command line arguments to the command
• a set of keyword parameters, corresponding to the command options - the key is the option name (long form) and the value is the value given to the option (or True/False if the option does not take an argument).

A reasonably complex example might be hg commit -m "A test" --addremove file1.py file2.py. This would have an equivalent API form

    from mercurial import commands
    commands.commit(ui, repo, 'file1.py', 'file2.py', message="A test", addremove=True)

In practice, some of the options for the commit command are required in a call, and must be included as keyword parameters - adding date=None, user=None, logfile=None would be sufficient in this case. This detail can be ignored for now.

2. Communicating with the User

Most extensions will need to perform some interaction with the user. This is the purpose of the ui parameter to an extension function. The ui parameter is an object with a number of useful methods for interacting with the user.

• ui.debug(*msg) - write a message at debug level

• ui.note(*msg) - write a message at note level

• ui.status(*msg) - write a message at status level

• ui.warn(*msg) - write a message at warning level

• ui.flush() - flush the output and error streams

• ui.prompt(msg, pat=None, default="y") - prompt the user with MSG, read the response and ensure that it matches the regular expression PAT. If we are not in an interactive context, just return DEFAULT.

• ui.getpass(prompt, default=None) - prompt for a password with PROMPT (default is "password: ") and return the result. Input will not be echoed on the screen. If we are not in an interactive context, just return DEFAULT.

• ui.edit(text, user) - open an editor on a file containing TEXT. Return the edited text, with lines starting HG: removed. While the edit is in progress, the HGUSER environment variable is set to USER.

• ui.editor() - the user's preferred editor

• ui.username() - the default username to be used in commits

• ui.shortuser(user) - a short form of user name USER

• ui.expandpath(loc, default=None) - the location of repository LOC (which may be relative to the CWD, or from the [paths] configuration section. If no other value can be found, DEFAULT is returned.

2.1. Collecting Output

Output from a ui object is usually to the standard output, sys.stdout. However, it is possible to "divert" all output and collect it for processing by your code. This involves the ui.pushbuffer and ui.popbuffer functions. At the start of the code whose output you want to collect, call ui.pushbuffer(). Then, when you have finished the code whose output you wish to collect, call ui.popbuffer(). The popbuffer call returns all collected output as a string, for you to process as you wish (and potentially pass to ui.write() in some form, if you just want to edit the output and then send it on.