From 4652fc01cdd915be369d080703b297fd6a0ccc96 Mon Sep 17 00:00:00 2001 From: Eike Date: Tue, 6 Oct 2020 11:28:05 +0200 Subject: [PATCH 1/3] Clarify '--one-file-system' for btrfs This addresses #4009. The documentation now explicitly mentions btrfs subvolumes. --- src/borg/archiver.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index efb5d96d76..7d2a1d8ad6 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -3220,7 +3220,7 @@ def define_borg_mount(parser): 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. Be aware that this treats every btrfs subvolume as a separate file system and will not back them up! Make doubly sure to check your backup does what you want when using btrfs.') fs_group.add_argument('--numeric-owner', dest='numeric_owner', action='store_true', help='only store numeric user and group identifiers') # --noatime is the default now and the flag is deprecated. args.noatime is not used any more. From 260b3861e5e62b794d2f11e158ab1c22716392e2 Mon Sep 17 00:00:00 2001 From: Eike Date: Wed, 7 Oct 2020 16:13:27 +0200 Subject: [PATCH 2/3] explained --one-file-system in detail. --- src/borg/archiver.py | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 7d2a1d8ad6..9c3c34f8b6 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -3111,6 +3111,16 @@ def define_borg_mount(parser): 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. Be aware that in Linux 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 in Linux 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. + the distribution installer. + + .. _list_item_flags: Item flags @@ -3220,7 +3230,7 @@ def define_borg_mount(parser): 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. Be aware that this treats every btrfs subvolume as a separate file system and will not back them up! Make doubly sure to check your backup does what you want when using btrfs.') + 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') # --noatime is the default now and the flag is deprecated. args.noatime is not used any more. From 449e07f8e39af82c85b330f4ac6e3730c290eb17 Mon Sep 17 00:00:00 2001 From: Eike Date: Mon, 12 Oct 2020 09:24:07 +0200 Subject: [PATCH 3/3] Update on the docs on --one-file-system The feedback from issue #4009 is now included. --- src/borg/archiver.py | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 9c3c34f8b6..2952ee55d2 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -3112,13 +3112,15 @@ def define_borg_mount(parser): 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. Be aware that in Linux 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 in Linux 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. - the distribution installer. + 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: