The Mercurial API

Using this API is a strong indication that you're creating a "derived work" subject to the GPL. Before going any further, read the License page.

The Mercurial API is intended primarily for internal use and creation of extensions and is subject to change at any time. See the API_Changes page for details.

This page documents the Mercurial API as of version 1.1.

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.

Commands which fail will raise a mercurial.util.Abort exception, with a message describing the problem:

    from mercurial import util
    raise util.Abort("The repository is not local")

Generally, however, you should not use this interface, as it mixes user interface and functionality. If you want to write robust code, you should read the source of the command function, and extract the relevant details. For most commands, this is not as hard as it seems - there is often a "core" function (usually in the cmdutil or hg module) which performs the important work of the command.

2. Setting up repository and UI objects

In order to get started, you'll often need a UI and a repository object. The UI object keeps access to input and output objects and all the relevant config bits (machine-global, user-global, repo-wide, and specific for this invocation), the repository represents, well, the repository. A repository object can be any of a number of objects (as enumerated below), but these two lines make it easy to create an appropriate repository object:

    from mercurial import ui, hg
    repo = hg.repository(ui.ui(), '.')

Here, the '.' is the path to the repository, which could also be something starting with http or ssh, for example. You'll often need these objects to get any work done through the Mercurial API, for example by using the commands as detailed above.

3. 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.

Writing output:

• ui.write(*msg) - write a message to the standard output (the message arguments are concatenated). This should only be used if you really want to give the user no way of suppressing the output. ui.status (below) is usually better.

• ui.status(*msg) - write a message at status level (shown unless --quiet is specified)

• ui.note(*msg) - write a message at note level (shown if --verbose is specified)

• ui.debug(*msg) - write a message at debug level (shown if --debug is specified)

• ui.warn(*msg) - write a warning message to the error stream

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

Accepting input:

• ui.prompt(msg, default="y") - prompt the user with MSG and read the response. If we are not in an interactive context, just return DEFAULT.

• ui.promptchoice(msg, choices, default=0) - prompt the user with MSG and ensure it matches one of the CHOICES. CHOICES is a secuence with the format ((&None), (E&xec)). The index of the choice is returned. 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.

Useful values:

• 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.

3.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.

3.2. Reading configuration files

All relevant configuration values should be represented in the UI object -- that is, global configuration (/etc/mercurial/hgrc), user configuration (~/.hgrc) and repository configuration (.hg/hgrc). You can easily read from these using the following methods on the ui object:

• ui.config(section, name, default=None, untrusted=False) - gets a configuration value, or a default value if none is specified

• ui.configbool(section, name, default=False, untrusted=False) - convert a config value to boolean (Mercurial accepts several different spellings, like True, false and 0)

• ui.configlist(section, name, default=None, untrusted=False) - try to make a list from the requested config value. The elements are separated by comma or whitespace.

• ui.configitems(section, untrusted=False) - return all configuration values in the given section

4. Repositories

There are a number of different repository types, each defined with its own class name, in its own module. All repository types are subclasses of mercurial.repo.repository.

Repository objects should be created using module.instance(ui, path, create) where path is an appropriate path/URL to the repository, and create should be True if a new repository is to be created. You can also use the helper method hg.repository(), which selects the appropriate repository class based on the path or URL passed.

Repositories have many methods and attributes, but not all repository types support all of the various options.

Some key methods of (local) repositories:

• repo[changeid] - a change context for the changeset changeid. changid can be a descriptor like changeset hash, revision number, 'tip', '.', branch names, tags or anything that can be resolved to a changeset hash.

• repo[None] - a change context for the working directory (works with hg 1.1+)

• repo.changelog - the repository changelog

• repo.root - the path of the repository root

• repo.status() - returns a tuple of files modified, added, removed, deleted, unknown(?), ignored and clean in the current working directory

TODO: Add more details here.

5. Change Contexts

A change context is an object which provides convenient access to various data related to a particular changeset. Change contexts can be converted to a string (for printing, etc - the string representation is the short ID), tested for truth value (false is the null revision), compared for equality, and used as keys in a dictionary. They act as containers for filenames - all of the following work:

• filename in changectx - tests if the file is in the changeset

• changectx[filename] - returns the file context

• for filename in changectx - loops over all files in the changeset (in sorted order)

Some informational methods on change context objects:

• ctx.rev() - the revision number

• ctx.node() - the revision ID

• ctx.user() - the user who created the changeset

• ctx.date() - the date of the changeset

• ctx.files() - the files changed in the changeset

• ctx.description() - the changeset log message

• ctx.branch() - the branch of the changeset

• ctx.tags() - a list of the tags applied to the changeset

• ctx.parents() - a list of the change context objects for the changeset's parents

• ctx.children() - a list of the change context objects for the changeset's children

• ctx.filectx(path) - get a filecontext, the same as ctx[path]

• ctx.ancestor(c2) - the common ancestor change context of ctx and c2

6. File Contexts

A file context is an object which provides convenient access to various data related to a particular file revision. File contexts can be converted to a string (for printing, etc - the string representation is the "path@shortID"), tested for truth value (False is "nonexistent"), compared for equality, and used as keys in a dictionary.

Some informational methods on file context objects:

• fctx.filectx(id) - the file context for another revision of the file

• fctx.filerev() - the revision at which this file was last changed

• fctx.filenode() - the file ID

• fctx.fileflags() - the file flags

• fctx.isexec() - is the file executable

• fctx.islink() - is the file a symbolic link

• fctx.filelog() - the file log for the file revision (file logs are not documented here - see the source)

• fctx.rev() - the revision from which this file context was extracted

• fctx.changectx() - the change context associated with this file revision

• fctx.node, fctx.user, fctx.date, fctx.files, fctx.description, fctx.branch, fctx.manifest - the same as the equivalent change context methods, applied to the change context associated with the file revision.

• fctx.data() - the file data

• fctx.path() - the file path

• fctx.size() - the file size

• fctx.cmp(data) - does the file contents match data?

• fctx.annotate(follow=False, linenumber=None) - list of tuples of (ctx, line) for each line in the file, where ctx is the file context of the node where that line was last changed. (The follow and linenumber parameters are not documented here - see the source for details).

7. Revlogs

Revlogs are the storage backend for Mercurial. They are not fully documented here, as it is unlikely that extension code will require detailed access to revlogs. However, a couple of key methods which may be generally useful are:

• len(log) - the number of revisions in the changelog

• log.tip() - the ID of the tip revision

The debugshell extension can be used to access the api in a python shell.

CategoryInternals