Next: , Previous: Command Reference, Up: Top


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.

You can put Lua functions in a file $HOME/.monotone/monotonerc, or in your workspace in _MTN/monotonerc, both of which will be read every time monotone runs. Definitions in _MTN/monotonerc shadow (override) definitions made in your $HOME/.monotone/monotonerc. You can also tell monotone to interpret extra hook functions from any other file using the --rcfile=file option; hooks defined in files specified on the command-line will shadow hooks from the other predefined locations. By specifying --rcfile=directory you can automatically load all the files contained in directory.

There are two uses for Lua functions; hooks and user-defined commands. This section documents hooks; see register_command in Additional Lua Functions 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 variables 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.