From fa26d5f7c45b253943ca445caa698096dea03041 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 5 Feb 2022 17:20:03 +0100 Subject: [PATCH 1/5] update CHANGES --- docs/changes.rst | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/docs/changes.rst b/docs/changes.rst index c7514a7c5..afeedc133 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -217,8 +217,8 @@ The best check that everything is ok is to run a dry-run extraction:: Change Log ========== -Version 1.2.0b4 (2022-01-23) ----------------------------- +Version 1.2.0rc1 (2022-02-05) +----------------------------- Please note: @@ -270,6 +270,41 @@ Compatibility notes: if you have scripts expecting rc == 2 for a signal exit, you need to update them to check for >= 128. +Fixes: + +- repo::archive location placeholder expansion fixes, #5826, #5998 +- repository: fix intermediate commits, shall be at end of current segment +- delete: don't commit if nothing was deleted, avoid cache sync, #6060 +- argument parsing: accept some options only once, #6026 +- disallow overwriting of existing keyfiles on init, #6036 +- if ensure_dir() fails, give more informative error message, #5952 + +New features: + +- delete --force: do not ask when deleting a repo, #5941 + +Other changes: + +- requirements: exclude broken or incompatible-with-pyinstaller setuptools +- add a requirements.d/development.lock.txt and use it for vagrant +- tests: + + - added nonce-related tests + - refactor: remove assert_true + - vagrant: macos box tuning, netbsd box fixes, #5370, #5922 +- docs: + + - update install docs / requirements docs, #6180 + - borg mount / FUSE "versions" view is not experimental any more + - --pattern* is not experimental any more, #6134 + - impact of deleting path/to/repo/nonce, #5858 + - key export: add examples, #6204 + - ~/.config/borg/keys is not used for repokey keys, #6107 + - excluded parent dir's metadata can't restore + + +Version 1.2.0b4 (2022-01-23) +---------------------------- Fixes: From 55591b882ee81b91b973cf6b0a6d69dab3458fa6 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 5 Feb 2022 17:31:26 +0100 Subject: [PATCH 2/5] setup_docs: put import-tar into same file as export-tar --- setup_docs.py | 1 + 1 file changed, 1 insertion(+) diff --git a/setup_docs.py b/setup_docs.py index eb44b608e..d326ec8d2 100644 --- a/setup_docs.py +++ b/setup_docs.py @@ -307,6 +307,7 @@ class build_man(Command): 'key_migrate-to-repokey': 'key', 'export-tar': 'tar', + 'import-tar': 'tar', 'benchmark_crud': 'benchmark', From b430c8d15a0c373ad338d045734adedfe5aeea2a Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 5 Feb 2022 17:22:33 +0100 Subject: [PATCH 3/5] build_usage --- docs/usage/create.rst.inc | 8 ++-- docs/usage/diff.rst.inc | 74 +++++++++++++++++------------------ docs/usage/export-tar.rst.inc | 8 ++-- docs/usage/extract.rst.inc | 14 ++++--- docs/usage/help.rst.inc | 19 +++++---- docs/usage/key_export.rst.inc | 13 +++++- docs/usage/list.rst.inc | 8 ++-- docs/usage/mount.rst.inc | 8 ++-- docs/usage/recreate.rst.inc | 8 ++-- 9 files changed, 89 insertions(+), 71 deletions(-) diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index 7b06fab2c..e6fa4e3a1 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -59,9 +59,9 @@ borg create +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html) | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -153,8 +153,8 @@ borg create Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line --exclude-caches exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html) --exclude-if-present NAME exclude directories that are tagged by containing a filesystem object with the given NAME --keep-exclude-tags if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive diff --git a/docs/usage/diff.rst.inc b/docs/usage/diff.rst.inc index 21ae9a936..ec3bffc29 100644 --- a/docs/usage/diff.rst.inc +++ b/docs/usage/diff.rst.inc @@ -12,41 +12,41 @@ borg diff .. class:: borg-options-table - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | **positional arguments** | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``REPO::ARCHIVE1`` | repository location and ARCHIVE1 name | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``ARCHIVE2`` | ARCHIVE2 name (no repository location allowed) | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``PATH`` | paths of items inside the archives to compare; patterns are supported | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | **optional arguments** | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--numeric-owner`` | deprecated, use ``--numeric-ids`` instead | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--numeric-ids`` | only consider numeric user and group identifiers | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--same-chunker-params`` | Override check of chunker parameters. | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--sort`` | Sort the output lines by file path. | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--json-lines`` | Format output as JSON Lines. | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | **Exclusion options** | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | **positional arguments** | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``REPO::ARCHIVE1`` | repository location and ARCHIVE1 name | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``ARCHIVE2`` | ARCHIVE2 name (no repository location allowed) | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``PATH`` | paths of items inside the archives to compare; patterns are supported | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | **optional arguments** | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--numeric-owner`` | deprecated, use ``--numeric-ids`` instead | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--numeric-ids`` | only consider numeric user and group identifiers | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--same-chunker-params`` | Override check of chunker parameters. | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--sort`` | Sort the output lines by file path. | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--json-lines`` | Format output as JSON Lines. | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | **Exclusion options** | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ .. raw:: html @@ -80,8 +80,8 @@ borg diff Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line Description diff --git a/docs/usage/export-tar.rst.inc b/docs/usage/export-tar.rst.inc index 8a235ff27..c898d7b51 100644 --- a/docs/usage/export-tar.rst.inc +++ b/docs/usage/export-tar.rst.inc @@ -37,9 +37,9 @@ borg export-tar +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``--strip-components NUMBER`` | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ @@ -73,8 +73,8 @@ borg export-tar Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line --strip-components NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc index 76e3e70b2..ce6ede4cc 100644 --- a/docs/usage/extract.rst.inc +++ b/docs/usage/extract.rst.inc @@ -51,9 +51,9 @@ borg extract +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``--strip-components NUMBER`` | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ @@ -93,8 +93,8 @@ borg extract Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line --strip-components NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. @@ -118,4 +118,8 @@ pass over the archive metadata. .. note:: Currently, extract always writes into the current working directory ("."), - so make sure you ``cd`` to the right place before calling ``borg extract``. \ No newline at end of file + so make sure you ``cd`` to the right place before calling ``borg extract``. + + When parent directories are not extracted (because of using file/directory selection + or any other reason), borg can not restore parent directories' metadata, e.g. owner, + group, permission, etc. \ No newline at end of file diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index a477483c1..cd7682db0 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -22,10 +22,9 @@ store all files as `some/path/.../file.ext` and ``borg create File patterns support these styles: fnmatch, shell, regular expressions, path prefixes and path full-matches. By default, fnmatch is used for -``--exclude`` patterns and shell-style is used for the experimental -``--pattern`` option. For commands that support patterns in their -``PATH`` argument like (``borg list``), the default pattern is path -prefix. +``--exclude`` patterns and shell-style is used for the ``--pattern`` + option. For commands that support patterns in their ``PATH`` argument +like (``borg list``), the default pattern is path prefix. Starting with Borg 1.2, for all but regular expression pattern matching styles, all paths are treated as relative, meaning that a leading path @@ -145,11 +144,9 @@ Examples:: EOF $ borg create --exclude-from exclude.txt backup / -.. container:: experimental - A more general and easier to use way to define filename matching patterns exists - with the experimental ``--pattern`` and ``--patterns-from`` options. Using these, you - may specify the backup roots (starting points) and patterns for inclusion/exclusion. + with the ``--pattern`` and ``--patterns-from`` options. Using these, you may + specify the backup roots (starting points) and patterns for inclusion/exclusion. A root path starts with the prefix `R`, followed by a path (a plain path, not a file pattern). An include rule starts with the prefix +, an exclude rule starts with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern. @@ -166,6 +163,12 @@ Examples:: a directory, it won't recurse into it and won't discover any potential matches for include rules below that directory. + .. note:: + + It's possible that a sub-directory/file is matched while parent directories are not. + In that case, parent directories are not backed up thus their user, group, permission, + etc. can not be restored. + Note that the default pattern style for ``--pattern`` and ``--patterns-from`` is shell style (`sh:`), so those patterns behave similar to rsync include/exclude patterns. The pattern style can be set via the `P` prefix. diff --git a/docs/usage/key_export.rst.inc b/docs/usage/key_export.rst.inc index a65d32df9..0a57bf091 100644 --- a/docs/usage/key_export.rst.inc +++ b/docs/usage/key_export.rst.inc @@ -77,4 +77,15 @@ data backup. For repositories using the repokey encryption the key is saved in the repository in the config file. A backup is thus not strictly needed, but guards against the repository becoming inaccessible if the file -is damaged for some reason. \ No newline at end of file +is damaged for some reason. + +Examples:: + + borg key export /path/to/repo > encrypted-key-backup + borg key export --paper /path/to/repo > encrypted-key-backup.txt + borg key export --qr-html /path/to/repo > encrypted-key-backup.html + # Or pass the output file as an argument instead of redirecting stdout: + borg key export /path/to/repo encrypted-key-backup + borg key export --paper /path/to/repo encrypted-key-backup.txt + borg key export --qr-html /path/to/repo encrypted-key-backup.html + diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc index 7799b4daf..456f42a66 100644 --- a/docs/usage/list.rst.inc +++ b/docs/usage/list.rst.inc @@ -53,9 +53,9 @@ borg list +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. raw:: html @@ -96,8 +96,8 @@ borg list Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line Description diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc index 0ac4caa48..a720f88a1 100644 --- a/docs/usage/mount.rst.inc +++ b/docs/usage/mount.rst.inc @@ -55,9 +55,9 @@ borg mount +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--strip-components NUMBER`` | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -102,8 +102,8 @@ borg mount Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line --strip-components NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. diff --git a/docs/usage/recreate.rst.inc b/docs/usage/recreate.rst.inc index e45784fae..f64e07599 100644 --- a/docs/usage/recreate.rst.inc +++ b/docs/usage/recreate.rst.inc @@ -39,9 +39,9 @@ borg recreate +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html) | +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -95,8 +95,8 @@ borg recreate Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line --exclude-caches exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html) --exclude-if-present NAME exclude directories that are tagged by containing a filesystem object with the given NAME --keep-exclude-tags if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive From ef8aac2e4c46a645af05b0d608e70e0104ebafe6 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 5 Feb 2022 17:30:40 +0100 Subject: [PATCH 4/5] build_man --- docs/man/borg-benchmark-crud.1 | 2 +- docs/man/borg-benchmark.1 | 2 +- docs/man/borg-break-lock.1 | 2 +- docs/man/borg-check.1 | 2 +- docs/man/borg-common.1 | 2 +- docs/man/borg-compact.1 | 2 +- docs/man/borg-compression.1 | 2 +- docs/man/borg-config.1 | 2 +- docs/man/borg-create.1 | 6 +- docs/man/borg-delete.1 | 2 +- docs/man/borg-diff.1 | 6 +- docs/man/borg-export-tar.1 | 6 +- docs/man/borg-extract.1 | 10 +- docs/man/borg-import-tar.1 | 2 +- docs/man/borg-info.1 | 2 +- docs/man/borg-init.1 | 2 +- docs/man/borg-key-change-passphrase.1 | 2 +- docs/man/borg-key-export.1 | 20 +++- docs/man/borg-key-import.1 | 2 +- docs/man/borg-key-migrate-to-repokey.1 | 2 +- docs/man/borg-key.1 | 2 +- docs/man/borg-list.1 | 6 +- docs/man/borg-mount.1 | 6 +- docs/man/borg-patterns.1 | 130 ++++++++++++------------- docs/man/borg-placeholders.1 | 2 +- docs/man/borg-prune.1 | 2 +- docs/man/borg-recreate.1 | 6 +- docs/man/borg-rename.1 | 2 +- docs/man/borg-serve.1 | 2 +- docs/man/borg-umount.1 | 4 +- docs/man/borg-upgrade.1 | 2 +- docs/man/borg-with-lock.1 | 2 +- docs/man/borg.1 | 2 +- docs/man/borgfs.1 | 6 +- 34 files changed, 135 insertions(+), 117 deletions(-) diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index 2aaa58f4e..bf0abc816 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BENCHMARK-CRUD" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-BENCHMARK-CRUD" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. .SH SYNOPSIS diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index dd28a1951..8f9972d67 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BENCHMARK" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-BENCHMARK" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-benchmark \- benchmark command .SH SYNOPSIS diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index 9acbf8851..dd13cbd82 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BREAK-LOCK" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-BREAK-LOCK" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. .SH SYNOPSIS diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index 732372702..aeb5c3db5 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-CHECK" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-CHECK" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-check \- Check repository consistency .SH SYNOPSIS diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index 8fe2ca702..9eec2c6b9 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-COMMON" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-COMMON" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-common \- Common options of Borg commands .SH SYNOPSIS diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1 index cd6faf243..c9b1b5db7 100644 --- a/docs/man/borg-compact.1 +++ b/docs/man/borg-compact.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-COMPACT" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-COMPACT" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-compact \- compact segment files in the repository .SH SYNOPSIS diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index f6672f500..1a651782f 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-COMPRESSION" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-COMPRESSION" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-compression \- Details regarding compression .SH DESCRIPTION diff --git a/docs/man/borg-config.1 b/docs/man/borg-config.1 index a92fe2d63..b6093cfe5 100644 --- a/docs/man/borg-config.1 +++ b/docs/man/borg-config.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-CONFIG" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-CONFIG" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-config \- get, set, and delete values in a repository or cache config file .SH SYNOPSIS diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index 178a2d1cb..e002dacf0 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-CREATE" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-CREATE" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-create \- Create new archive .SH SYNOPSIS @@ -187,10 +187,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .TP .B \-\-exclude\-caches exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP) diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index b08c8fbb1..a3ff02571 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-DELETE" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-DELETE" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-delete \- Delete an existing repository or archives .SH SYNOPSIS diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index af8156210..1a8aebf7b 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-DIFF" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-DIFF" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-diff \- Diff contents of two archives .SH SYNOPSIS @@ -94,10 +94,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .UNINDENT .SH EXAMPLES .INDENT 0.0 diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index 7fccdc1b9..58b2b2028 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-EXPORT-TAR" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-EXPORT-TAR" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-export-tar \- Export archive contents as a tarball .SH SYNOPSIS @@ -110,10 +110,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .TP .BI \-\-strip\-components \ NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index ba3606888..d4148eaee 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-EXTRACT" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-EXTRACT" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-extract \- Extract archive contents .SH SYNOPSIS @@ -54,6 +54,10 @@ pass over the archive metadata. .INDENT 3.5 Currently, extract always writes into the current working directory ("."), so make sure you \fBcd\fP to the right place before calling \fBborg extract\fP\&. +.sp +When parent directories are not extracted (because of using file/directory selection +or any other reason), borg can not restore parent directories\(aq metadata, e.g. owner, +group, permission, etc. .UNINDENT .UNINDENT .SH OPTIONS @@ -111,10 +115,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .TP .BI \-\-strip\-components \ NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. diff --git a/docs/man/borg-import-tar.1 b/docs/man/borg-import-tar.1 index 8b90e6d61..70a9db3d2 100644 --- a/docs/man/borg-import-tar.1 +++ b/docs/man/borg-import-tar.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-IMPORT-TAR" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-IMPORT-TAR" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-import-tar \- Create a backup archive from a tarball .SH SYNOPSIS diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index 63cee823c..5112545e1 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-INFO" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-INFO" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-info \- Show archive details such as disk space used .SH SYNOPSIS diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1 index 43e2e69bc..3c5b83e08 100644 --- a/docs/man/borg-init.1 +++ b/docs/man/borg-init.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-INIT" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-INIT" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-init \- Initialize an empty repository .SH SYNOPSIS diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 48e9af352..b49c8bddd 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-key-change-passphrase \- Change repository key file passphrase .SH SYNOPSIS diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index 7adb2b4e2..ce63f6142 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-EXPORT" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-KEY-EXPORT" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-key-export \- Export the repository key for backup .SH SYNOPSIS @@ -56,6 +56,24 @@ For repositories using the repokey encryption the key is saved in the repository in the config file. A backup is thus not strictly needed, but guards against the repository becoming inaccessible if the file is damaged for some reason. +.sp +Examples: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +borg key export /path/to/repo > encrypted\-key\-backup +borg key export \-\-paper /path/to/repo > encrypted\-key\-backup.txt +borg key export \-\-qr\-html /path/to/repo > encrypted\-key\-backup.html +# Or pass the output file as an argument instead of redirecting stdout: +borg key export /path/to/repo encrypted\-key\-backup +borg key export \-\-paper /path/to/repo encrypted\-key\-backup.txt +borg key export \-\-qr\-html /path/to/repo encrypted\-key\-backup.html +.ft P +.fi +.UNINDENT +.UNINDENT .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index f26aee1fd..f2fc5422d 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-IMPORT" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-KEY-IMPORT" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-key-import \- Import the repository key from backup .SH SYNOPSIS diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1 index a316b3c30..57d66eaae 100644 --- a/docs/man/borg-key-migrate-to-repokey.1 +++ b/docs/man/borg-key-migrate-to-repokey.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-key-migrate-to-repokey \- Migrate passphrase -> repokey .SH SYNOPSIS diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index 13aaf0378..9b0a0221c 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-KEY" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-key \- Manage a keyfile or repokey of a repository .SH SYNOPSIS diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index 56f6748fd..1a4ea9138 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-LIST" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-LIST" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-list \- List archive or repository contents .SH SYNOPSIS @@ -96,10 +96,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .UNINDENT .SH EXAMPLES .INDENT 0.0 diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index 6c5f18616..6a7d3ad6c 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-MOUNT" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-MOUNT" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-mount \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS @@ -153,10 +153,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .TP .BI \-\-strip\-components \ NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index cafad763b..3115154e1 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-PATTERNS" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-PATTERNS" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns .SH DESCRIPTION @@ -48,10 +48,18 @@ store all files as \fIsome/path/.../file.ext\fP and \fBborg create .sp File patterns support these styles: fnmatch, shell, regular expressions, path prefixes and path full\-matches. By default, fnmatch is used for -\fB\-\-exclude\fP patterns and shell\-style is used for the experimental -\fB\-\-pattern\fP option. For commands that support patterns in their -\fBPATH\fP argument like (\fBborg list\fP), the default pattern is path -prefix. +\fB\-\-exclude\fP patterns and shell\-style is used for the \fB\-\-pattern\fP +.IP "System Message: ERROR/3 (docs/borg-patterns.rst:, line 43)" +Unexpected indentation. +.INDENT 0.0 +.INDENT 3.5 +option. For commands that support patterns in their \fBPATH\fP argument +.UNINDENT +.UNINDENT +.IP "System Message: WARNING/2 (docs/borg-patterns.rst:, line 44)" +Block quote ends without a blank line; unexpected unindent. +.sp +like (\fBborg list\fP), the default pattern is path prefix. .sp Starting with Borg 1.2, for all but regular expression pattern matching styles, all paths are treated as relative, meaning that a leading path @@ -179,77 +187,65 @@ sh:/home/*/.thumbnails some file with spaces.txt EOF $ borg create \-\-exclude\-from exclude.txt backup / -.ft P -.fi -.UNINDENT -.UNINDENT + A more general and easier to use way to define filename matching patterns exists -with the experimental \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using these, you -may specify the backup roots (starting points) and patterns for inclusion/exclusion. -A root path starts with the prefix \fIR\fP, followed by a path (a plain path, not a +with the \(ga\(ga\-\-pattern\(ga\(ga and \(ga\(ga\-\-patterns\-from\(ga\(ga options. Using these, you may +specify the backup roots (starting points) and patterns for inclusion/exclusion. +A root path starts with the prefix \(gaR\(ga, followed by a path (a plain path, not a file pattern). An include rule starts with the prefix +, an exclude rule starts with the prefix \-, an exclude\-norecurse rule starts with !, all followed by a pattern. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Via \fB\-\-pattern\fP or \fB\-\-patterns\-from\fP you can define BOTH inclusion and exclusion -of files using pattern prefixes \fB+\fP and \fB\-\fP\&. With \fB\-\-exclude\fP and -\fB\-\-exclude\-from\fP ONLY excludes are defined. -.UNINDENT -.UNINDENT -.sp + +\&.. note:: + + Via \(ga\(ga\-\-pattern\(ga\(ga or \(ga\(ga\-\-patterns\-from\(ga\(ga you can define BOTH inclusion and exclusion + of files using pattern prefixes \(ga\(ga+\(ga\(ga and \(ga\(ga\-\(ga\(ga. With \(ga\(ga\-\-exclude\(ga\(ga and + \(ga\(ga\-\-exclude\-from\(ga\(ga ONLY excludes are defined. + Inclusion patterns are useful to include paths that are contained in an excluded path. The first matching pattern is used so if an include pattern matches before an exclude pattern, the file is backed up. If an exclude\-norecurse pattern matches a directory, it won\(aqt recurse into it and won\(aqt discover any potential matches for include rules below that directory. -.sp -Note that the default pattern style for \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP is -shell style (\fIsh:\fP), so those patterns behave similar to rsync include/exclude -patterns. The pattern style can be set via the \fIP\fP prefix. -.sp -Patterns (\fB\-\-pattern\fP) and excludes (\fB\-\-exclude\fP) from the command line are -considered first (in the order of appearance). Then patterns from \fB\-\-patterns\-from\fP -are added. Exclusion patterns from \fB\-\-exclude\-from\fP files are appended last. -.sp -Examples: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -# backup pics, but not the ones from 2018, except the good ones: -# note: using = is essential to avoid cmdline argument parsing issues. -borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 repo::arch pics -# use a file with patterns: -borg create \-\-patterns\-from patterns.lst repo::arch -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The patterns.lst file could look like that: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -# "sh:" pattern style is the default, so the following line is not needed: -P sh -R / -# can be rebuild -\- /home/*/.cache -# they\(aqre downloads for a reason -\- /home/*/Downloads -# susan is a nice person -# include susans home -+ /home/susan -# don\(aqt backup the other home directories -\- /home/* -# don\(aqt even look in /proc -! /proc +\&.. note:: + + It\(aqs possible that a sub\-directory/file is matched while parent directories are not. + In that case, parent directories are not backed up thus their user, group, permission, + etc. can not be restored. + +Note that the default pattern style for \(ga\(ga\-\-pattern\(ga\(ga and \(ga\(ga\-\-patterns\-from\(ga\(ga is +shell style (\(gash:\(ga), so those patterns behave similar to rsync include/exclude +patterns. The pattern style can be set via the \(gaP\(ga prefix. + +Patterns (\(ga\(ga\-\-pattern\(ga\(ga) and excludes (\(ga\(ga\-\-exclude\(ga\(ga) from the command line are +considered first (in the order of appearance). Then patterns from \(ga\(ga\-\-patterns\-from\(ga\(ga +are added. Exclusion patterns from \(ga\(ga\-\-exclude\-from\(ga\(ga files are appended last. + +Examples:: + + # backup pics, but not the ones from 2018, except the good ones: + # note: using = is essential to avoid cmdline argument parsing issues. + borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 repo::arch pics + + # use a file with patterns: + borg create \-\-patterns\-from patterns.lst repo::arch + +The patterns.lst file could look like that:: + + # "sh:" pattern style is the default, so the following line is not needed: + P sh + R / + # can be rebuild + \- /home/*/.cache + # they\(aqre downloads for a reason + \- /home/*/Downloads + # susan is a nice person + # include susans home + + /home/susan + # don\(aqt backup the other home directories + \- /home/* + # don\(aqt even look in /proc + ! /proc .ft P .fi .UNINDENT diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index dd70332ba..e2add1fb8 100644 --- a/docs/man/borg-placeholders.1 +++ b/docs/man/borg-placeholders.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-PLACEHOLDERS" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-PLACEHOLDERS" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-placeholders \- Details regarding placeholders .SH DESCRIPTION diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index c287cfb4b..bf725776d 100644 --- a/docs/man/borg-prune.1 +++ b/docs/man/borg-prune.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-PRUNE" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-PRUNE" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-prune \- Prune repository archives according to specified rules .SH SYNOPSIS diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index 77881d60a..18c7e6686 100644 --- a/docs/man/borg-recreate.1 +++ b/docs/man/borg-recreate.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-RECREATE" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-RECREATE" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-recreate \- Re-create archives .SH SYNOPSIS @@ -122,10 +122,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .TP .B \-\-exclude\-caches exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP) diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index 2627b2033..021756ce0 100644 --- a/docs/man/borg-rename.1 +++ b/docs/man/borg-rename.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-RENAME" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-RENAME" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-rename \- Rename an existing archive .SH SYNOPSIS diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 index 09e12ca2c..3cd76f3ee 100644 --- a/docs/man/borg-serve.1 +++ b/docs/man/borg-serve.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-SERVE" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-SERVE" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-serve \- Start in server mode. This command is usually not used manually. .SH SYNOPSIS diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index 2fd420d10..1e57a9879 100644 --- a/docs/man/borg-umount.1 +++ b/docs/man/borg-umount.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-UMOUNT" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-UMOUNT" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-umount \- un-mount the FUSE filesystem .SH SYNOPSIS @@ -69,7 +69,7 @@ bin boot etc home lib lib64 lost+found media mnt opt root sbin srv tmp usr var $ borg umount /tmp/mymountpoint -# The experimental "versions view" merges all archives in the repository +# The "versions view" merges all archives in the repository # and provides a versioned view on files. $ borg mount \-o versions /path/to/repo /tmp/mymountpoint $ ls \-l /tmp/mymountpoint/home/user/doc.txt/ diff --git a/docs/man/borg-upgrade.1 b/docs/man/borg-upgrade.1 index a54006938..7930dbc4c 100644 --- a/docs/man/borg-upgrade.1 +++ b/docs/man/borg-upgrade.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-UPGRADE" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-UPGRADE" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-upgrade \- upgrade a repository from a previous version .SH SYNOPSIS diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index 9d4fb188a..09219074a 100644 --- a/docs/man/borg-with-lock.1 +++ b/docs/man/borg-with-lock.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-WITH-LOCK" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG-WITH-LOCK" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg-with-lock \- run a user specified command with the repository lock held .SH SYNOPSIS diff --git a/docs/man/borg.1 b/docs/man/borg.1 index 449bb3813..fe8626416 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG" 1 "2022-01-23" "" "borg backup tool" +.TH "BORG" 1 "2022-02-05" "" "borg backup tool" .SH NAME borg \- deduplicating and encrypting backup tool .SH SYNOPSIS diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1 index c03d1a3f4..0c28ea4c7 100644 --- a/docs/man/borgfs.1 +++ b/docs/man/borgfs.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORGFS" 1 "2022-01-23" "" "borg backup tool" +.TH "BORGFS" 1 "2022-02-05" "" "borg backup tool" .SH NAME borgfs \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS @@ -156,10 +156,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .TP .BI \-\-strip\-components \ NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. From d6bfb1147cb2d993976e5daecb0cc07a0d4fceb7 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 5 Feb 2022 18:04:47 +0100 Subject: [PATCH 5/5] appveyor: use py38 --- .appveyor.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.appveyor.yml b/.appveyor.yml index d3ab16c44..6ceca538c 100644 --- a/.appveyor.yml +++ b/.appveyor.yml @@ -1,8 +1,8 @@ version: '{build}' -environment: +environment: matrix: - - PYTHON: C:\Python37-x64 + - PYTHON: C:\Python38-x64 # Disable automatic builds build: off