document snapshot usage #2178

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.
         """)

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.