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.

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.

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")

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.

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

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.

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.

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

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

Some key methods of (local) repositories:

• repo.changectx(changeid) - a change context in the repository

• repo.changelog - the repository changelog

• repo.root - the path of the repository root

TODO: Add more details here.

4. 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.filectxs() - yield each filecontext in turn, the same as iter(ctx)

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

5. 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).

6. Changelogs

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

• cl.count() - the number of revisions in the changelog

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