From acaef57a16d00f370f51cdc1260a8578437e0f26 Mon Sep 17 00:00:00 2001 From: eike-fokken <33839210+eike-fokken@users.noreply.github.com> Date: Mon, 12 Oct 2020 13:26:09 +0200 Subject: [PATCH] Clarify '--one-file-system' for btrfs (#5391) docs: clarify borg create's '--one-file-system' option, #4009 The documentation now explicitly mentions btrfs subvolumes and explains how --one-file-system works. Co-authored-by: Eike --- src/borg/archiver.py | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 0228e6669..f59e80505 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -3321,6 +3321,18 @@ class Archiver: and not include any other contents of the containing folder, this can be enabled through using the ``--keep-exclude-tags`` option. + The ``-x`` or ``--one-file-system`` option excludes directories, that are mountpoints (and everything in them). + It detects mountpoints by comparing the device number from the output of ``stat()`` of the directory and its + parent directory. Specifically, it excludes directories for which ``stat()`` reports a device number different + from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories + with device number different from their parent, which the kernel does not consider a mountpoint and also the + other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL + subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when + using ``--one-file-system``, one should make doubly sure that the backup works as intended especially when using + btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution + installer. + + .. _list_item_flags: Item flags @@ -3415,7 +3427,7 @@ class Archiver: fs_group = subparser.add_argument_group('Filesystem options') fs_group.add_argument('-x', '--one-file-system', dest='one_file_system', action='store_true', - help='stay in the same file system and do not store mount points of other file systems') + help='stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs.') fs_group.add_argument('--numeric-owner', dest='numeric_owner', action='store_true', help='only store numeric user and group identifiers') fs_group.add_argument('--noatime', dest='noatime', action='store_true',