Mutagen has multiple levels of configuration that are merged together and locked-in at session creation time. These include built-in defaults, the global configuration file, command line configuration, and other configuration files. Once the configuration for a session is locked-in, it can’t be changed (without recreating the session). The purpose of this design is to prevent unintended behavioral changes from occuring for existing sessions when configuration files are updated.
When configuration levels are merged, more specific configuration levels take precedence. For example, configuration parameters provided on the command line take precedence over those provided in the global configuration file. For certain configuration parameters (specifically ignore specification lists), merging means appending lists, with the more specific list being appended to the end of the less specific list to allow for overrides. Some parameters also permit endpoint-specific specifications that take precedence over the core merged session configuration.
This guide aims to give an outline of the configuration hierarchy, with individual configuration parameters described in their respective documentation.
Every configuration parameter has a default value. Mutagen’s built-in defaults are designed to be safe and portable. The value for each of these defaults can be found in the relevant documentation for a given parameter.
Mutagen’s global configuration is stored at
~/.mutagen.yml. If it exists, this
file will be merged into the session configuration, taking precedence over
built-in defaults. This configuration is loaded and applied automatically to all
sessions, including those created using Mutagen’s orchestration infrastructure,
--no-global-configuration flag is passed to the relevant session
creation command (
mutagen sync create,
mutagen forward create, or
mutagen project start).
All of Mutagen’s configuration files share the same YAML-based format. The global configuration permits only a subset of this format, namely session defaults. The complete format for this file is as follows:
sync: defaults: mode: ... maxEntryCount: ... maxStagingFileSize: ... probeMode: ... scanMode: ... stageMode: ... symlink: mode: ... watch: mode: ... pollingInterval: ... ignore: paths: - ... - ... vcs: ... permissions: defaultFileMode: ... defaultDirectoryMode: ... defaultOwner: ... defaultGroup: ... forward: defaults: socket: overwriteMode: ... owner: ... group: ... permissionMode: ...
... values in this case represent the values that can be used for each
configuration parameter. These values are documented in their respective
sections throughout the documentation. All parameters are optional.
An additional configuration file, with the same format as the global
configuration, can be specified to
mutagen sync create and
mutagen forward create using the
-c/--configuration-file flag. If provided,
this file will be merged into the session configuration, taking precedence over
the global configuration (if any) and built-in defaults.
Command line configuration
mutagen sync create and
mutagen forward create commands permit the
specification of any session configuration parameter. If provided, these
parameters are merged into the session configuration, taking precedence over
specifications from any other source. These commands also permit
endpoint-specific overrides for certain configuration parameters.
Mutagen’s project orchestration format is an extension of the global configuration format, allowing for session specifications and endpoint-specific configuration parameters. It is detailed more fully in the project orchestration documentation.