Repository: borgbackup/borg

Issue:
Confusing advice regarding --ignore-inode command line flag
The documentation currently says:

> To speed up pulling backups over sshfs and similar network file systems which do not provide correct inode information the –ignore-inode flag can be used. This potentially decreases reliability of change detection, while avoiding always reading all files on these file systems.

I tried to understand how this actually works:

* Inode information is used to avoid reading and hashing files that didn't change since the previous backup.
* This information could be wrong when backing up files from sshfs and similar network file systems, so that some files might be mistakenly considered unchanged, and some probably marked as changed despite not having been changed (is that actually an issue?).
* In order to make change detection work reliably, `--ignore-inode` flag can be specified. This will cause all files to be read in on backup which should improve consistency at the cost of performance.

Did I get this correctly? If so, it doesn't match the documentation at all, I can suggest a better formulation then.


Discussion:
Yeah this wording isn't exactly great...

> This information could be wrong when backing up files from sshfs and similar network file systems, so that some files might be mistakenly considered unchanged, and some probably marked as changed despite not having been changed (is that actually an issue?).

It's the other way around ("potentially decreases reliability").

 > In order to make change detection work reliably, --ignore-inode flag can be specified. This will cause all files to be read in on backup which should improve consistency at the cost of performance.

No, --ignore-inode ignores the inode which could otherwise trigger a re-read ("To speed up pulling backups ... the –ignore-inode flag can be used.")

I assume the "this" in "This potentially decreases reliability" makes this paragraph very ambiguous? How about "Enabling this flag ..."?

——

The internal details are described [here](http://borgbackup.readthedocs.io/en/latest/internals/data-structures.html#the-cache) (unstable docs); --ignore-inode just removes the inode-equality check.
I looked it up in the source code and apparently I got this wrong. With the `--ignore-inode` flag change detection happens by size and modification time only. So the confusing parts here are "pulling backup over" (I initially associated that with a restore operation, and didn't realize that sshfs is the location of the files being backed up, not the repository) and "potentially decreases reliability" being not very informative. Finally, the context (unchanged files being skipped for incremental backups) is missing.

How about:

> Backup speed is increased by not reprocessing files that are already part of existing archives and weren't modified. Normally, detecting file modifications will take inode information into consideration. This is problematic for files located on sshfs and similar network file systems which do not provide correct inode information, such files will always be considered modified. The –ignore-inode flag can be used to prevent this and improve performance. This flag will reduce reliability of change detection however, with files considered unmodified as long as their size and modification time are unchanged.
Guess that's better, just s/correct inode information,/stable inode numbers -/.

That part was actually copied from the current documentation :smile: 
Can you do a PR?

Resolving patch:
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -2767,10 +2767,14 @@ def define_archive_filters_group(subparser, *, sort_by=True, first_last=True):
         In the archive name, you may use the following placeholders:
         {now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.
 
-        To speed up pulling backups over sshfs and similar network file systems which do
-        not provide correct inode information the ``--ignore-inode`` flag can be used. This
-        potentially decreases reliability of change detection, while avoiding always reading
-        all files on these file systems.
+        Backup speed is increased by not reprocessing files that are already part of
+        existing archives and weren't modified. Normally, detecting file modifications
+        will take inode information into consideration. This is problematic for files
+        located on sshfs and similar network file systems which do not provide stable
+        inode numbers, such files will always be considered modified. The
+        ``--ignore-inode`` flag can be used to prevent this and improve performance.
+        This flag will reduce reliability of change detection however, with files
+        considered unmodified as long as their size and modification time are unchanged.
 
         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


Test patch: