From 0b00ef65c24e641b29ccfc50c8b674ee356e9d9d Mon Sep 17 00:00:00 2001 From: Jakob Borg Date: Sat, 20 Jun 2015 22:56:37 +0200 Subject: [PATCH] Draft docs for FollowSymlinks --- draft/followsymlinks.rst | 70 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 draft/followsymlinks.rst diff --git a/draft/followsymlinks.rst b/draft/followsymlinks.rst new file mode 100644 index 000000000..c228988b3 --- /dev/null +++ b/draft/followsymlinks.rst @@ -0,0 +1,70 @@ +.. note:: This describes an incomplete feature under development. + +.. warning:: + + This is an advanced feature. Be sure to read and fully understand this + guide, and have a backup of your data. Incorrect configuration may result in + the deletion of your files. Currently it's probably best to only use + ``FollowSymlinks`` on a folder master. + +.. versionadded:: v0.11.10 + +Symbolic Link Following +======================= + +It is possible to synchronize directory trees not present directly under a +sync folder by using symbolic links ("symlinks") and enabling "following" of +them. This feature is currently experimental and cannot be enabled by using +the graphical interface. + +Operation +--------- + +When a folder is configured to follow symlinks, any such links that are +encountered during scanning will be resolved to their destination and scanned. +Symlinks can point to either files or directories. When symlink following is +enabled, the behavior is changed from the default (copy symlinks verbatim) to +the following: + +#. Symlinks pointing to a nonexistent destination are ignored. + +#. Symlinks pointing to a file are interpreted as being that file. + +#. Editing such a file on another device results in the *symlink* being + replaced with the new version of the file. + +#. Deleting such a file on another device results in the *symlink* being + deleted. + +#. Symlinks pointing to directories are interpreted as being that directory. + +#. Symlinks pointing to a directory that is a child of another already scanned + directory are ignored. This is to avoid infinite recursion in symlink + following. + +Enabling +-------- + +.. code-block:: xml + + + + ... + true + + ... + + +Disabling +--------- + +.. warning:: + + Disabling ``FollowSymlinks``, once enabled, is not fully supported. Doing so + by the same mechanism used to enable it is likely to destroy your files. + +Disabling ``FollowSymlinks`` on the source results in symlinked directories +being deleted and replaced with the actual symlink. During the next scan, the +files previously present in the directory will be noted as having been deleted +and delete record sent to other devices. The source device will then delete +the files.