From b369fcde28f3995c7f31e9ea9fdc708b3af9b49c Mon Sep 17 00:00:00 2001
From: "yair@unicorn" <yair@unicorn>
Date: Fri, 18 Jan 2019 00:14:38 +0200
Subject: [PATCH] local: add documentation for `-l` option #1152

---
 docs/content/local.md | 68 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 67 insertions(+), 1 deletion(-)

diff --git a/docs/content/local.md b/docs/content/local.md
index 2fba21153..03987d138 100644
--- a/docs/content/local.md
+++ b/docs/content/local.md
@@ -116,8 +116,74 @@ $ rclone -L ls /tmp/a
         6 b/one
 ```
 
-### Restricting filesystems with --one-file-system
+#### --links, -l 
 
+Normally rclone will ignore symlinks or junction points (which behave
+like symlinks under Windows).
+
+If you supply this flag then rclone will copy symblic links from the local storage,
+and store them as text files, with a '.rclonelink' suffix in the remote storage.
+
+The text file will contain the target of the symblic link (see example).
+
+This flag applies to all commands.
+
+For example, supposing you have a directory structure like this
+
+```
+$ tree /tmp/a
+/tmp/a
+├── file1 -> ./file4
+└── file2 -> /home/user/file3
+```
+
+Copying the entire directory with '-l'
+
+```
+$ rclone copyto -l /tmp/a/file1 remote:/tmp/a/
+```
+
+The remote files are created with a '.rclonelink' suffix
+
+```
+$ rclone ls remote:/tmp/a
+       5 file1.rclonelink
+      14 file2.rclonelink
+```
+
+The remote files will contain the target of the symblic links
+
+```
+$ rclone cat remote:/tmp/a/file1.rclonelink
+./file4
+
+$ rclone cat remote:/tmp/a/file2.rclonelink
+/home/user/file3
+```
+
+Copying them back with '-l'
+
+```
+$ rclone copyto -l remote:/tmp/a/ /tmp/b/
+
+$ tree /tmp/b
+/tmp/b
+├── file1 -> ./file4
+└── file2 -> /home/user/file3
+```
+
+However, if copied back without '-l'
+
+```
+$ rclone copyto remote:/tmp/a/ /tmp/b/
+
+$ tree /tmp/b
+/tmp/b
+├── file1.rclonelink
+└── file2.rclonelink
+````
+
+### Restricting filesystems with --one-file-system
 Normally rclone will recurse through filesystems as mounted.
 
 However if you set `--one-file-system` or `-x` this tells rclone to