Mercurial: The Definitive Guide

Information for Writers of Hooks

In-Process Hook Execution

An in-process hook is called with arguments of the following form:

def myhook(ui, repo, **kwargs): pass

The ui parameter is a ui object. The repo parameter is a localrepository object. The names and values of the **kwargs parameters depend on the hook being invoked, with the following common features:

• If a parameter is named node or parentN, it will contain a hexadecimal changeset ID. The empty string is used to represent “null changeset ID” instead of a string of zeros.

• If a parameter is named url, it will contain the URL of a remote repository, if that can be determined.

• Boolean-valued parameters are represented as Python bool objects.

An in-process hook is called without a change to the process’s working directory (unlike external hooks, which are run in the root of the repository). It must not change the process’s working directory, or it will cause any calls it makes into the Mercurial API to fail.

If a hook returns a boolean “false” value, it is considered to have succeeded. If it returns a boolean “true” value or raises an exception, it is considered to have failed. A useful way to think of the calling convention is “tell me if you fail.”

Note that changeset IDs are passed into Python hooks as hexadecimal strings, not the binary hashes that Mercurial’s APIs normally use. To convert a hash from hex to binary, use the bin function.

External Hook Execution

An external hook is passed to the shell of the user running Mercurial.