From 9f07d13c4a3c3b893fb82f59b22c4a4d78a53132 Mon Sep 17 00:00:00 2001
From: kmq <kmq@omfa.de>
Date: Sun, 26 Feb 2017 13:47:26 +0200
Subject: [PATCH 1/2] document snapshot usage #2178

---
 borg/archiver.py | 5 +++++
 docs/faq.rst     | 2 +-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/borg/archiver.py b/borg/archiver.py
index ce70e831d..cc214b682 100644
--- a/borg/archiver.py
+++ b/borg/archiver.py
@@ -1374,6 +1374,11 @@ class Archiver:
         potentially decreases reliability of change detection, while avoiding always reading
         all files on these file systems.
 
+        The mount points of filesystems or filesystem snapshots should be the same for every
+        creation of a new archive to ensure fast operation. This is because the file cache that
+        is used to determine changed files quickly uses absolute filenames.
+        If this is not possible, consider creating a bind mount to a stable location.
+
         See the output of the "borg help patterns" command for more help on exclude patterns.
         See the output of the "borg help placeholders" command for more help on placeholders.
         """)
diff --git a/docs/faq.rst b/docs/faq.rst
index f0ae2fe7f..6c69d60b5 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -422,7 +422,7 @@ BORG_FILES_CACHE_TTL to at least 26 (or maybe even a small multiple of that),
 it would be much faster.
 
 Another possible reason is that files don't always have the same path, for
-example if you mount a filesystem without stable mount points for each backup.
+example if you mount a filesystem without stable mount points for each backup or if you are running the backup from a filesystem snapshot whose name is not stable.
 If the directory where you mount a filesystem is different every time,
 |project_name| assume they are different files.
 

From 96ebb096e9ee4220eff2b404f1defce19064e2da Mon Sep 17 00:00:00 2001
From: kmq <kmq@omfa.de>
Date: Sun, 26 Feb 2017 20:33:15 +0200
Subject: [PATCH 2/2] Document relative path usage #1868

---
 borg/archiver.py | 9 ++++++---
 docs/usage.rst   | 6 +++++-
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/borg/archiver.py b/borg/archiver.py
index cc214b682..99d21369b 100644
--- a/borg/archiver.py
+++ b/borg/archiver.py
@@ -1355,9 +1355,12 @@ class Archiver:
 
         create_epilog = textwrap.dedent("""
         This command creates a backup archive containing all files found while recursively
-        traversing all paths specified. When giving '-' as path, borg will read data
-        from standard input and create a file 'stdin' in the created archive from that
-        data.
+        traversing all paths specified. Paths are added to the archive as they are given,
+        that means if relative paths are desired, the command has to be run from the correct
+        directory.
+
+        When giving '-' as path, borg will read data from standard input and create a
+        file 'stdin' in the created archive from that data.
 
         The archive will consume almost no disk space for files or parts of files that
         have already been stored in other archives.
diff --git a/docs/usage.rst b/docs/usage.rst
index 18a7cdbdf..48f1894d5 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -435,6 +435,11 @@ Examples
     # As above, but add nanoseconds
     $ borg create /path/to/repo::{hostname}-{user}-{now:%Y-%m-%dT%H:%M:%S.%f} ~
 
+    # Backing up relative paths by moving into the correct directory first
+    $ cd /home/user/Documents
+    # The root directory of the archive will be "projectA"
+    $ borg create /path/to/repo::daily-projectA-{now:%Y-%m-%d} projectA
+
 Notes
 ~~~~~
 
@@ -443,7 +448,6 @@ Notes
   '\*/.bundler/gems' to get the same effect. See ``borg help patterns`` for
   more information.
 
-
 .. include:: usage/extract.rst.inc
 
 Examples