upstream/borgbackup
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-02-23 01:41:25 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Merge pull request #2687 from enkore/docs/formatting-i2650

Browse source 
More consistent docs formatting
This commit is contained in:
enkore 2017-06-17 12:38:48 +02:00 committed by GitHub
commit a013bd7d75
20 changed files with 123 additions and 140 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
docs/borg_theme/css/borg.css
View file

@ -60,3 +60,21 @@ dt code {
border-left: 2px solid #4e4a4a;;
border-right: 2px solid #4e4a4a;;
}
p .literal,
p .literal span {
border: none;
padding: 0;
color: black; /* slight contrast with #404040 of regular text */
background: none;
}
cite {
white-space: nowrap;
color: black; /* slight contrast with #404040 of regular text */
font-size: 75%;
font-family: Consolas,"Andale Mono WT","Andale Mono","Lucida Console","Lucida Sans Typewriter",
"DejaVu Sans Mono","Bitstream Vera Sans Mono","Liberation Mono","Nimbus Mono L",Monaco,"Courier New",Courier,monospace;
font-style: normal;
text-decoration: underline;
}

4
docs/conf.py
View file

@ -152,9 +152,7 @@ html_last_updated_fmt = '%Y-%m-%d'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#
# This is disabled to avoid mangling --options-that-appear-in-texts.
html_use_smartypants = False
html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
html_sidebars = {

2
docs/deployment/central-backup-server.rst
View file

@ -55,7 +55,7 @@ Borg is instructed to restrict clients into their own paths:
The client will be able to access any file or subdirectory inside of ``/home/backup/repos/<client fqdn>``
but no other directories. You can allow a client to access several separate directories by passing multiple
`--restrict-to-path` flags, for instance: ``borg serve --restrict-to-path /home/backup/repos/<client fqdn> --restrict-to-path /home/backup/repos/<other client fqdn>``,
``--restrict-to-path`` flags, for instance: ``borg serve --restrict-to-path /home/backup/repos/<client fqdn> --restrict-to-path /home/backup/repos/<other client fqdn>``,
which could make sense if multiple machines belong to one person which should then have access to all the
backups of their machines.

4
docs/faq.rst
View file

@ -388,7 +388,7 @@ yet noticed on the server. Try these settings:
ClientAliveCountMax 3
If you have multiple borg create ... ; borg create ... commands in a already
serialized way in a single script, you need to give them --lock-wait N (with N
serialized way in a single script, you need to give them ``--lock-wait N`` (with N
being a bit more than the time the server needs to terminate broken down
connections and release the lock).
@ -440,7 +440,7 @@ Can I backup my root partition (/) with Borg?
Backing up your entire root partition works just fine, but remember to
exclude directories that make no sense to backup, such as /dev, /proc,
/sys, /tmp and /run, and to use --one-file-system if you only want to
/sys, /tmp and /run, and to use ``--one-file-system`` if you only want to
backup the root partition (and not any mounted devices e.g.).
If it crashes with a UnicodeError, what can I do?

56
docs/misc/compression.conf
View file

@ -1,56 +0,0 @@
# example config file for --compression-from option
#
# Format of non-comment / non-empty lines:
# <compression-spec>:<path/filename pattern>
# compression-spec is same format as for --compression option
# path/filename pattern is same format as for --exclude option
# archives / files:
none:*.gz
none:*.tgz
none:*.bz2
none:*.tbz2
none:*.xz
none:*.txz
none:*.lzma
none:*.lzo
none:*.zip
none:*.rar
none:*.7z
# audio:
none:*.mp3
none:*.ogg
none:*.oga
none:*.flac
none:*.aac
none:*.m4a
# video:
none:*.mp4
none:*.mkv
none:*.m4v
none:*.avi
none:*.mpg
none:*.mpeg
none:*.webm
none:*.vob
none:*.ts
none:*.ogv
none:*.mov
none:*.flv
none:*.ogm
# pictures/images
none:*.jpg
none:*.jpeg
none:*.png
none:*.gif
# disk images
none:*.dmg
# software archives
none:*.rpm
none:*.deb
none:*.msi

12
docs/usage/check.rst.inc
View file

@ -18,7 +18,7 @@ optional arguments
``--archives-only``
| only perform archives checks
``--verify-data``
| perform cryptographic archive data integrity verification (conflicts with --repository-only)
| perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)
``--repair``
| attempt to repair any inconsistencies found
``--save-space``
@ -29,7 +29,9 @@ optional arguments
filters
``-P``, ``--prefix``
| only consider archive names starting with this prefix
| only consider archive names starting with this prefix.
``-a``, ``--glob-archives``
| only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
``--sort-by``
| Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
``--first N``
@ -54,7 +56,7 @@ First, the underlying repository data files are checked:
stored in the segments.
- If you use a remote repo server via ssh:, the repo check is executed on the
repo server without causing significant network traffic.
- The repository check can be skipped using the --archives-only option.
- The repository check can be skipped using the ``--archives-only`` option.
Second, the consistency and correctness of the archive metadata is verified:
@ -76,9 +78,9 @@ Second, the consistency and correctness of the archive metadata is verified:
decryption and this is always done client-side, because key access will be
required).
- The archive checks can be time consuming, they can be skipped using the
--repository-only option.
``--repository-only`` option.
The --verify-data option will perform a full integrity verification (as opposed to
The ``--verify-data`` option will perform a full integrity verification (as opposed to
checking the CRC32 of the segment) of data, which means reading the data from the
repository, decrypting and decompressing it. This is a cryptographic verification,
which will detect (accidental) corruption. For encrypted repositories it is

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

@ -93,7 +93,7 @@ In the archive name, you may use the following placeholders:
{now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.
To speed up pulling backups over sshfs and similar network file systems which do
not provide correct inode information the --ignore-inode flag can be used. This
not provide correct inode information the ``--ignore-inode`` flag can be used. This
potentially decreases reliability of change detection, while avoiding always reading
all files on these file systems.
@ -102,7 +102,7 @@ creation of a new archive to ensure fast operation. This is because the file cac
is used to determine changed files quickly uses absolute filenames.
If this is not possible, consider creating a bind mount to a stable location.
The --progress option shows (from left to right) Original, Compressed and Deduplicated
The ``--progress`` option shows (from left to right) Original, Compressed and Deduplicated
(O, C and D, respectively), then the Number of files (N) processed so far, followed by
the currently processed path.
@ -111,8 +111,8 @@ See the output of the "borg help placeholders" command for more help on placehol
.. man NOTES
The --exclude patterns are not like tar. In tar --exclude .bundler/gems will
exclude foo/.bundler/gems. In borg it will not, you need to use --exclude
The ``--exclude`` patterns are not like tar. In tar ``--exclude`` .bundler/gems will
exclude foo/.bundler/gems. In borg it will not, you need to use ``--exclude``
'\*/.bundler/gems' to get the same effect. See ``borg help patterns`` for
more information.

4
docs/usage/delete.rst.inc
View file

@ -27,7 +27,9 @@ optional arguments
filters
``-P``, ``--prefix``
| only consider archive names starting with this prefix
| only consider archive names starting with this prefix.
``-a``, ``--glob-archives``
| only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
``--sort-by``
| Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
``--first N``

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

@ -58,7 +58,7 @@ are compared, which is very fast.
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.
pass ``--same-chunker-params``.
Note that the chunker params changed from Borg 0.xx to 1.0.
See the output of the "borg help patterns" command for more help on exclude patterns.

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

@ -42,7 +42,7 @@ This command creates a tarball from an archive.
When giving '-' as the output FILE, Borg will write a tar stream to standard output.
By default (--tar-filter=auto) Borg will detect whether the FILE should be compressed
By default (``--tar-filter=auto``) Borg will detect whether the FILE should be compressed
based on its file extension and pipe the tarball through an appropriate filter
before writing it to FILE:
@ -50,7 +50,7 @@ before writing it to FILE:
- .tar.bz2: bzip2
- .tar.xz: xz
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.
@ -61,7 +61,7 @@ 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 extract) is not supported.
A ``--sparse`` option (as found in borg extract) is not supported.
By default the entire archive is extracted but a subset of files and directories
can be selected by passing a list of ``PATHs`` as arguments.

4
docs/usage/info.rst.inc
View file

@ -21,7 +21,9 @@ optional arguments
filters
``-P``, ``--prefix``
| only consider archive names starting with this prefix
| only consider archive names starting with this prefix.
``-a``, ``--glob-archives``
| only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
``--sort-by``
| Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
``--first N``

7
docs/usage/init.rst.inc
View file

@ -84,7 +84,8 @@ Encryption modes
On modern Intel/AMD CPUs (except very cheap ones), AES is usually
hardware-accelerated.
BLAKE2b is faster than SHA256 on Intel/AMD 64-bit CPUs,
BLAKE2b is faster than SHA256 on Intel/AMD 64-bit CPUs
(except AMD Ryzen and future CPUs with SHA extensions),
which makes `authenticated-blake2` faster than `none` and `authenticated`.
On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster
@ -95,7 +96,7 @@ Hardware acceleration is always used automatically when available.
`repokey` and `keyfile` use AES-CTR-256 for encryption and HMAC-SHA256 for
authentication in an encrypt-then-MAC (EtM) construction. The chunk ID hash
is HMAC-SHA256 as well (with a separate key).
These modes are compatible with borg 1.0.x.
These modes are compatible with Borg 1.0.x.
`repokey-blake2` and `keyfile-blake2` are also authenticated encryption modes,
but use BLAKE2b-256 instead of HMAC-SHA256 for authentication. The chunk ID
@ -105,7 +106,7 @@ These modes are new and *not* compatible with Borg 1.0.x.
`authenticated` mode uses no encryption, but authenticates repository contents
through the same HMAC-SHA256 hash as the `repokey` and `keyfile` modes (it uses it
as the chunk ID hash). The key is stored like `repokey`.
This mode is new and *not* compatible with borg 1.0.x.
This mode is new and *not* compatible with Borg 1.0.x.
`authenticated-blake2` is like `authenticated`, but uses the keyed BLAKE2b-256 hash
from the other blake2 modes.

2
docs/usage/key_import.rst.inc
View file

@ -16,7 +16,7 @@ positional arguments
optional arguments
``--paper``
| interactively import from a backup done with --paper
| interactively import from a backup done with ``--paper``
:ref:`common_options`
|

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

@ -21,16 +21,18 @@ optional arguments
| specify format for file listing
| (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {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.
| 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.
| 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.
:ref:`common_options`
|
filters
``-P``, ``--prefix``
| only consider archive names starting with this prefix
| only consider archive names starting with this prefix.
``-a``, ``--glob-archives``
| only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
``--sort-by``
| Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
``--first N``
@ -63,7 +65,7 @@ See the "borg help patterns" command for more help on exclude patterns.
.. man NOTES
The following keys are available for --format:
The following keys are available for ``--format``:
- NEWLINE: OS dependent line separator
- NL: alias of NEWLINE
@ -108,12 +110,20 @@ Keys for listing archive files:
- isoctime
- isoatime
- blake2b
- blake2s
- md5
- sha1
- sha224
- sha256
- sha384
- sha3_224
- sha3_256
- sha3_384
- sha3_512
- sha512
- shake_128
- shake_256
- archiveid
- archivename

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

@ -25,7 +25,9 @@ optional arguments
filters
``-P``, ``--prefix``
| only consider archive names starting with this prefix
| only consider archive names starting with this prefix.
``-a``, ``--glob-archives``
| only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
``--sort-by``
| Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
``--first N``
@ -54,7 +56,7 @@ supported by borg:
- 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
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.
The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users

2
docs/usage/notes.rst
View file

@ -63,7 +63,7 @@ of them.
--read-special
~~~~~~~~~~~~~~
The --read-special option is special - you do not want to use it for normal
The ``--read-special`` option is special - you do not want to use it for normal
full-filesystem backups, but rather after carefully picking some targets for it.
The option ``--read-special`` triggers special treatment for block and char

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

@ -37,14 +37,18 @@ optional arguments
| number of monthly archives to keep
``-y``, ``--keep-yearly``
| number of yearly archives to keep
``-P``, ``--prefix``
| only consider archive names starting with this prefix
``--save-space``
| work slower, but using less space
:ref:`common_options`
|
filters
``-P``, ``--prefix``
| only consider archive names starting with this prefix.
``-a``, ``--glob-archives``
| only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
Description
~~~~~~~~~~~
@ -55,7 +59,7 @@ automated backup scripts wanting to keep a certain number of historic backups.
Also, prune automatically removes checkpoint archives (incomplete archives left
behind by interrupted backup runs) except if the checkpoint is the latest
archive (and thus still needed). Checkpoint archives are not considered when
comparing archive counts against the retention limits (--keep-X).
comparing archive counts against the retention limits (``--keep-X``).
If a prefix is set with -P, then only archives that start with the prefix are
considered for deletion and only those archives count towards the totals
@ -68,14 +72,14 @@ If you have multiple sequences of archives with different data sets (e.g.
from different machines) in one shared repository, use one prune call per
data set that matches only the respective archives using the -P option.
The "--keep-within" option takes an argument of the form "<int><char>",
where char is "H", "d", "w", "m", "y". For example, "--keep-within 2d" means
The ``--keep-within`` option takes an argument of the form "<int><char>",
where char is "H", "d", "w", "m", "y". For example, ``--keep-within 2d`` means
to keep all archives that were created within the past 48 hours.
"1m" is taken to mean "31d". The archives kept with this option do not
count towards the totals specified by any other options.
A good procedure is to thin out more and more the older your backups get.
As an example, "--keep-daily 7" means to keep the latest backup on each day,
As an example, ``--keep-daily 7`` means to keep the latest backup on each day,
up to 7 most recent days with backups (days without backups do not count).
The rules are applied from secondly to yearly, and backups selected by previous
rules do not count towards those of later rules. The time that each backup
@ -83,6 +87,6 @@ starts is used for pruning purposes. Dates and times are interpreted in
the local timezone, and weeks go from Monday to Sunday. Specifying a
negative number of archives to keep means that there is no limit.
The "--keep-last N" option is doing the same as "--keep-secondly N" (and it will
The ``--keep-last N`` option is doing the same as ``--keep-secondly N`` (and it will
keep the last N archives under the assumption that you do not create more than one
backup archive in the same second).

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

@ -37,7 +37,7 @@ Exclusion options
``--exclude-if-present NAME``
| exclude directories that are tagged by containing a filesystem object with the given NAME
``--keep-exclude-tags``, ``--keep-tag-files``
| if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
| if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
``--pattern PATTERN``
| experimental: include/exclude paths matching PATTERN
``--patterns-from PATTERNFILE``
@ -55,9 +55,9 @@ Archive options
``-C COMPRESSION``, ``--compression COMPRESSION``
| select compression algorithm, see the output of the "borg help compression" command for details.
``--recompress``
| recompress data chunks according to --compression if "if-different". When "always", chunks that are already compressed that way are not skipped, but compressed again. Only the algorithm is considered for "if-different", not the compression level (if any).
| recompress data chunks according to ``--compression`` if `if-different`. When `always`, chunks that are already compressed that way are not skipped, but compressed again. Only the algorithm is considered for `if-different`, not the compression level (if any).
``--chunker-params PARAMS``
| specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or "default" to use the current defaults. default: 19,23,21,4095
| specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: 19,23,21,4095
Description
~~~~~~~~~~~
@ -66,33 +66,33 @@ Recreate the contents of existing archives.
This is an *experimental* feature. Do *not* use this on your only backup.
--exclude, --exclude-from, --exclude-if-present, --keep-exclude-tags, and PATH
``--exclude``, ``--exclude-from``, ``--exclude-if-present``, ``--keep-exclude-tags``, and PATH
have the exact same semantics as in "borg create". If PATHs are specified the
resulting archive will only contain files from these PATHs.
Note that all paths in an archive are relative, therefore absolute patterns/paths
will *not* match (--exclude, --exclude-from, PATHs).
will *not* match (``--exclude``, ``--exclude-from``, PATHs).
--recompress allows to change the compression of existing data in archives.
``--recompress`` allows to change the compression of existing data in archives.
Due to how Borg stores compressed size information this might display
incorrect information for archives that were not recreated at the same time.
There is no risk of data loss by this.
--chunker-params will re-chunk all files in the archive, this can be
``--chunker-params`` will re-chunk all files in the archive, this can be
used to have upgraded Borg 0.xx or Attic archives deduplicate with
Borg 1.x archives.
**USE WITH CAUTION.**
Depending on the PATHs and patterns given, recreate can be used to permanently
delete files from archives.
When in doubt, use "--dry-run --verbose --list" to see how patterns/PATHS are
When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHS are
interpreted.
The archive being recreated is only removed after the operation completes. The
archive that is built during the operation exists at the same time at
"<ARCHIVE>.recreate". The new archive will have a different archive ID.
With --target the original archive is not replaced, instead a new archive is created.
With ``--target`` the original archive is not replaced, instead a new archive is created.
When rechunking space usage can be substantial, expect at least the entire
deduplicated size of the archives using the previous chunker params.

4
docs/usage_general.rst.inc
View file

@ -75,7 +75,7 @@ Type of log output
The log level of the builtin logging configuration defaults to WARNING.
This is because we want Borg to be mostly silent and only output
warnings, errors and critical messages, unless output has been requested
by supplying an option that implies output (eg, --list or --progress).
by supplying an option that implies output (e.g. ``--list`` or ``--progress``).
Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
@ -97,7 +97,7 @@ to get critical level output.
While you can set misc. log levels, do not expect that every command will
give different output on different log levels - it's just a possibility.
.. warning:: Options --critical and --error are provided for completeness,
.. warning:: Options ``--critical`` and ``--error`` are provided for completeness,
their usage is not recommended as you might miss important information.
Return codes

68
src/borg/archiver.py
View file

@ -2529,7 +2529,7 @@ class Archiver:
stored in the segments.
- If you use a remote repo server via ssh:, the repo check is executed on the
repo server without causing significant network traffic.
- The repository check can be skipped using the --archives-only option.
- The repository check can be skipped using the ``--archives-only`` option.
Second, the consistency and correctness of the archive metadata is verified:
@ -2551,9 +2551,9 @@ class Archiver:
decryption and this is always done client-side, because key access will be
required).
- The archive checks can be time consuming, they can be skipped using the
--repository-only option.
``--repository-only`` option.
The --verify-data option will perform a full integrity verification (as opposed to
The ``--verify-data`` option will perform a full integrity verification (as opposed to
checking the CRC32 of the segment) of data, which means reading the data from the
repository, decrypting and decompressing it. This is a cryptographic verification,
which will detect (accidental) corruption. For encrypted repositories it is
@ -2579,7 +2579,7 @@ class Archiver:
subparser.add_argument('--verify-data', dest='verify_data', action='store_true',
default=False,
help='perform cryptographic archive data integrity verification '
'(conflicts with --repository-only)')
'(conflicts with ``--repository-only``)')
subparser.add_argument('--repair', dest='repair', action='store_true',
default=False,
help='attempt to repair any inconsistencies found')
@ -2653,7 +2653,7 @@ class Archiver:
help='path to the backup')
subparser.add_argument('--paper', dest='paper', action='store_true',
default=False,
help='interactively import from a backup done with --paper')
help='interactively import from a backup done with ``--paper``')
change_passphrase_epilog = process_epilog("""
The key files used for repository encryption are optionally passphrase
@ -2725,7 +2725,7 @@ class Archiver:
{now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.
To speed up pulling backups over sshfs and similar network file systems which do
not provide correct inode information the --ignore-inode flag can be used. This
not provide correct inode information the ``--ignore-inode`` flag can be used. This
potentially decreases reliability of change detection, while avoiding always reading
all files on these file systems.
@ -2734,7 +2734,7 @@ class Archiver:
is used to determine changed files quickly uses absolute filenames.
If this is not possible, consider creating a bind mount to a stable location.
The --progress option shows (from left to right) Original, Compressed and Deduplicated
The ``--progress`` option shows (from left to right) Original, Compressed and Deduplicated
(O, C and D, respectively), then the Number of files (N) processed so far, followed by
the currently processed path.
@ -2743,8 +2743,8 @@ class Archiver:
.. man NOTES
The --exclude patterns are not like tar. In tar --exclude .bundler/gems will
exclude foo/.bundler/gems. In borg it will not, you need to use --exclude
The ``--exclude`` patterns are not like tar. In tar ``--exclude`` .bundler/gems will
exclude foo/.bundler/gems. In borg it will not, you need to use ``--exclude``
'\*/.bundler/gems' to get the same effect. See ``borg help patterns`` for
more information.
@ -2950,7 +2950,7 @@ class Archiver:
When giving '-' as the output FILE, Borg will write a tar stream to standard output.
By default (--tar-filter=auto) Borg will detect whether the FILE should be compressed
By default (``--tar-filter=auto``) Borg will detect whether the FILE should be compressed
based on its file extension and pipe the tarball through an appropriate filter
before writing it to FILE:
@ -2958,7 +2958,7 @@ class Archiver:
- .tar.bz2: bzip2
- .tar.xz: xz
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.
@ -2969,7 +2969,7 @@ class Archiver:
Timestamp resolution is limited to whole seconds, not the nanosecond resolution
otherwise supported by Borg.
A --sparse option (as found in borg extract) is not supported.
A ``--sparse`` option (as found in borg extract) is not supported.
By default the entire archive is extracted but a subset of files and directories
can be selected by passing a list of ``PATHs`` as arguments.
@ -3024,7 +3024,7 @@ class Archiver:
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.
pass ``--same-chunker-params``.
Note that the chunker params changed from Borg 0.xx to 1.0.
See the output of the "borg help patterns" command for more help on exclude patterns.
@ -3131,7 +3131,7 @@ class Archiver:
.. man NOTES
The following keys are available for --format:
The following keys are available for ``--format``:
""") + BaseFormatter.keys_help() + textwrap.dedent("""
@ -3157,13 +3157,13 @@ class Archiver:
(default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")""")
subparser.add_argument('--json', action='store_true',
help='Only valid for listing repository contents. Format output as JSON. '
'The form of --format is ignored, '
'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.')
subparser.add_argument('--json-lines', action='store_true',
help='Only valid for listing archive contents. Format output as JSON Lines. '
'The form of --format is ignored, '
'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.')
@ -3217,7 +3217,7 @@ class Archiver:
- 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
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.
The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users
@ -3312,7 +3312,7 @@ class Archiver:
Also, prune automatically removes checkpoint archives (incomplete archives left
behind by interrupted backup runs) except if the checkpoint is the latest
archive (and thus still needed). Checkpoint archives are not considered when
comparing archive counts against the retention limits (--keep-X).
comparing archive counts against the retention limits (``--keep-X``).
If a prefix is set with -P, then only archives that start with the prefix are
considered for deletion and only those archives count towards the totals
@ -3325,14 +3325,14 @@ class Archiver:
from different machines) in one shared repository, use one prune call per
data set that matches only the respective archives using the -P option.
The "--keep-within" option takes an argument of the form "<int><char>",
where char is "H", "d", "w", "m", "y". For example, "--keep-within 2d" means
The ``--keep-within`` option takes an argument of the form "<int><char>",
where char is "H", "d", "w", "m", "y". For example, ``--keep-within 2d`` means
to keep all archives that were created within the past 48 hours.
"1m" is taken to mean "31d". The archives kept with this option do not
count towards the totals specified by any other options.
A good procedure is to thin out more and more the older your backups get.
As an example, "--keep-daily 7" means to keep the latest backup on each day,
As an example, ``--keep-daily 7`` means to keep the latest backup on each day,
up to 7 most recent days with backups (days without backups do not count).
The rules are applied from secondly to yearly, and backups selected by previous
rules do not count towards those of later rules. The time that each backup
@ -3340,7 +3340,7 @@ class Archiver:
the local timezone, and weeks go from Monday to Sunday. Specifying a
negative number of archives to keep means that there is no limit.
The "--keep-last N" option is doing the same as "--keep-secondly N" (and it will
The ``--keep-last N`` option is doing the same as ``--keep-secondly N`` (and it will
keep the last N archives under the assumption that you do not create more than one
backup archive in the same second).
""")
@ -3496,33 +3496,33 @@ class Archiver:
This is an *experimental* feature. Do *not* use this on your only backup.
--exclude, --exclude-from, --exclude-if-present, --keep-exclude-tags, and PATH
``--exclude``, ``--exclude-from``, ``--exclude-if-present``, ``--keep-exclude-tags``, and PATH
have the exact same semantics as in "borg create". If PATHs are specified the
resulting archive will only contain files from these PATHs.
Note that all paths in an archive are relative, therefore absolute patterns/paths
will *not* match (--exclude, --exclude-from, PATHs).
will *not* match (``--exclude``, ``--exclude-from``, PATHs).
--recompress allows to change the compression of existing data in archives.
``--recompress`` allows to change the compression of existing data in archives.
Due to how Borg stores compressed size information this might display
incorrect information for archives that were not recreated at the same time.
There is no risk of data loss by this.
--chunker-params will re-chunk all files in the archive, this can be
``--chunker-params`` will re-chunk all files in the archive, this can be
used to have upgraded Borg 0.xx or Attic archives deduplicate with
Borg 1.x archives.
**USE WITH CAUTION.**
Depending on the PATHs and patterns given, recreate can be used to permanently
delete files from archives.
When in doubt, use "--dry-run --verbose --list" to see how patterns/PATHS are
When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHS are
interpreted.
The archive being recreated is only removed after the operation completes. The
archive that is built during the operation exists at the same time at
"<ARCHIVE>.recreate". The new archive will have a different archive ID.
With --target the original archive is not replaced, instead a new archive is created.
With ``--target`` the original archive is not replaced, instead a new archive is created.
When rechunking space usage can be substantial, expect at least the entire
deduplicated size of the archives using the previous chunker params.
@ -3563,7 +3563,7 @@ class Archiver:
'the given NAME')
exclude_group.add_argument('--keep-exclude-tags', '--keep-tag-files', dest='keep_exclude_tags',
action='store_true', default=False,
help='if tag objects are specified with --exclude-if-present, don\'t omit the tag '
help='if tag objects are specified with ``--exclude-if-present``, don\'t omit the tag '
'objects themselves from the backup archive')
exclude_group.add_argument('--pattern',
action=ArgparsePatternAction,
@ -3592,15 +3592,15 @@ class Archiver:
'"borg help compression" command for details.')
archive_group.add_argument('--recompress', dest='recompress', nargs='?', default='never', const='if-different',
choices=('never', 'if-different', 'always'),
help='recompress data chunks according to --compression if "if-different". '
'When "always", chunks that are already compressed that way are not skipped, '
'but compressed again. Only the algorithm is considered for "if-different", '
help='recompress data chunks according to ``--compression`` if `if-different`. '
'When `always`, chunks that are already compressed that way are not skipped, '
'but compressed again. Only the algorithm is considered for `if-different`, '
'not the compression level (if any).')
archive_group.add_argument('--chunker-params', dest='chunker_params',
type=ChunkerParams, default=CHUNKER_PARAMS,
metavar='PARAMS',
help='specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, '
'HASH_MASK_BITS, HASH_WINDOW_SIZE) or "default" to use the current defaults. '
'HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. '
'default: %d,%d,%d,%d' % CHUNKER_PARAMS)
subparser.add_argument('location', metavar='REPOSITORY_OR_ARCHIVE', nargs='?', default='',
@ -3880,7 +3880,7 @@ class Archiver:
group.add_argument('-a', '--glob-archives', dest='glob_archives', default=None,
help='only consider archive names matching the glob. '
'sh: rules apply, see "borg help patterns". '
'--prefix and --glob-archives are mutually exclusive.')
'``--prefix`` and ``--glob-archives`` are mutually exclusive.')
if sort_by:
sort_by_default = 'timestamp'