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

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.