Configuration

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. Certain parameters also permit endpoint-specific specifications that take precedence over the core session configuration. For certain configuration parameters, namely ignore path 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.

This guide aims to give an outline of the configuration hierarchy, with individual configuration parameters described in their respective documentation.

Built-in defaults

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.

Global configuration

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, unless the --no-global-configuration flag is passed to the relevant session creation command (mutagen sync create, mutagen forward create, or mutagen project start).

Format

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: ...

The ... 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.

Configuration files

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

Both the 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.

Orchestration configuration

Mutagen’s session orchestration format is an extension of the global configuration format, allowing for endpoint specifications and endpoint-specific configuration parameters. It is detailed more fully in the orchestration documentation.