From 572e996d9a9479abb8c9e50a03d5b96ca413ef90 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sun, 23 Jan 2022 15:52:21 +0100 Subject: build_usage --- docs/usage/create.rst.inc | 4 +- docs/usage/export-tar.rst.inc | 10 ++-- docs/usage/extract.rst.inc | 6 +- docs/usage/help.rst.inc | 25 +++----- docs/usage/import-tar.rst.inc | 117 +++++++++++++++++++++++++++++++++++++ docs/usage/list.rst.inc | 132 +++++++++++++++++++++++++----------------- docs/usage/mount.rst.inc | 17 ++++++ docs/usage/prune.rst.inc | 4 +- 8 files changed, 235 insertions(+), 80 deletions(-) create mode 100644 docs/usage/import-tar.rst.inc 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 `_. 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 + + + +.. 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. | + +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-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 | + +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. raw:: html @@ -77,7 +77,7 @@ borg list 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}") + --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. @@ -109,17 +109,46 @@ See the "borg help patterns" command for more help on exclude patterns. .. man NOTES -The following keys are available for ``--format``: +The FORMAT specifier syntax ++++++++++++++++++++++++++++ + +The ``--format`` option uses python's `format string syntax +`_. + +Examples: +:: + + $ borg list --format '{archive}{NL}' /path/to/repo + ArchiveFoo + ArchiveBar + ... + + # {VAR:NUMBER} - pad to NUMBER columns. + # Strings are left-aligned, numbers are right-aligned. + # Note: time columns except ``isomtime``, ``isoctime`` and ``isoatime`` cannot be padded. + $ borg list --format '{archive:36} {time} [{id}]{NL}' /path/to/repo + ArchiveFoo Thu, 2021-12-09 10:22:28 [0b8e9a312bef3f2f6e2d0fc110c196827786c15eba0188738e81697a7fa3b274] + $ borg list --format '{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo + -rw-rw-r-- user user 1024 Thu, 2021-12-09 10:22:17 file-foo + ... + + # {VAR:NUMBER} - pad to NUMBER columns right-aligned. + $ borg list --format '{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo + -rw-rw-r-- user user 1024 Thu, 2021-12-09 10:22:17 file-foo + ... + +The following keys are always available: - NEWLINE: OS dependent line separator - NL: alias of NEWLINE -- NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath +- NUL: NUL character for creating print0 / xargs -0 like output, see barchive and bpath keys below - SPACE - TAB - CR - LF -Keys for listing repository archives: +Keys available only when listing archives in a repository: - archive: archive name interpreted as text (might be missing non-text characters, see barchive) - name: alias of "archive" @@ -131,12 +160,13 @@ Keys for listing repository archives: - start: time (start) of creation of the archive - time: alias of "start" - end: time (end) of creation of the archive +- command_line: command line which was used to create the archive - hostname: hostname of host on which this archive was created - username: username of user who created this archive -Keys for listing archive files: +Keys available only when listing files in an archive: - type - mode @@ -176,8 +206,6 @@ Keys for listing archive files: - sha3_384 - sha3_512 - sha512 -- shake_128 -- shake_256 - xxh64: XXH64 checksum of this file (note: this is NOT a cryptographic hash!) - archiveid diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc index bcf7358bf..0ac4caa48 100644 --- a/docs/usage/mount.rst.inc +++ b/docs/usage/mount.rst.inc @@ -124,6 +124,23 @@ To allow a regular user to use fstab entries, add the ``user`` option: For FUSE configuration and mount options, see the mount.fuse(8) manual page. +Borg's default behavior is to use the archived user and group names of each +file and map them to the system's respective user and group ids. +Alternatively, using ``numeric-ids`` will instead use the archived user and +group ids without any mapping. + +The ``uid`` and ``gid`` mount options (implemented by Borg) can be used to +override the user and group ids of all files (i.e., ``borg mount -o +uid=1000,gid=1000``). + +The man page references ``user_id`` and ``group_id`` mount options +(implemented by fuse) which specify the user and group id of the mount owner +(aka, the user who does the mounting). It is set automatically by libfuse (or +the filesystem if libfuse is not used). However, you should not specify these +manually. Unlike the ``uid`` and ``gid`` mount options which affect all files, +``user_id`` and ``group_id`` affect the user and group id of the mounted +(base) directory. + Additional mount options supported by borg: - versions: when used with a repository mount, this gives a merged, versioned diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index 808577327..b5bd5b421 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -103,7 +103,9 @@ any of the specified retention options. Important: Repository disk space is **not** freed until you run ``borg compact``. This command is normally used by automated backup scripts wanting to keep a -certain number of historic backups. +certain number of historic backups. This retention policy is commonly referred to as +`GFS `_ +(Grandfather-father-son) backup rotation scheme. Also, prune automatically removes checkpoint archives (incomplete archives left behind by interrupted backup runs) except if the checkpoint is the latest -- cgit v1.2.3