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.

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

#6231: Clarify where paths are relative to #7737

Open
wants to merge 10 commits into
base: master
Choose a base branch
from
22 changes: 12 additions & 10 deletions docs/usage/help.rst.inc
Original file line number Diff line number Diff line change
Expand Up @@ -17,16 +17,18 @@ unwanted ones. Patterns can be used
- in the file given with ``--patterns-from`` option and
- for ``PATH`` arguments that explicitly support them.

Borg always stores all file paths normalized and relative to the
current recursion root. The recursion root is also named ``PATH`` in
Borg commands like `borg create` that do a file discovery, so do not
confuse the root with the ``PATH`` argument of e.g. `borg extract`.

Starting with Borg 1.2, paths that are matched against patterns always
appear relative. If you give ``/absolute/`` as root, the paths going
into the matcher will start with ``absolute/``.
If you give ``../../relative`` as root, the paths will be normalized
as ``relative/``.
Borg always stores all file paths normalized, with the first part equal to the
recursion root, but (since 1.2) with any leading / or ../ removed. If you give
``/absolute/path`` as root, the paths going into the matcher will start with
``absolute/path``. If you wanted to exclude e.g.
``/absolute/path/logs/*.log``, the pattern ``logs/*.log`` would not match; you
must use ``absolute/path/logs/*.log`` or ``**/logs/*.log`` (using ``sh``
patterns). The pattern ``/absolute/path/logs/*.log`` will also match, since
the leading path separator is stripped in patterns.

The recursion root is also named ``PATH`` in Borg commands like `borg create`
that do a file discovery, so do not confuse the root with the ``PATH``
argument of e.g. `borg extract`.
Comment on lines +29 to +31
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still think this sentence is confusing. I'd vote for just deleting it, as I can't see how someone would confuse a recursion root with a path they want to extract. Or maybe just

Suggested change
The recursion root is also named ``PATH`` in Borg commands like `borg create`
that do a file discovery, so do not confuse the root with the ``PATH``
argument of e.g. `borg extract`.
The recursion root is named ``PATH`` in Borg commands like `borg create`
that do file discovery.


Borg supports different pattern styles. To define a non-default
style for a specific pattern, prefix it with two characters followed
Expand Down