diff options
author | Thomas Waldmann <tw@waldmann-edv.de> | 2022-01-23 15:52:21 +0100 |
---|---|---|
committer | Thomas Waldmann <tw@waldmann-edv.de> | 2022-01-23 15:52:21 +0100 |
commit | 572e996d9a9479abb8c9e50a03d5b96ca413ef90 (patch) | |
tree | e4b6bfc23abd53c0f5b7176f571f7d72487a971e /docs/usage | |
parent | 5b60761bd755b73e3320a31a39a4a350d9f40d3f (diff) |
build_usage
Diffstat (limited to 'docs/usage')
-rw-r--r-- | docs/usage/create.rst.inc | 4 | ||||
-rw-r--r-- | docs/usage/export-tar.rst.inc | 10 | ||||
-rw-r--r-- | docs/usage/extract.rst.inc | 6 | ||||
-rw-r--r-- | docs/usage/help.rst.inc | 25 | ||||
-rw-r--r-- | docs/usage/import-tar.rst.inc | 117 | ||||
-rw-r--r-- | docs/usage/list.rst.inc | 132 | ||||
-rw-r--r-- | docs/usage/mount.rst.inc | 17 | ||||
-rw-r--r-- | docs/usage/prune.rst.inc | 4 |
8 files changed, 235 insertions, 80 deletions
diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index 9129112c5..7b06fab2c 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -37,7 +37,7 @@ borg create +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--stdin-user USER`` | set user USER in archive for stdin data (default: 'root') | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--stdin-group GROUP`` | set group GROUP in archive for stdin data (default: 'root') | + | | ``--stdin-group GROUP`` | set group GROUP in archive for stdin data (default: 'wheel') | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--stdin-mode M`` | set mode to M in archive for stdin data (default: 0660) | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -139,7 +139,7 @@ borg create --no-cache-sync experimental: do not synchronize the cache. Implies not using the files cache. --stdin-name NAME use NAME in archive for stdin data (default: 'stdin') --stdin-user USER set user USER in archive for stdin data (default: 'root') - --stdin-group GROUP set group GROUP in archive for stdin data (default: 'root') + --stdin-group GROUP set group GROUP in archive for stdin data (default: 'wheel') --stdin-mode M set mode to M in archive for stdin data (default: 0660) --content-from-command interpret PATH as command and store its stdout. See also section Reading from stdin below. --paths-from-stdin read DELIM-separated list of paths to backup from stdin. Will not recurse into directories. diff --git a/docs/usage/export-tar.rst.inc b/docs/usage/export-tar.rst.inc index 9fa16e40b..8a235ff27 100644 --- a/docs/usage/export-tar.rst.inc +++ b/docs/usage/export-tar.rst.inc @@ -89,11 +89,13 @@ By default (``--tar-filter=auto``) Borg will detect whether the FILE should be c based on its file extension and pipe the tarball through an appropriate filter before writing it to FILE: -- .tar.gz: gzip -- .tar.bz2: bzip2 -- .tar.xz: xz +- .tar.gz or .tgz: gzip +- .tar.bz2 or .tbz: bzip2 +- .tar.xz or .txz: xz +- .tar.zstd: zstd +- .tar.lz4: lz4 -Alternatively a ``--tar-filter`` program may be explicitly specified. It should +Alternatively, a ``--tar-filter`` program may be explicitly specified. It should read the uncompressed tar stream from stdin and write a compressed/filtered tar stream to stdout. diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc index 474dbe7d3..76e3e70b2 100644 --- a/docs/usage/extract.rst.inc +++ b/docs/usage/extract.rst.inc @@ -118,8 +118,4 @@ 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``. - - 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. + so make sure you ``cd`` to the right place before calling ``borg extract``.
\ No newline at end of file diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index a77816458..a477483c1 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -23,7 +23,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. +``--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 @@ -69,15 +71,12 @@ Regular expressions, selector `re:` the re module <https://docs.python.org/3/library/re.html>`_. Path prefix, selector `pp:` - This pattern style matches either the whole path or an initial segment - of the path up to but not including a path separator. For consistency - with the `fn:` and `sh:` patterns, a path separator is added to the - end of the path before matching. For example, `pp:root/somedir` - matches `root/somedir` and everything therein. A leading path - separator is always removed. A trailing slash makes no difference. + This pattern style is useful to match whole sub-directories. The pattern + `pp:root/somedir` matches `root/somedir` and everything therein. A leading + path separator is always removed. Path full-match, selector `pf:` - This pattern style is (only) useful to match full (exact) paths. + This pattern style is (only) useful to match full paths. This is kind of a pseudo pattern as it can not have any variable or unspecified parts - the full path must be given. `pf:root/file.ext` matches `root/file.ext` only. A leading path separator is always removed. @@ -139,8 +138,8 @@ Examples:: /home/*/junk *.tmp fm:aa:something/* - re:^home/[^/]\.tmp/ - sh:home/*/.thumbnails + re:^/home/[^/]+\.tmp/ + sh:/home/*/.thumbnails # Example with spaces, no need to escape as it is processed by borg some file with spaces.txt EOF @@ -167,12 +166,6 @@ 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/import-tar.rst.inc b/docs/usage/import-tar.rst.inc new file mode 100644 index 000000000..b0b5822a7 --- /dev/null +++ b/docs/usage/import-tar.rst.inc @@ -0,0 +1,117 @@ +.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! + +.. _borg_import-tar: + +borg import-tar +--------------- +.. code-block:: none + + borg [common options] import-tar [options] ARCHIVE TARFILE + +.. only:: html + + .. class:: borg-options-table + + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | **positional arguments** | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | | ``ARCHIVE`` | name of archive to create (must be also a valid directory name) | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | | ``TARFILE`` | input tar file. "-" to read from stdin instead. | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | **optional arguments** | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--tar-filter`` | filter program to pipe data through | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-s``, ``--stats`` | print statistics for the created archive | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--list`` | output verbose list of items (files, dirs, ...) | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--filter STATUSCHARS`` | only display items with the given status characters | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--json`` | output stats as JSON (implies --stats) | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | **Archive options** | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--comment COMMENT`` | add a comment text to the archive | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory. | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + + .. raw:: html + + <script type='text/javascript'> + $(document).ready(function () { + $('.borg-options-table colgroup').remove(); + }) + </script> + +.. only:: latex + + ARCHIVE + name of archive to create (must be also a valid directory name) + TARFILE + input tar file. "-" to read from stdin instead. + + + optional arguments + --tar-filter filter program to pipe data through + -s, --stats print statistics for the created archive + --list output verbose list of items (files, dirs, ...) + --filter STATUSCHARS only display items with the given status characters + --json output stats as JSON (implies --stats) + + + :ref:`common_options` + | + + Archive options + --comment COMMENT add a comment text to the archive + --timestamp TIMESTAMP manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory. + -c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800) + --chunker-params PARAMS specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 + -C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. + + +Description +~~~~~~~~~~~ + +This command creates a backup archive from a tarball. + +When giving '-' as path, Borg will read a tar stream from standard input. + +By default (--tar-filter=auto) Borg will detect whether the file is compressed +based on its file extension and pipe the file through an appropriate filter: + +- .tar.gz or .tgz: gzip -d +- .tar.bz2 or .tbz: bzip2 -d +- .tar.xz or .txz: xz -d +- .tar.zstd: zstd -d +- .tar.lz4: lz4 -d + +Alternatively, a --tar-filter program may be explicitly specified. It should +read compressed data from stdin and output an uncompressed tar stream on +stdout. + +Most documentation of borg create applies. Note that this command does not +support excluding files. + +import-tar is a lossy conversion: +BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported. +Timestamp resolution is limited to whole seconds, not the nanosecond resolution +otherwise supported by Borg. + +A ``--sparse`` option (as found in borg create) is not supported. + +import-tar reads POSIX.1-1988 (ustar), POSIX.1-2001 (pax), GNU tar, UNIX V7 tar +and SunOS tar with extended attributes.
\ No newline at end of file diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc index f26728678..7799b4daf 100644 --- a/docs/usage/list.rst.inc +++ b/docs/usage/list.rst.inc @@ -12,51 +12,51 @@ borg list .. class:: borg-options-table - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **positional arguments** | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``REPOSITORY_OR_ARCHIVE`` | repository or archive to list contents of | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``PATH`` | paths to list; patterns are supported | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **optional arguments** | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--consider-checkpoints`` | Show checkpoint archives in the repository contents list (default: hidden). | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--short`` | only print file/directory names, nothing else | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--format FORMAT``, ``--list-format FORMAT`` | specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {mtime} {path}{extra}{NL}") | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--json`` | Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available. | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--json-lines`` | Only valid for listing archive contents. Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **Archive filters** — Archive filters can be applied to repository targets. | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-P PREFIX``, ``--prefix PREFIX`` | only consider archive names starting with this prefix. | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--first N`` | consider first N archives after other filters were applied | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--last N`` | consider last N archives after other filters were applied | - +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **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** | + +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``REPOSITORY_OR_ARCHIVE`` | repository or archive to list contents of | + +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``PATH`` | paths to list; patterns are supported | + +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **optional arguments** | + +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--consider-checkpoints`` | Show checkpoint archives in the repository contents list (default: hidden). | + +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--short`` | only print file/directory names, nothing else | + +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--format FORMAT`` | specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}") | + +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--json`` | Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available. | + +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--json-lines`` | Only valid for listing archive contents. Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. | + +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Archive filters** — Archive filters can be applied to repository targets. | + +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-P PREFIX``, ``--prefix PREFIX`` | only consider archive names starting with this prefix. |