Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

improve --one-file-system help /docs #7548

Merged
merged 2 commits into from
May 6, 2023
Merged

improve --one-file-system help /docs #7548

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8cbaaf6
improve --one-file-system help string, fixes #5618
ThomasWaldmann Apr 2, 2023
49b58bf
--one-file-system: add macOS apfs notes, fixes #4876
ThomasWaldmann Apr 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 9 additions & 8 deletions src/borg/archiver.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3448,13 +3448,13 @@ def define_borg_mount(parser):
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.
from the device number of their parent.
In general: be aware that there are directories with device number different from their parent, which the kernel
does not consider a mountpoint and also the other way around.
Linux examples for this 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).
macOS examples are the apfs mounts of a typical macOS installation.
Therefore, when using ``--one-file-system``, you should double-check that the backup works as intended.


.. _list_item_flags:
Expand Down Expand Up @@ -3580,7 +3580,8 @@ 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. This might behave different from your expectations, see the docs.')
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 description below.')
fs_group.add_argument('--numeric-owner', dest='numeric_ids', action='store_true',
help='deprecated, use ``--numeric-ids`` instead')
fs_group.add_argument('--numeric-ids', dest='numeric_ids', action='store_true',
Expand Down