6 Lua Reference

Monotone makes use of the Lua programming language to customize and extend its behaviour. By writing functions which are loaded and evaluated at runtime, you can help monotone to make a particular decision, set a suitable default or preference or perform a certain action.

Lua functions are defined in “rcfiles” which will be read every time monotone runs. rcfiles consist of:

• $HOME/.monotone/monotonerc on Unix or %APPDATA%\monotone\monotonerc on Windows
• _MTN/monotonerc in the current workspace
• Files given in the --rcfile=file option on the command line.
• All files in a directory given by --rcfile=directory on the command line.

The files are loaded in the order .monotone/monotonerc, _MTN/monotonerc, --rcfile in the command line order. Definitions loaded later shadow (override) earlier definitions.

There are two uses for Lua functions; hooks and user-defined commands. This section documents hooks; see register_command for user-defined commands. The source distribution contains some example user commands in the contrib/command directory.

Hooks are Lua functions that are called from monotone code in many places. Monotone provides default definitions for some hooks; see Default hooks for their complete source. For other hooks, if no definition is provided, a default return value is used. When writing new hooks, it may be helpful to reuse some code from the default ones. Since Lua is a lexically scoped language with closures, this can be achieved with the following code:

do
    local old_hook = default_hook
    function default_hook(arg)
        if not old_hook(arg) then
            -- do other stuff
        end
    end
end

Now the default hook is trapped in a variable local to this block, and can only be seen by the new hook. Since in Lua functions default to the global scope, the new hook is seen from inside monotone.

Monotone also provides a number of helper functions to hook writers exposing functionality not available with standard Lua.