v0.16.0

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-mode flag (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

v0.16.0-rc1

NOTE: This is a pre-release version of Mutagen. It should not be used on production or mission-critical systems. Use on any system is at your own risk (please see the license). For a better experience, you may wish to use the latest stable release.

Mutagen maintains backward compatibility between releases, but sessions created with pre-release versions are not guaranteed to be compatible with final releases. Please wait for the final release if you want to be sure that you can avoid recreating sessions.

Changes

Final release notes and documentation will be issued when v0.16.0 is released.

This release includes the following changes from v0.16.0-beta2:

• Updated to Go 1.19.2
• Updated various dependencies
• Updated third-party license information

v0.15.4

Changes

This release includes the following changes from v0.15.3:

• Backported fix for accelerated scanning corner case when using fanotify watching

v0.16.0-beta2

NOTE: This is a pre-release version of Mutagen. It should not be used on production or mission-critical systems. Use on any system is at your own risk (please see the license). For a better experience, you may wish to use the latest stable release.

Mutagen maintains backward compatibility between releases, but sessions created with pre-release versions are not guaranteed to be compatible with final releases. Please wait for the final release if you want to be sure that you can avoid recreating sessions.

Changes

Final release notes and documentation will be issued when v0.16.0 is released.

This release includes the following changes from v0.16.0-beta1:

• Fixed accelerated scanning corner case when using fanotify watching

v0.16.0-beta1

NOTE: This is a pre-release version of Mutagen. It should not be used on production or mission-critical systems. Use on any system is at your own risk (please see the license). For a better experience, you may wish to use the latest stable release.

Mutagen maintains backward compatibility between releases, but sessions created with pre-release versions are not guaranteed to be compatible with final releases. Please wait for the final release if you want to be sure that you can avoid recreating sessions.

Changes

Final release notes and documentation will be issued when v0.16.0 is released.

This release is primarily focused on internal changes, with one additional new feature: a permissions mode setting.

At the moment, the permissions mode setting can be either portable (the default) or manual. The portable mode is Mutagen's current behavior, where only executability permissions are propagated and only to users with a corresponding read bit set. The manual mode offers fully manual control over the permission bits that Mutagen will set, allowing file modes to include 0111 bits that would normally be rejected by the portable propagation mode. Additional permissions modes are planned (such as posix-raw).

To set the permissions mode, you can use the --permissions-mode flag with mutagen sync create or include the mode under the permissions heading in YAML, e.g.

sync:
  mysession:
    ...
    permissions:
      mode: manual

Most users will not want to use the manual mode. At the moment, the only known use case is for setting 0111 permission bits on all files when executability information is not available on the endpoint where the files originate (e.g. when syncing files from a Windows machine into a Docker container).

This release includes the following changes from v0.15.2:

• A new "permissions mode" feature has been added
• Non-UTF-8 filenames are now handled more gracefully
• Housekeeping periods for stale caches and staging roots have been reduced from 30 days to 7 days
• Internal state tracking has been refactored to support more immediate cancellation
• Releases are now built using Go 1.19

v0.15.3

Changes

This release includes the following changes from v0.15.2:

• Improved handling of non-UTF-8 filenames
• Updated to Go 1.18.6

v0.16.0-alpha3

Alpha release

This is a pre-release version created for testing purposes and should not be used. Please continue to use the latest stable release for the time being.

v0.16.0-alpha2

Alpha release

This is a pre-release version created for testing purposes and should not be used. Please continue to use the latest stable release for the time being.

v0.16.0-alpha1

Alpha release

This is a pre-release version created for testing purposes and should not be used. Please continue to use the latest stable release for the time being.

v0.15.2

Changes

This release includes the following changes from v0.15.1:

• Modified templated rendering to include session status even when paused
  • Thanks to @rfay for reporting
• Fixed detection of mutagen-agent absence on tcsh (#366)
  • Thanks to @mkoennecke for reporting
• Switched to using defaultFileMode instead of defaultDirectoryMode for base symbolic link permissions (see below)

Symbolic link permissions changes

This release contains a minor change for symbolic link permissions bits. While no existing behavior is documented and most POSIX systems don't respect symbolic link permission bits in any case, the original intention was for Mutagen to use defaultFileMode as the basis for symbolic link permission bits. In earlier releases, the defaultDirectoryMode setting was being used as the basis for symbolic link permissions instead of defaultFileMode. The cases in which this change will have any effect are uncommon and the effects are minimal.

Specifically, the following conditions are necessary for there to be any difference:

• Non-default settings are used for defaultDirectoryMode and/or defaultFileMode

AND

• (Case 1) macOS is being used and defaultDirectoryMode has read bits that differ from those in defaultFileMode, OR
• (Case 2) Windows is being used and defaultDirectoryMode differs from defaultFileMode in its setting of the 0200 bit

In Case 1, the differing read bit(s) will have an effect on corresponding entities' ability to invoke readlink on the symbolic link. They have no impact on the accessibility of the link's target. No other POSIX platforms use symlink permission bits to enforce access control, instead allowing readlink unconditionally, and thus this change has no visible impact on those platforms other than the (unused) permission bits set on the symlink being different. On platforms such as Linux, which don't allow the association of permission bits with symlinks, there is no effect whatsoever.

In Case 2, the differing 0200 bit only affects owner writability for the symbolic link.