mirror of
https://github.com/borgbackup/borg.git
synced 2026-05-28 04:03:21 -04:00
build_usage
This commit is contained in:
Thomas Waldmann
parent
5b60761bd7
commit
572e996d9a
8 changed files with 235 additions and 80 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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``.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
117
docs/usage/import-tar.rst.inc
Normal file
117
docs/usage/import-tar.rst.inc
Normal file
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
<https://docs.python.org/3.8/library/string.html#formatstrings>`_.
|
||||
|
||||
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 left-aligned.
|
||||
# {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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 <https://en.wikipedia.org/wiki/Backup_rotation_scheme#Grandfather-father-son>`_
|
||||
(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
|
||||
|
|
|
|||
Loading…
Reference in a new issue