mirror
/
borg
mirror of https://github.com/borgbackup/borg.git
1
0
Fork 0
Code Issues Releases Wiki Activity

build_usage

This commit is contained in:
Thomas Waldmann 2023-06-11 23:09:20 +02:00
parent fbf463496b
commit 70602bda52
No known key found for this signature in database
GPG Key ID: 243ACFA951F78E01
15 changed files with 308 additions and 168 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/usage/common-options.rst.inc
View File

@ -18,4 +18,5 @@
--upload-buffer UPLOAD_BUFFER set network upload buffer size in MiB. (default: 0=no buffer)
--debug-profile FILE Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof".
--rsh RSH Use this command to connect to the 'borg serve' process (default: 'ssh')
--socket PATH Use UNIX DOMAIN (IPC) socket at PATH for client/server communication with socket: protocol.
-r REPO, --repo REPO repository to use

30
docs/usage/create.rst.inc
View File

@ -43,17 +43,17 @@ borg create
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--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 back up from stdin. Will not recurse into directories. |
| | ``--paths-from-stdin`` | read DELIM-separated list of paths to back up from stdin. All control is external: it will back up all files given - no more, no less. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--paths-from-command`` | interpret PATH as command and treat its output as ``--paths-from-stdin`` |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--paths-delimiter DELIM`` | set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: \n) |
| | ``--paths-delimiter DELIM`` | set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Exclusion options** |
| **Include/Exclude options** |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@ -73,7 +73,7 @@ borg create
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Filesystem options** |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-x``, ``--one-file-system`` | stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs. |
| | ``-x``, ``--one-file-system`` | stay in the same file system and do not store mount points of other file systems - this might behave different from your expectations, see the description below. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--numeric-ids`` | only store numeric user and group identifiers |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@ -138,15 +138,15 @@ borg create
--stdin-group GROUP set group GROUP in archive for stdin data (default: do not store group/gid)
--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 back up from stdin. Will not recurse into directories.
--paths-from-stdin read DELIM-separated list of paths to back up from stdin. All control is external: it will back up all files given - no more, no less.
--paths-from-command interpret PATH as command and treat its output as ``--paths-from-stdin``
--paths-delimiter DELIM set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: \n)
--paths-delimiter DELIM set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``)
:ref:`common_options`
|
Exclusion options
Include/Exclude options
-e PATTERN, --exclude PATTERN exclude paths matching PATTERN
--exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line
--pattern PATTERN include/exclude paths matching PATTERN
@ -158,7 +158,7 @@ borg create
Filesystem options
-x, --one-file-system stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs.
-x, --one-file-system stay in the same file system and do not store mount points of other file systems - this might behave different from your expectations, see the description below.
--numeric-ids only store numeric user and group identifiers
--atime do store atime into archive
--noctime do not store ctime into archive
@ -276,13 +276,13 @@ through using the ``--keep-exclude-tags`` option.
The ``-x`` or ``--one-file-system`` option excludes directories, that are mountpoints (and everything in them).
It detects mountpoints by comparing the device number from the output of ``stat()`` of the directory and its
parent directory. Specifically, it excludes directories for which ``stat()`` reports a device number different
from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories
with device number different from their parent, which the kernel does not consider a mountpoint and also the
other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL
subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when
using ``--one-file-system``, one should make doubly sure that the backup works as intended especially when using
btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution
installer.
from the device number of their parent.
In general: be aware that there are directories with device number different from their parent, which the kernel
does not consider a mountpoint and also the other way around.
Linux examples for this are bind mounts (possibly same device number, but always a mountpoint) and ALL
subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint).
macOS examples are the apfs mounts of a typical macOS installation.
Therefore, when using ``--one-file-system``, you should double-check that the backup works as intended.
.. _list_item_flags:

3
docs/usage/delete.rst.inc
View File

@ -23,8 +23,6 @@ borg delete
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics for the deleted archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--cache-only`` | delete only the local cache for the given repository |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--force`` | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) |
@ -69,7 +67,6 @@ borg delete
--list output verbose list of archives
--consider-checkpoints consider checkpoint archives for deletion (default: not considered).
-s, --stats print statistics for the deleted archive
--cache-only delete only the local cache for the given repository
--force force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
-c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800)

140
docs/usage/diff.rst.inc
View File

@ -12,39 +12,43 @@ borg diff
.. class:: borg-options-table
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``ARCHIVE1`` | ARCHIVE1 name |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``ARCHIVE2`` | ARCHIVE2 name |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``PATH`` | paths of items inside the archives to compare; patterns are supported |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--numeric-ids`` | only consider numeric user and group identifiers |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--same-chunker-params`` | Override check of chunker parameters. |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--sort`` | Sort the output lines by file path. |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--json-lines`` | Format output as JSON Lines. |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| **Exclusion options** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--pattern PATTERN`` | include/exclude paths matching PATTERN |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``ARCHIVE1`` | ARCHIVE1 name |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``ARCHIVE2`` | ARCHIVE2 name |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``PATH`` | paths of items inside the archives to compare; patterns are supported |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--numeric-ids`` | only consider numeric user and group identifiers |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--same-chunker-params`` | Override check of chunker parameters. |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--sort`` | Sort the output lines by file path. |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--format FORMAT`` | specify format for differences between archives (default: "{change} {path}{NL}") |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--json-lines`` | Format output as JSON Lines. |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--content-only`` | Only compare differences in content (exclude metadata differences) |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| **Include/Exclude options** |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--pattern PATTERN`` | include/exclude paths matching PATTERN |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
.. raw:: html
@ -68,13 +72,15 @@ borg diff
--numeric-ids only consider numeric user and group identifiers
--same-chunker-params Override check of chunker parameters.
--sort Sort the output lines by file path.
--format FORMAT specify format for differences between archives (default: "{change} {path}{NL}")
--json-lines Format output as JSON Lines.
--content-only Only compare differences in content (exclude metadata differences)
:ref:`common_options`
|
Exclusion options
Include/Exclude options
-e PATTERN, --exclude PATTERN exclude paths matching PATTERN
--exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line
--pattern PATTERN include/exclude paths matching PATTERN
@ -84,19 +90,61 @@ borg diff
Description
~~~~~~~~~~~
This command finds differences (file contents, user/group/mode) between archives.
This command finds differences (file contents, metadata) between ARCHIVE1 and ARCHIVE2.
A repository location and an archive name must be specified for REPO::ARCHIVE1.
ARCHIVE2 is just another archive name in same repository (no repository location
allowed).
For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
For archives created with Borg 1.1 or newer diff automatically detects whether
the archives are created with the same chunker params. If so, only chunk IDs
are compared, which is very fast.
.. man NOTES
For archives prior to Borg 1.1 chunk contents are compared by default.
If you did not create the archives with different chunker params,
pass ``--same-chunker-params``.
Note that the chunker params changed from Borg 0.xx to 1.0.
The FORMAT specifier syntax
+++++++++++++++++++++++++++
For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
The ``--format`` option uses python's `format string syntax
<https://docs.python.org/3.9/library/string.html#formatstrings>`_.
Examples:
::
$ borg diff --format '{content:30} {path}{NL}' ArchiveFoo ArchiveBar
modified: +4.1 kB -1.0 kB file-diff
...
# {VAR:<NUMBER} - pad to NUMBER columns left-aligned.
# {VAR:>NUMBER} - pad to NUMBER columns right-aligned.
$ borg diff --format '{content:>30} {path}{NL}' ArchiveFoo ArchiveBar
modified: +4.1 kB -1.0 kB file-diff
...
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
- SPACE: space character
- TAB: tab character
- CR: carriage return character
- LF: line feed character
Keys available only when showing differences between archives:
- path: archived file path
- change: all available changes
- content: file content change
- mode: file mode change
- type: file type change
- owner: file owner (user/group) change
- group: file group change
- user: file user change
- link: file link change
- directory: file directory change
- blkdev: file block device change
- chrdev: file character device change
- fifo: file fifo change
- mtime: file modification time change
- ctime: file change time change
- isomtime: file modification time change (ISO 8601)
- isoctime: file creation time change (ISO 8601)

4
docs/usage/export-tar.rst.inc
View File

@ -33,7 +33,7 @@ borg export-tar
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| **Exclusion options** |
| **Include/Exclude options** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@ -73,7 +73,7 @@ borg export-tar
:ref:`common_options`
|
Exclusion options
Include/Exclude options
-e PATTERN, --exclude PATTERN exclude paths matching PATTERN
--exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line
--pattern PATTERN include/exclude paths matching PATTERN

7
docs/usage/extract.rst.inc
View File

@ -37,11 +37,13 @@ borg extract
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--sparse`` | create holes in output sparse file from all-zero chunks |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--continue`` | continue a previously interrupted extraction of same archive |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| **Exclusion options** |
| **Include/Exclude options** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@ -79,12 +81,13 @@ borg extract
--noxattrs do not extract/set xattrs
--stdout write all extracted data to stdout
--sparse create holes in output sparse file from all-zero chunks
--continue continue a previously interrupted extraction of same archive
:ref:`common_options`
|
Exclusion options
Include/Exclude options
-e PATTERN, --exclude PATTERN exclude paths matching PATTERN
--exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line
--pattern PATTERN include/exclude paths matching PATTERN

91
docs/usage/help.rst.inc
View File

@ -24,15 +24,13 @@ confuse the root with the ``PATH`` argument of e.g. `borg extract`.
Starting with Borg 1.2, paths that are matched against patterns always
appear relative. If you give ``/absolute/`` as root, the paths going
into the matcher will look relative like ``absolute/.../file.ext``.
If you give ``../some/path`` as root, the paths will look like
``some/path/.../file.ext``.
into the matcher will start with ``absolute/``.
If you give ``../../relative`` as root, the paths will be normalized
as ``relative/``.
File patterns support five different styles. If followed by a colon ':',
the first two characters of a pattern are used as a style selector.
Explicit style selection is necessary if a non-default style is desired
or when the desired pattern starts with two alphanumeric characters
followed by a colon (i.e. ``aa:something/*``).
Borg supports different pattern styles. To define a non-default
style for a specific pattern, prefix it with two characters followed
by a colon ':' (i.e. ``fm:path/*``, ``sh:path/**``).
`Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector ``fm:``
This is the default style for ``--exclude`` and ``--exclude-from``.
@ -55,7 +53,8 @@ Shell-style patterns, selector ``sh:``
Like fnmatch patterns these are similar to shell patterns. The difference
is that the pattern may include ``**/`` for matching zero or more directory
levels, ``*`` for matching zero or more arbitrary characters with the
exception of any path separator. A leading path separator is always removed.
exception of any path separator, ``{}`` containing comma-separated
alternative patterns. A leading path separator is always removed.
`Regular expressions <https://docs.python.org/3/library/re.html>`_, selector ``re:``
Unlike shell patterns, regular expressions are not required to match the full
@ -175,6 +174,25 @@ before an exclude pattern, the file is backed up. Note that a no-recurse
exclude stops examination of subdirectories so that potential includes
will not match - use normal excludes for such use cases.
Example::
# Define the recursion root
R /
# Exclude all iso files in any directory
- **/*.iso
# Explicitly include all inside etc and root
+ etc/**
+ root/**
# Exclude a specific directory under each user's home directories
- home/*/.cache
# Explicitly include everything in /home
+ home/**
# Explicitly exclude some directories without recursing into them
! re:^(dev|proc|run|sys|tmp)
# Exclude all other files and directories
# that are not specifically included earlier.
- **
**Tip: You can easily test your patterns with --dry-run and --list**::
$ borg create --dry-run --list --patterns-from patterns.txt archive
@ -393,29 +411,44 @@ auto,C[,L]
obfuscate,SPEC,C[,L]
Use compressed-size obfuscation to make fingerprinting attacks based on
the observable stored chunk size more difficult.
Note:
- you must combine this with encryption or it won't make any sense.
- your repo size will be bigger, of course.
the observable stored chunk size more difficult. Note:
The SPEC value will determine how the size obfuscation will work:
- You must combine this with encryption, or it won't make any sense.
- Your repo size will be bigger, of course.
- A chunk is limited by the constant ``MAX_DATA_SIZE`` (cur. ~20MiB).
The SPEC value determines how the size obfuscation works:
*Relative random reciprocal size variation* (multiplicative)
Relative random reciprocal size variation:
Size will increase by a factor, relative to the compressed data size.
Smaller factors are often used, larger factors rarely.
1: factor 0.01 .. 100.0
2: factor 0.1 .. 1000.0
3: factor 1.0 .. 10000.0
4: factor 10.0 .. 100000.0
5: factor 100.0 .. 1000000.0
6: factor 1000.0 .. 10000000.0
Smaller factors are used often, larger factors rarely.
Add a randomly sized padding up to the given size:
110: 1kiB
...
120: 1MiB
...
123: 8MiB (max.)
Available factors::
1: 0.01 .. 100
2: 0.1 .. 1,000
3: 1 .. 10,000
4: 10 .. 100,000
5: 100 .. 1,000,000
6: 1,000 .. 10,000,000
Example probabilities for SPEC ``1``::
90 % 0.01 .. 0.1
9 % 0.1 .. 1
0.9 % 1 .. 10
0.09% 10 .. 100
*Randomly sized padding up to the given size* (additive)
::
110: 1kiB (2 ^ (SPEC - 100))
...
120: 1MiB
...
123: 8MiB (max.)
Examples::
@ -426,7 +459,7 @@ Examples::
borg create --compression zlib,1 REPO::ARCHIVE data
borg create --compression auto,lzma,6 REPO::ARCHIVE data
borg create --compression auto,lzma ...
borg create --compression obfuscate,3,none ...
borg create --compression obfuscate,110,none ...
borg create --compression obfuscate,3,auto,zstd,10 ...
borg create --compression obfuscate,2,zstd,6 ...

7
docs/usage/import-tar.rst.inc
View File

@ -31,6 +31,8 @@ borg import-tar
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--json`` | output stats as JSON (implies --stats) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--ignore-zeros`` | ignore zero-filled blocks in the input tarball |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
@ -72,6 +74,7 @@ borg import-tar
--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)
--ignore-zeros ignore zero-filled blocks in the input tarball
:ref:`common_options`
@ -121,3 +124,7 @@ import-tar reads these tar formats:
- POSIX.1-1988 (ustar)
- UNIX V7 tar
- SunOS tar with extended attributes
To import multiple tarballs into a single archive, they can be simply
concatenated (e.g. using "cat") into a single file, and imported with an
``--ignore-zeros`` option to skip through the stop markers between them.

45
docs/usage/list.rst.inc
View File

@ -31,7 +31,7 @@ borg list
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Exclusion options** |
| **Include/Exclude options** |
+-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
+-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@ -67,7 +67,7 @@ borg list
:ref:`common_options`
|
Exclusion options
Include/Exclude options
-e PATTERN, --exclude PATTERN exclude paths matching PATTERN
--exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line
--pattern PATTERN include/exclude paths matching PATTERN
@ -107,35 +107,36 @@ 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
- SPACE
- TAB
- CR
- LF
- SPACE: space character
- TAB: tab character
- CR: carriage return character
- LF: line feed character
Keys available only when listing files in an archive:
- type
- mode
- uid
- gid
- user
- group
- type: file type (file, dir, symlink, ...)
- mode: file mode (as in stat)
- uid: user id of file owner
- gid: group id of file owner
- user: user name of file owner
- group: group name of file owner
- path: file path
- target: link target for symlinks
- hlid: hard link identity (same if hardlinking same fs object)
- flags
- flags: file flags
- size
- size: file size
- dsize: deduplicated size
- num_chunks: number of chunks in this file
- unique_chunks: number of unique chunks in this file
- mtime
- ctime
- atime
- isomtime
- isoctime
- isoatime
- mtime: file modification time
- ctime: file change time
- atime: file access time
- isomtime: file modification time (ISO 8601 format)
- isoctime: file change time (ISO 8601 format)
- isoatime: file access time (ISO 8601 format)
- blake2b
- blake2s
@ -151,8 +152,8 @@ Keys available only when listing files in an archive:
- sha512
- xxh64: XXH64 checksum of this file (note: this is NOT a cryptographic hash!)
- archiveid
- archivename
- archiveid: internal ID of the archive
- archivename: name of the archive
- extra: prepends {target} with " -> " for soft links and " link to " for hard links
- health: either "healthy" (file ok) or "broken" (if file has all-zero replacement chunks)

16
docs/usage/mount.rst.inc
View File

@ -51,7 +51,7 @@ borg mount
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| **Exclusion options** |
| **Include/Exclude options** |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
@ -101,7 +101,7 @@ borg mount
--newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m.
Exclusion options
Include/Exclude options
-e PATTERN, --exclude PATTERN exclude paths matching PATTERN
--exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line
--pattern PATTERN include/exclude paths matching PATTERN
@ -148,14 +148,14 @@ manually. Unlike the ``uid`` and ``gid`` mount options which affect all files,
Additional mount options supported by borg:
- versions: when used with a repository mount, this gives a merged, versioned
- ``versions``: when used with a repository mount, this gives a merged, versioned
view of the files in the archives. EXPERIMENTAL, layout may change in future.
- allow_damaged_files: by default damaged files (where missing chunks were
replaced with runs of zeros by borg check ``--repair``) are not readable and
- ``allow_damaged_files``: by default damaged files (where missing chunks were
replaced with runs of zeros by ``borg check --repair``) are not readable and
return EIO (I/O error). Set this option to read such files.
- ignore_permissions: for security reasons the "default_permissions" mount
option is internally enforced by borg. "ignore_permissions" can be given to
not enforce "default_permissions".
- ``ignore_permissions``: for security reasons the ``default_permissions`` mount
option is internally enforced by borg. ``ignore_permissions`` can be given to
not enforce ``default_permissions``.
The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users
to tweak the performance. It sets the number of cached data chunks; additional

18
docs/usage/prune.rst.inc
View File

@ -23,6 +23,14 @@ borg prune
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of archives it keeps/prunes |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--short`` | use a less wide archive part format |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--list-pruned`` | output verbose list of archives it prunes |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--list-kept`` | output verbose list of archives it keeps |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--format FORMAT`` | specify format for the archive part (default: "{archive:<36} {time} [{id}]") |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--keep-within INTERVAL`` | keep all archives within this time interval |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--keep-last``, ``--keep-secondly`` | number of secondly archives to keep |
@ -75,6 +83,10 @@ borg prune
--force force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
-s, --stats print statistics for the deleted archive
--list output verbose list of archives it keeps/prunes
--short use a less wide archive part format
--list-pruned output verbose list of archives it prunes
--list-kept output verbose list of archives it keeps
--format FORMAT specify format for the archive part (default: "{archive:<36} {time} [{id}]")
--keep-within INTERVAL keep all archives within this time interval
--keep-last, --keep-secondly number of secondly archives to keep
--keep-minutely number of minutely archives to keep
@ -153,4 +165,8 @@ backup archive in the same second).
When using ``--stats``, you will get some statistics about how much data was
deleted - the "Deleted data" deduplicated size there is most interesting as
that is how much your repository will shrink.
Please note that the "All archives" stats refer to the state after pruning.
Please note that the "All archives" stats refer to the state after pruning.
You can influence how the ``--list`` output is formatted by using the ``--short``
option (less wide output) or by giving a custom format using ``--format`` (see
the ``borg rlist`` description for more details about the format string).

4
docs/usage/recreate.rst.inc
View File

@ -31,7 +31,7 @@ borg recreate
| |
| :ref:`common_options` |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Exclusion options** |
| **Include/Exclude options** |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@ -106,7 +106,7 @@ borg recreate
:ref:`common_options`
|
Exclusion options
Include/Exclude options
-e PATTERN, --exclude PATTERN exclude paths matching PATTERN
--exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line
--pattern PATTERN include/exclude paths matching PATTERN

12
docs/usage/rlist.rst.inc
View File

@ -112,10 +112,11 @@ 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
- SPACE
- TAB
- CR
- LF
- SPACE: space character
- TAB: tab character
- CR: carriage return character
- LF: line feed character
Keys available only when listing archives in a repository:
@ -131,3 +132,6 @@ Keys available only when listing archives in a repository:
- hostname: hostname of host on which this archive was created
- username: username of user who created this archive
- size: size of this archive (data plus metadata, not considering compression and deduplication)
- nfiles: count of files in this archive

12
docs/usage/serve.rst.inc
View File

@ -53,4 +53,14 @@ borg serve
Description
~~~~~~~~~~~
This command starts a repository server process. This command is usually not used manually.
This command starts a repository server process.
borg serve can currently support:
- Getting automatically started via ssh when the borg client uses a ssh://...
remote repository. In this mode, `borg serve` will live until that ssh connection
gets terminated.
- Getting started by some other means (not by the borg client) as a long-running socket
server to be used for borg clients using a socket://... repository (see the `--socket`
option if you do not want to use the default path for the socket and pid file).

86
docs/usage/transfer.rst.inc
View File

@ -12,37 +12,41 @@ borg transfer
.. class:: borg-options-table
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| **options** |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change repository, just check |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--other-repo SRC_REPOSITORY`` | transfer archives from the other repository |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--upgrader UPGRADER`` | use the upgrader to convert transferred data (default: no conversion) |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--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 |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change repository, just check |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--other-repo SRC_REPOSITORY`` | transfer archives from the other repository |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--upgrader UPGRADER`` | use the upgrader to convert transferred data (default: no conversion) |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--recompress MODE`` | recompress data chunks according to `MODE` and ``--compression``. Possible modes are `always`: recompress unconditionally; and `never`: do not recompress (faster: re-uses compressed data chunks w/o change).If no MODE is given, `always` will be used. Not passing --recompress is equivalent to "--recompress never". |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--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 |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@ -60,6 +64,8 @@ borg transfer
-n, --dry-run do not change repository, just check
--other-repo SRC_REPOSITORY transfer archives from the other repository
--upgrader UPGRADER use the upgrader to convert transferred data (default: no conversion)
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
--recompress MODE recompress data chunks according to `MODE` and ``--compression``. Possible modes are `always`: recompress unconditionally; and `never`: do not recompress (faster: re-uses compressed data chunks w/o change).If no MODE is given, `always` will be used. Not passing --recompress is equivalent to "--recompress never".
:ref:`common_options`
@ -81,6 +87,14 @@ Description
This command transfers archives from one repository to another repository.
Optionally, it can also upgrade the transferred data.
Optionally, it can also recompress the transferred data.
It is easiest (and fastest) to give ``--compression=COMPRESSION --recompress=never`` using
the same COMPRESSION mode as in the SRC_REPO - borg will use that COMPRESSION for metadata (in
any case) and keep data compressed "as is" (saves time as no data compression is needed).
If you want to globally change compression while transferring archives to the DST_REPO,
give ``--compress=WANTED_COMPRESSION --recompress=always``.
Suggested use for general purpose archive transfer (not repo upgrades)::
@ -96,11 +110,17 @@ Suggested use for general purpose archive transfer (not repo upgrades)::
The default is to transfer all archives, including checkpoint archives.
You could use the misc. archive filter options to limit which archives it will
transfer, e.g. using the -a option. This is recommended for big
transfer, e.g. using the ``-a`` option. This is recommended for big
repositories with multiple data sets to keep the runtime per invocation lower.
For repository upgrades (e.g. from a borg 1.2 repo to a related borg 2.0 repo), usage is
quite similar to the above::
borg --repo=DST_REPO transfer --other-repo=SRC_REPO --upgrader=From12To20
# fast: compress metadata with zstd,3, but keep data chunks compressed as they are:
borg --repo=DST_REPO transfer --other-repo=SRC_REPO --upgrader=From12To20 \
--compress=zstd,3 --recompress=never
# compress metadata and recompress data with zstd,3
borg --repo=DST_REPO transfer --other-repo=SRC_REPO --upgrader=From12To20 \
--compress=zstd,3 --recompress=always