Contents

Probing and scanning

On each synchronization cycle, Mutagen endpoints are probed for filesystem behavior and scanned to create a snapshot of synchronization root contents. In both cases, Mutagen can perform the operation in a variety of different ways. While the default behavior will be satisfactory for the vast majority of users, there are certain cases (outlined below) where users may wish to adjust Mutagen’s default behavior.

Probing

Filesystem probing is used to determine certain filesystem behaviors that need to be understood in order to correctly synchronize files between different systems. In particular, Mutagen needs to know if a filesystem preserves POSIX executability bits and whether or not it decomposes Unicode filesystem names. Mutagen has two mechanisms for determining this information: it can either probe the filesystem to determine the exact behavior or assume behavior based on the platform.

When probing a filesystem, Mutagen first checks the filesystem type. Mutagen has a conservative (but broadly applicable) database of filesystem types with well-known behavior, allowing it to skip direct probing on most filesystems. For filesystem types unknown to Mutagen or where behaviors are not well-defined, Mutagen performs direct probing using temporary files. These temporary files contain non-ASCII characters in their names and may cause problems for tools using filesystem watching. In that case, it may be advantageous to tell Mutagen to simply assume filesystem behavior based on the platform.

To configure filesystem probing behavior, Mutagen offers two different modes:

  • probe (Default): In this mode, Mutagen performs its default probing using filesystem type checks and (if necessary) temporary probe files.
  • assume: In this mode, Mutagen assumes filesystem behavior based on the platform. This is less accurate but (very marginally) faster and less likely to cause conflicts with other tools using filesystem watching.

These modes can be specified on a per-session and/or per-endpoint basis by passing the --probe-mode=<mode> or --probe-mode-(alpha|beta)=<mode> flag, respectively, to the mutagen sync create command. These modes can be specified on a default per-session basis by including the following configuration in ~/.mutagen.yml:

sync:
  defaults:
    probeMode: "<mode>"

Scanning

Filesystem scanning is used to generate a snapshot of the synchronization root on an endpoint for use as input to Mutagen’s reconciliation algorithm. Mutagen has two different modes for performing scans:

  • accelerated (Default): In this mode, Mutagen uses filesystem watching information to avoid performing a full synchronization root re-scan. For endpoints using recursive native watching, Mutagen tracks the files that have changed since the last scan and only re-scans those files and their parent directories. For systems using poll-based watching, Mutagen simply returns the last scan generated by polling. For systems with watching disabled, Mutagen simply falls back to a full scan.
  • full: In this mode, Mutagen always performs a full synchronization root re-scan. This is the most accurate option, though it comes with a performance hit for very large synchronization roots.

These modes can be specified on a per-session and/or per-endpoint basis by passing the --scan-mode=<mode> or --scan-mode-(alpha|beta)=<mode> flag, respectively, to the mutagen sync create command. These modes can be specified on a default per-session basis by including the following configuration in ~/.mutagen.yml:

sync:
  defaults:
    scanMode: "<mode>"

It’s worth noting that even in cases where accelerated scanning returns a slightly outdated synchronization root snapshot, Mutagen’s change application algorithms will still detect conflicting changes that might have been missed in the outdated snapshot, so the safety behavior is the same as with full scanning.