From 0da1e34602673a21da4daea44c794fb27f978895 Mon Sep 17 00:00:00 2001 From: Jeff Turner Date: Tue, 25 Jul 2023 23:28:08 +1000 Subject: [PATCH 1/7] Clarify where paths are relative to --- docs/usage/help.rst.inc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index 1fee15d4ed..b7c51cd6d6 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -18,13 +18,13 @@ unwanted ones. Patterns can be used - 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`. +first directory of 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/``. +appear relative. If you give ``/opt/app/`` as root, the paths going +into the matcher will start with ``opt/``. If you give ``../../relative`` as root, the paths will be normalized as ``relative/``. From b2cf0df64160f3735829581087436d82c9268962 Mon Sep 17 00:00:00 2001 From: Jeff Turner Date: Tue, 25 Jul 2023 23:46:38 +1000 Subject: [PATCH 2/7] Use 'absolute' in the absolute path --- docs/usage/help.rst.inc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index b7c51cd6d6..0dca6744ae 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -23,8 +23,8 @@ first directory of the current recursion root. The recursion root is also named 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 ``/opt/app/`` as root, the paths going -into the matcher will start with ``opt/``. +appear relative. If you give ``/absolute/path/`` 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/``. From c65f2cbee5712d67a46795f42b16e0204f202fcf Mon Sep 17 00:00:00 2001 From: Jeff Turner Date: Wed, 26 Jul 2023 00:54:28 +1000 Subject: [PATCH 3/7] Further clarifications --- docs/usage/help.rst.inc | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index 0dca6744ae..249c4631f8 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -17,16 +17,17 @@ 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 -first directory of 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/path/`` 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 matches 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 (using ``sh`` patterns) +``**/logs/*.log``. + +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`. Borg supports different pattern styles. To define a non-default style for a specific pattern, prefix it with two characters followed From 66037af9430297ff344c0fb8d4032545bbe9062c Mon Sep 17 00:00:00 2001 From: Jeff Turner Date: Wed, 26 Jul 2023 01:00:02 +1000 Subject: [PATCH 4/7] Typo --- docs/usage/help.rst.inc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index 249c4631f8..cb8e5a57dc 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -19,7 +19,7 @@ unwanted ones. Patterns can be used 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 matches will start with +``/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 (using ``sh`` patterns) From b44193d82b0bc14107038a09abaa8346a24da6e2 Mon Sep 17 00:00:00 2001 From: Jeff Turner Date: Wed, 26 Jul 2023 01:02:41 +1000 Subject: [PATCH 5/7] Simplify --- docs/usage/help.rst.inc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index cb8e5a57dc..eccccd985f 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -22,8 +22,8 @@ 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 (using ``sh`` patterns) -``**/logs/*.log``. +must use ``absolute/path/logs/*.log`` or ``**/logs/*.log`` (using ``sh`` +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`` From 81b8a5ade19ddc898bc67fe5cbe801d7554c1cc9 Mon Sep 17 00:00:00 2001 From: Jeff Turner Date: Wed, 26 Jul 2023 01:09:52 +1000 Subject: [PATCH 6/7] Also mention that the matching pattern can be absolute --- docs/usage/help.rst.inc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index eccccd985f..b183cac248 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -23,7 +23,8 @@ recursion root, but (since 1.2) with any leading / or ../ removed. If you give ``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). +patterns). Since the leading path separator is stripped in patterns, +``/absolute/path/logs/*.log`` will also match (and is clearest). 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`` From a94a15f3f19febc94af0d2f8dc3f1cacb4043c7d Mon Sep 17 00:00:00 2001 From: Jeff Turner Date: Wed, 26 Jul 2023 00:54:28 +1000 Subject: [PATCH 7/7] Doc clarifications --- docs/usage/help.rst.inc | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index 0dca6744ae..df3053a5d3 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -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 -first directory of 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/path/`` 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`. Borg supports different pattern styles. To define a non-default style for a specific pattern, prefix it with two characters followed