From b430c8d15a0c373ad338d045734adedfe5aeea2a Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 5 Feb 2022 17:22:33 +0100 Subject: 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 -- cgit v1.2.3