Staging

When transferring files to an endpoint, Mutagen first stages them in a temporary directory so that they can be atomically relocated into place. By default, these files are staged in the Mutagen data directory (~/.mutagen), which works well for most synchronization root locations and keeps staged files consolidated in a single location. However, in cases where the synchronization root resides on a different filesystem than the user’s home directory, staging files in the Mutagen data directory incurs an additional copy operation to transition them into place. To work around this, Mutagen provides the following staging modes:

  • mutagen (Default): Files are staged in the Mutagen data directory (~/.mutagen) before being relocated to the synchronization root.
  • neighboring: Files are staged in a hidden temporary directory that neighbors the synchronization root, allowing placement on the same filesystem as the synchronization root for faster relocation.

These modes can be specified on a per-session and/or per-endpoint basis by passing the --stage-mode=<mode> or --stage-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:
    stageMode: "<mode>"