3.10 Managed Databases

In monotone commands, a database name (provided to a --db option) starting with “:” is a “database alias”. It addresses a usual monotone database sitting in a special, “managed” location, which we therefore call a “managed database”.

The database alias is a regular file name (excluding the leading colon). Monotone searches for this file name in common locations and internally expands it to a full path once it found an unambigious match.

Some commands, such as mtn clone and mtn setup, work without a --db option; they fall back on a managed “default” database and even initialize that in case it is not existant.

To keep an overview of managed databases and their workspaces, the commands mtn list databases and mtn list workspaces can be used: The former shows a list of all known databases in all managed locations together with their workspaces, while the latter only shows the list of workspaces for a single, specified database.

Monotone usually keeps track of known workspaces automatically in the background and updates the references as soon as your workspace’ database option in _MTN/options is set up or changed. There are a few cases where monotone is unable to detect changes, though, for example when a workspace is moved in the file system. To get monotone back on track in cases like this, the commands mtn register_workspace and mtn unregister_workspace can be used.

Finally, all this magic behaviour can be customized by a variety of lua hooks:

• get_default_database_locations returns a list of search paths where monotone should look for managed databases. This hook defaults to a single directory; $HOME/.monotone/databases on Unix and %APPDATA%\monotone\databases on Windows.
• get_default_database_glob returns a pattern which monotone uses to match and recognized database files in the configured default locations. This pattern is also used to determine if shortened database aliases, such as :default, should get suffixed with .mtn to be transformed into a valid database file name. By default this hook returns .{mtn,db}.
• get_default_database_alias returns the name of the alias of a default database that is initialized and used on demand. If more than one database locations are configured, the first location is used as save location for this database. This hook defaults to :default.mtn.