upstream/borgbackup
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-04-24 23:57:23 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

build_usage

Browse source
This commit is contained in:
Thomas Waldmann 2022-02-05 17:22:33 +01:00
parent 55591b882e
commit b430c8d15a
9 changed files with 89 additions and 71 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
docs/usage/create.rst.inc
View file

@ -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

74
docs/usage/diff.rst.inc
View file

@ -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

8
docs/usage/export-tar.rst.inc
View file

@ -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.

14
docs/usage/extract.rst.inc
View file

@ -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``.
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.

19
docs/usage/help.rst.inc
View file

@ -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.

13
docs/usage/key_export.rst.inc
View file

@ -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.
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

8
docs/usage/list.rst.inc
View file

@ -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

8
docs/usage/mount.rst.inc
View file

@ -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.

8
docs/usage/recreate.rst.inc
View file

@ -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