Contents

Symbolic links

Mutagen has full support for symbolic links on both POSIX and Windows systems. Because POSIX and Windows platforms have different symbolic link implementations and interpretations, Mutagen provides a few different symbolic link synchronization modes aimed at providing maximum compatibility:

  • ignore: In this mode, Mutagen simply ignores any symbolic links that it encounters within a synchronization root. This means that it won’t propagate them and it won’t delete them. This mode is supported on both POSIX and Windows systems.
  • portable (default): In this mode, Mutagen restricts itself to propagating only symbolic links that it defines as “portable”. Portable symbolic links are those which are relative paths, containing only safe characters, which do point outside the synchronization root at any point in their target path. In this mode, Mutagen also performs appropriate symbolic link normalization on Windows endpoints to ensure that symbolic links are correctly round-tripped to disk. If a non-portable symbolic link is detected within the synchronization root, the session will halt synchronization until it is removed or corrected. This mode is supported on both POSIX and Windows systems, though please see the note below about Windows permissions.
  • posix-raw: In this mode, which is only supported for synchronization sessions between two POSIX endpoints, Mutagen will propagate raw symbolic link targets without any analysis or modification. Trying to use this mode when either endpoint is a Windows system will prevent synchronization from starting.

These modes can be specified on a per-session basis by passing the --symlink-mode=<mode> flag to the mutagen sync create command and on a default per-session basis by including the following configuration in ~/.mutagen.yml:

sync:
  defaults:
    symlink:
      mode: "<mode>"

Windows permissions

On Windows, the SeCreateSymbolicLinkPrivilege permission is required to create symbolic links. By default, this permission is usually only granted to administrators. This has changed a bit in Windows 10, where anyone can create symbolic links if Developer Mode has been enabled.

If you don’t have the SeCreateSymbolicLinkPrivilege permission and can’t add it for yourself, or you can’t enable Developer Mode in Windows 10, then you have two choices:

  1. Do nothing. In this case, Mutagen will attempt to propagate symbolic links (if it’s in Portable mode), and will simply report that it is unable to do so. This won’t hurt anything, and it won’t stop other files from synchronizing. The only downside is that you’ll see problems indicated when listing or monitoring the session.
  2. Switch to ignoring symbolic links.