monotone documentation: User Defaults

6.1.3 User Defaults

These are hooks that can be used to provide smart, context-sensitive default values for a number of parameters the user might otherwise be prompted for.

get_branch_key (branchname)

Called whenever monotone needs a key to sign a certificate, and --key was not given.

Returns a string which is the name or hash of a private key used to sign certificates in a particular branch branchname, or nil for no key.

See --key for a description of how monotone determines what key to use.

There is no default definition for this hook; it returns nil.

get_netsync_client_key(server, include, exclude)

Called by the client when a netsync connection is being established, and --key was not given. Returns a string which is the name or hash of the key to use to authenticate the client side of a netsync connection.

Note that netsync commands do not need a signing key; they only transmit already signed information.

See --key for a discussion of how monotone determines what key to use.

Arguments, when called:

server: The scheme, user, host, port, and path fields from the URI provided on the command line. See netsync uri.
include: The include pattern in the URI provided on the command line.
exclude: The exclude pattern in the URI provided on the command line.

get_netsync_server_key(addresses)

Called by the server when a new netsync server instance is created, and --key was not given. Returns a string which is the name or hash of the key to use to authenticate the server side of a netsync connection.

Note that netsync commands do not need a signing key; they only transmit already signed information.

See --key for a discussion of how monotone determines what key to use.

Arguments, when called:

addresses: A table of addresses given to monotone via the --bind option that denote the addresses and / or ports monotone is listening on for connections. If the address in one of the table entries is omitted, the port must be given with a leading colon; in this case monotone listens on all interfaces on this port.

get_default_command_options(command)

Called after a command is completed, before the workspace options are loaded, and before the command line options are processed.

Returns a table of options. The options must be valid for the given command or global options. The returned option values overwrite the standard default options values; workspace and command line options override the new defaults as usual.

The argument is a table containing the command keywords, indexed by the integer position of the keyword in the command. For example, mtn list branches passes a table (1 => "list", 2 => "branches").

The default definition of this hook returns an empty table.

Simple example which enables recursive directory scanning for mtn add by default:

function get_default_command_options(command)
    local default_options = {}
    if (command[1] == "add") then
        table.insert(default_options, "--recursive")
    end
    return default_options
end

get_passphrase (key_identity)

Called whenever monotone needs to use a private key.

Returns a string which must match the passphrase used to encrypt the private key_identity in your key store.

This hook has no default definition.

If this hook is not defined or returns false, and ssh keys are not enabled (see mtn ssh_agent_export), monotone will prompt you for a passphrase each time it needs to use a private key.

get_local_key_name (key_identity)

Called whenever monotone retrieves a key from the keystore or database, or completes a user-provided key, to provide the local alias (the name field in key_identity).

Returns the local alias for the given key_identity. The id and given_name fields of key_identity will be populated, and the name field will not be. The return value indicates what the name field should contain.

The default implementation of this hook returns given_name.

get_author (branchname, key_identity)

Called by any command that needs an author name for an author cert for a commit, if --author is not given.

Returns a string which is the author name. If it returns nil, the key local name (as provided by get_local_key_name) is used for the author name.

branchname is the branch for the commit, key_identity is the key.

There is no default definition for this hook; it returns nil.

Example definitions:

function get_author(branchname, key_identity)
        -- Key pair identity ignored.
        local user = os.getenv("USER")
        local host = os.getenv("HOSTNAME")
        if ((user == nil) or (host == nil)) then return nil end
        return string.format("%s@%s", user, host)
end

function get_author(branchname, key_identity)
        -- Branch name ignored.
        if (key_identity.given_name == "joe@example.com") then
                return "Joe Random <joe@example.com>"
        end
        return key_identity
end

get_default_database_locations ()

Called whenever monotone converts a database name to an absolute path.

Returns a table of paths where monotone should look for Managed Databases.

The default implementation returns a table with a single entry, $HOME/.monotone/databases on Unix and %APPDATA%\monotone\databases on Windows.

get_default_database_alias ()

Called whenever monotone converts a database name to an absolute path.

Returns the alias of the managed database which should be used as default. See Managed Databases.

The default implementation returns :default.mtn.

get_default_database_glob ()

Returns a pattern to let monotone distinguish a valid from an invalid database file name. This pattern is used in two places:

When monotone scans for database files in its default database locations, it will skip all files which do not match the pattern return from this hook.
When a partial database alias is validated and the alias’ name does not match the pattern returned from this hook, .mtn is appended to the alias’ name.

The default implementation returns *.{mtn,db}.

edit_comment (user_log_message)

Called by mtn comment, mtn commit, mtn import when a comment is not provided on the command line.

Returns a commit comment for the command. user_log_message depends on the calling command; see the command definitions.

This hook is intended to interface with some sort of editor, so that you can interactively document each change you make.

The default definition of edit_comment invokes the user’s editor (specified by the environment variables VISUAL and EDITOR, or editor, vi, or notepad on Windows). See Default hooks.

persist_phrase_ok ()

Called whenever a passphrase is provided to decrypt a private key.

Returns true if you want monotone to remember the passphrase of a private key for the duration of a single command, or false if you want monotone to prompt you for a passphrase for each certificate it generates. Since monotone often generates several certificates in quick succession, unless you are very concerned about security you probably want this hook to return true.

The default definition of this hook returns true.

use_inodeprints ()

Called when creating a new workspace.

Returns true if you want monotone to automatically enable Inodeprints support in the workspace.

The default definition of this hook returns false.

ignore_file (filename)

Called by many monotone commands when considering whether to process a file in a workspace.

Returns true if filename should be ignored by the command, false otherwise.

This is most important when performing recursive actions on directories; if ignore_file returns true for a directory, all files under that directory will be ignored.

In some commands, --no-ignore will cause this hook to not be called.

The default definition of this hook recognises a number of common file types and extensions for temporary and generated file types that users typically don’t want to track. In addition, if the file .mtn-ignore exists in the root workspace directory, this hook will read a list of regular expressions from the file, one per line, and ignore all files matching one of these expressions. See Default hooks.

ignore_branch (branchname)

Called by mtn automate branches, mtn automate tags, mtn list branches.

Returns true if branchname should be ignored by the command, otherwise returns false.

This hook has no default definition; it acts as if it returns false.

get_date_format_spec (wanted)

Called by commands that display dates, when neither --date-format nor --no-format-dates is given.

Returns a strftime format specification.

If an empty string is returned, monotone uses the date format “yyyy-mm-ddThh:mm:ss”.

The default definition returns ‘%x’ for long and short date formats, ‘%X’ for long and short time formats and ‘%x %X’ for long and short date time formats, which is equivalent to ‘22/05/09’, ‘09:06:14’ and ‘22/05/09 09:06:14’ in an English locale.

wanted can be one of ‘date_long’, ‘date_short’, ‘time_long’, ‘time_short’, ‘date_time_long’, ‘date_time_short’.

get_man_page_formatter_command ()

Called by mtn manpage, if --formatted is specified.

Returns a command string that is passed to the operating system function popen to format man pages. The input to the pipe is nroff markup.

Note that on the native Windows build of monotone, popen runs the cmd.exe shell to execute the command string. On Unix and Windows Cygwin, popen runs the sh shell.

The default hook returns a string that runs nroff and pipes that output into the less pager, with appropriate options. On Windows native, the default hook assumes that Cygwin or equivalent is installed, and includes sh in the command string.