Overview
Mutagen v0.16 is a relatively minor release focused on internal cleanup. Most of its bug fixes and changes have already been backported to the v0.15.x release branch.
The primary user-facing feature added in v0.16.0 is the --permissions-mode flag.
Permissions modes
Mutagen has always opted for development-oriented heuristics and defaults, including in its treatment of POSIX permissions bits. By default, Mutagen will only record, manage, and propagate executability bits (i.e. those in the 0111 mask) for the files that it synchronizes. Moreover, those bits are only propagated to entities with a corresponding read bit set (i.e. those bits in the 0444 mask). To facilitate this, Mutagen does a lot of work to handle cases where the underlying filesystems don't support the preservation of these bits (e.g. NTFS or FAT32) while still providing an intuitive synchronization experience.
Unfortunately, while this behavior is a useful default (inspired by the likes of Git and rsync), there is one case where additional control is needed: the case where files that originate from a system/filesystem without any notion of POSIX executability bits (e.g. Windows/NTFS) are propagated to a system that relies on a large number of these bits being set. In this case, it may be advantageous for users to be able to specify 0777 permissions for all files as a (hacky) way to make things work more readily. The primary example of this is when synchronizing files from a Windows system into a Linux container (and indeed Docker Desktop's bind mounts perform a similar translation).
To facilitate this, Mutagen v0.16 adds a new configuration option for synchronization sessions: the permissions mode. This can be set using the --permissions-mode flag with mutagen sync create or in YAML under the permissions section:
<session>:
...
permissions:
mode: <mode>
The mode specification may be either portable (the current and default behavior) or manual. In the manual case, Mutagen will neither record nor propagate executability information between endpoints, and the --default-file-mode flags will allow users to include 0111 bits into their values. In this case, the value specified to --default-file-mode (or via its endpoint-specific variants and/or corresponding YAML) will be used for all files, without any regard to their executability status on the origin endpoint.
Note that this new feature is not recommended for most use cases because of the blanket nature of the setting. Most users should continue to use the default behavior.
In the future, the --permissions-mode flag will likely be be expanded (potentially via orthogonal flags) to include additional behaviors, such as ownership propagation, permissions preservation, and raw ownership/permissions propagation.
Changes
A full accounting of changes since v0.15.4 can be found here. Notable changes include:
- The addition of the
--permissions-modeflag (and corresponding YAML-based configuration) - Improved internal state polling, allowing for preemption and reduced overhead in monitoring
- The reduction of the cache and staging garbage collection window from 30 days to 7 days