Ignores

By default, Mutagen attempts to propagate all files that it sees within a synchronization root. This isn’t always desirable, so Mutagen supports ignoring paths within a synchronization root and excluding them from synchronization. When a path is ignored, it won’t be scanned, it won’t be propagated, and it won’t be deleted.

Mutagen allows ignores to be specified on both a default and per-session basis. It supports a rich syntax for specifying ignores, which should be familiar to Git users. In fact, the syntax and behavior is almost identical to Git’s (with a few helpful extensions), so the gitignore documentation is another useful reference for understanding ignore behavior and strategies. Finally, Mutagen provides utilities for ignoring certain kinds of common directories, such as data directories from version control systems.

Global ignores

Global ignores affect all newly created sessions. These should be used for files that should always be ignored (for example, those pesky .DS_Store files on macOS).

When a new session is created, global ignores are “locked in” to the session configuration, meaning that subsequent changes to global ignores will only be reflected in subsequently created sessions. This is for simplicity (no need to think through the effects of changing ignores in one place) and safety (no files will suddenly become unignored and propagated (causing conflicts or security risks) or silently ignored).

Global ignores are specified in the ~/.mutagen.yml file as follows:

sync:
  defaults:
    ignore:
      paths:
        - "<ignore1>"
        - "<ignore2>"
        - ...

The format of ignore specifications is outline below.

Per-session ignores

Per-session ignores only affect the session to which they are attached. They are processed after global ignores, meaning that they can extend or cancel out global ignores.

To specify ignores on a per-session basis, use the -i/--ignore flag of the mutagen sync create command. Multiple ignores can be specified using repeated -i/--ignore flags, for example:

mutagen sync create -i <ignore1> -i <ignore2> ...

or using comma-separated values, for example:

mutagen sync create --ignore=<ignore1>,<ignore2> ...

Ignore groups

Mutagen provides ignore “groups” that provide a pre-defined set of ignores that can be used for sessions. At the moment, only one ignore group is defined in Mutagen, which ignores VCS directories (for example, .git, .svn, etc.), though additional ignore groups (for example, for Python object code files, node_modules directories, etc.) will be coming in future versions.

Ignore groups are processed before both global and per-session ignores, so they can be extended or cancelled out by global and per-session ignores.

Version control systems

Version control system (VCS) directories can be ignored on a per-session basis by passing the --ignore-vcs flag to the create command and on a default basis by including the following configuration in ~/.mutagen.yml:

sync:
  defaults:
    ignore:
      vcs: true

A default VCS ignore setting can be overridden on a per-session basis by passing the --no-ignore-vcs flag to the create command.

Format and behavior

The format and behavior of Mutagen’s ignore patterns are designed to match those of Git, insofar as that makes sense for Mutagen’s somewhat different application.

Ignore patterns are essentially paths that support special syntax for matching. At a base level, ignore patterns are built using the doublestar package, so all of the syntax there carries over.

Ignore patterns use / as a path separator. All paths are treated as relative to the synchronization root.

If an ignore pattern does not contain a / (i.e. it is a leaf name), then it will also be treated as relative to any subdirectory in the synchronization root. For example, an ignore pattern of some/path will only ignore content at <root>/some/path, but an ignore pattern of path will ignore content at <root>/path, <root>/some/path, <root>/other/path, etc. If you want to ignore content that exists directly at the root and not any other subpath, then prefix the ignore with /. For example, build will ignore content named build at any subdirectory, but /build will only ignore content at <root>/build.

Suffixing a pattern with / will cause it to match only directories. It’s important to note that this is the only way that a path can “become” ignored or unignored, and the way that this behaves with a three-way merge might be non-intuitive. For example, imagine that an ignore of name/ is specified, and that both endpoints of the connection have a copy of a synchronized file (not a directory) called name. Imagine that one endpoint then replaces the file name with a directory called name. This directory will now be ignored. Since Mutagen will ignore a directory called name in its scans, it will appear to Mutagen’s three-way merge algorithm that the content at this path has been deleted on the side where the type has changed to a directory, and it will thus propagate deletion of the file called name to the other endpoint. This is still technically correct behavior, but it’s worth understanding before using this type of ignore pattern.

Prefixing a pattern with ! will cause it to negate previously matching ignores. E.g. specifying an ignore list like ["hot*", "!hotel"] will ignore any content whose name begins with “hot”, unless the full content name is “hotel”. This can be a useful mechanism for overriding global ignores on a per-session basis.