Clarify '--one-file-system' for btrfs

[eike-fokken]

This addresses #4009. The documentation now explicitly mentions
btrfs subvolumes.

I'm happy to change the wording if the PR is welcome but the exact wording is not.

[eike-fokken]

rather than adding it to the (short) help here, one could check whether it is documented how -x works (see the check in the code - iirc it is checking for the device number [not] changing) and if that is not documented, add it there.

I don't understand what you mean by "check in the code". I found the code relating to --one-file-system in archiver.py.
To my understanding it explicitely checks the device number from stat.
But is there further documentation on this?

after talking about how borg -x works, one could also point out that some filesystems trigger this change detection:

• btrfs for subvolumes
• (more to come?)

I think, borg create is the only command accepting --one-file-system.
So, do you mean, I should add a paragraph in the text part of the borg create page?

[ThomasWaldmann]

Yes, that is what I meant, add a paragraph to user docs.

Just say what it does so that it is clear how "one filesystem" is defined.

[ThomasWaldmann]

This PR is changing way to many files.

[ThomasWaldmann]

Do not run build_usage / build_man (or at least do not commit the result, so it is more clear what the PR is actually changing) - this is done at release time.

[eike-fokken]

Oh, sorry, I'm not familiar with github pull requests. I meant to make a different pull request, but it got mashed into this one. I will have look later on or tomorrow.

[eike-fokken]

I now inserted a paragraph in the prose part of the docs.

[ThomasWaldmann]

Looks good.

Can you get some other btrfs user from #4009 to review this also (I am unfamiliar with btrfs specifics)?

[eike-fokken]

I will.
What does it mean, that the codecov/project check fails?

[ThomasWaldmann]

@eike-fokken it means the overall test coverage could be improved. Unrelated to this PR.

[eike-fokken]

I got replies from two btrfs users and included their comments, see #4009.

[codecov-io]

Codecov Report

Merging #5391 into master will decrease coverage by 0.20%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #5391      +/-   ##
==========================================
- Coverage   83.61%   83.41%   -0.21%     
==========================================
  Files          37       37              
  Lines        9957     9957              
  Branches     1656     1656              
==========================================
- Hits         8326     8306      -20     
- Misses       1149     1162      +13     
- Partials      482      489       +7     

Impacted Files	Coverage Δ
src/borg/archiver.py	81.37% <ø> (+0.10%)	⬆️
src/borg/platform/__init__.py	72.00% <0.00%> (-12.00%)	⬇️
src/borg/platform/xattr.py	82.53% <0.00%> (-6.35%)	⬇️
src/borg/xattr.py	48.83% <0.00%> (-3.49%)	⬇️
src/borg/platform/base.py	77.58% <0.00%> (-3.45%)	⬇️
src/borg/helpers/misc.py	77.02% <0.00%> (-2.03%)	⬇️
src/borg/archive.py	82.36% <0.00%> (-0.28%)	⬇️
src/borg/helpers/parseformat.py	89.00% <0.00%> (-0.17%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f18c4bf...449e07f. Read the comment docs.

[codecov-commenter]

Codecov Report

Merging #5391 into master will decrease coverage by 0.20%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #5391      +/-   ##
==========================================
- Coverage   83.61%   83.41%   -0.21%     
==========================================
  Files          37       37              
  Lines        9957     9957              
  Branches     1656     1656              
==========================================
- Hits         8326     8306      -20     
- Misses       1149     1162      +13     
- Partials      482      489       +7     

Impacted Files	Coverage Δ
src/borg/archiver.py	81.37% <ø> (+0.10%)	⬆️
src/borg/platform/__init__.py	72.00% <0.00%> (-12.00%)	⬇️
src/borg/platform/xattr.py	82.53% <0.00%> (-6.35%)	⬇️
src/borg/xattr.py	48.83% <0.00%> (-3.49%)	⬇️
src/borg/platform/base.py	77.58% <0.00%> (-3.45%)	⬇️
src/borg/helpers/misc.py	77.02% <0.00%> (-2.03%)	⬇️
src/borg/archive.py	82.36% <0.00%> (-0.28%)	⬇️
src/borg/helpers/parseformat.py	89.00% <0.00%> (-0.17%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f18c4bf...449e07f. Read the comment docs.

[ThomasWaldmann]

Looks good, are you finished?

[eike-fokken]

I am!

That was a pleasant experience, thanks for your time!

[ThomasWaldmann]

Thanks for working on this. Guess we better do a backport to 1.1-maint (as the 1.1.x docs are what people usually read).

[eike-fokken]

Seems like a good idea, my system's borg is 1.1.13 and I am on Debian testing, so rather up-to-date.