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.internal: Files are staged in a hidden temporary directory inside the synchronization root, allowing placement on the same filesystem as the synchronization root for faster relocation. This mode will fail if the synchronization root doesn’t already exist. It is only advantageous overneighboringwhen working with volume roots.
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>"