Merge pull request #5107 from ThomasWaldmann/update-docs

update docs

docs/man/borg-benchmark-crud.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK-CRUD 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-BENCHMARK-CRUD 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .

docs/man/borg-benchmark.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-BENCHMARK 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-benchmark \- benchmark command
 .

docs/man/borg-break-lock.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BREAK-LOCK 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .

docs/man/borg-check.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CHECK 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-CHECK 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .
@@ -40,24 +40,25 @@ The check command verifies the consistency of a repository and the corresponding
 First, the underlying repository data files are checked:
 .INDENT 0.0
 .IP \(bu 2
-For all segments the segment magic (header) is checked
+For all segments, the segment magic header is checked.
 .IP \(bu 2
-For all objects stored in the segments, all metadata (e.g. crc and size) and
+For all objects stored in the segments, all metadata (e.g. CRC and size) and
 all data is read. The read data is checked by size and CRC. Bit rot and other
 types of accidental damage can be detected this way.
 .IP \(bu 2
-If we are in repair mode and a integrity error is detected for a segment,
-we try to recover as many objects from the segment as possible.
+In repair mode, if an integrity error is detected in a segment, try to recover
+as many objects from the segment as possible.
 .IP \(bu 2
-In repair mode, it makes sure that the index is consistent with the data
-stored in the segments.
+In repair mode, make sure that the index is consistent with the data stored in
+the segments.
 .IP \(bu 2
-If you use a remote repo server via ssh:, the repo check is executed on the
-repo server without causing significant network traffic.
+If checking a remote repo via \fBssh:\fP, the repo check is executed on the server
+without causing significant network traffic.
 .IP \(bu 2
 The repository check can be skipped using the \fB\-\-archives\-only\fP option.
 .IP \(bu 2
-A repository check can be time consuming. Partial checks are possible with the \fB\-\-max\-duration\fP option.
+A repository check can be time consuming. Partial checks are possible with the
+\fB\-\-max\-duration\fP option.
 .UNINDENT
 .sp
 Second, the consistency and correctness of the archive metadata is verified:
@@ -66,46 +67,46 @@ Second, the consistency and correctness of the archive metadata is verified:
 Is the repo manifest present? If not, it is rebuilt from archive metadata
 chunks (this requires reading and decrypting of all metadata and data).
 .IP \(bu 2
-Check if archive metadata chunk is present. if not, remove archive from
-manifest.
+Check if archive metadata chunk is present; if not, remove archive from manifest.
 .IP \(bu 2
 For all files (items) in the archive, for all chunks referenced by these
-files, check if chunk is present.
-If a chunk is not present and we are in repair mode, replace it with a same\-size
-replacement chunk of zeros.
-If a previously lost chunk reappears (e.g. via a later backup) and we are in
-repair mode, the all\-zero replacement chunk will be replaced by the correct chunk.
-This requires reading of archive and file metadata, but not data.
+files, check if chunk is present. In repair mode, if a chunk is not present,
+replace it with a same\-size replacement chunk of zeroes. If a previously lost
+chunk reappears (e.g. via a later backup), in repair mode the all\-zero replacement
+chunk will be replaced by the correct chunk. This requires reading of archive and
+file metadata, but not data.
 .IP \(bu 2
-If we are in repair mode and we checked all the archives: delete orphaned
-chunks from the repo.
+In repair mode, when all the archives were checked, orphaned chunks are deleted
+from the repo. One cause of orphaned chunks are input file related errors (like
+read errors) in the archive creation process.
 .IP \(bu 2
-if you use a remote repo server via ssh:, the archive check is executed on
-the client machine (because if encryption is enabled, the checks will require
-decryption and this is always done client\-side, because key access will be
-required).
+If checking a remote repo via \fBssh:\fP, the archive check is executed on the
+client machine because it requires decryption, and this is always done client\-side
+as key access is needed.
 .IP \(bu 2
-The archive checks can be time consuming, they can be skipped using the
+The archive checks can be time consuming; they can be skipped using the
 \fB\-\-repository\-only\fP option.
 .UNINDENT
 .sp
-The \fB\-\-max\-duration\fP option can be used to split a long\-running repository check into multiple partial checks.
-After the given number of seconds the check is interrupted. The next partial check will continue where the
-previous one stopped, until the complete repository has been checked. Example: Assuming a full check took 7
-hours, then running a daily check with \-\-max\-duration=3600 (1 hour) would result in one full check per week.
+The \fB\-\-max\-duration\fP option can be used to split a long\-running repository check
+into multiple partial checks. After the given number of seconds the check is
+interrupted. The next partial check will continue where the previous one stopped,
+until the complete repository has been checked. Example: Assuming a full check took 7
+hours, then running a daily check with \-\-max\-duration=3600 (1 hour) resulted in one
+full check per week.
 .sp
-Attention: Partial checks can only do way less checks than a full check (only the CRC32 checks on segment file
-entries are done) and cannot be combined with \fB\-\-repair\fP\&. Partial checks may therefore be useful only with very
-large repositories where a full check would take too long. Doing a full repository check aborts a partial check;
-the next partial check will start from the beginning.
+Attention: Partial checks can only do way less checking than a full check (only the
+CRC32 checks on segment file entries are done), and cannot be combined with the
+\fB\-\-repair\fP option. Partial checks may therefore be useful only with very large
+repositories where a full check took too long. Doing a full repository check aborts a
+partial check; the next partial check will restart from the beginning.
 .sp
 The \fB\-\-verify\-data\fP 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
-tamper\-resistant as well, unless the attacker has access to the keys.
-.sp
-It is also very slow.
+tamper\-resistant as well, unless the attacker has access to the keys. It is also very
+slow.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.

docs/man/borg-common.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMMON 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-COMMON 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .
@@ -63,6 +63,9 @@ Output one JSON object per log line instead of formatted text.
 .BI \-\-lock\-wait \ SECONDS
 wait at most SECONDS for acquiring a repository/cache lock (default: 1).
 .TP
+.B \-\-bypass\-lock
+Bypass locking mechanism
+.TP
 .B \-\-show\-version
 show/log the borg version
 .TP

docs/man/borg-compact.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMPACT 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-COMPACT 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-compact \- compact segment files in the repository
 .

docs/man/borg-compression.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMPRESSION 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-COMPRESSION 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .

docs/man/borg-config.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CONFIG 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-CONFIG 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-config \- get, set, and delete values in a repository or cache config file
 .

docs/man/borg-create.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CREATE 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-CREATE 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .
@@ -201,7 +201,10 @@ do not store ctime into archive
 do not store birthtime (creation date) into archive
 .TP
 .B \-\-nobsdflags
-do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive
+deprecated, use \fB\-\-noflags\fP instead
+.TP
+.B \-\-noflags
+do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive
 .TP
 .BI \-\-files\-cache \ MODE
 operate files cache in MODE. default: ctime,size,inode

docs/man/borg-delete.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DELETE 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-DELETE 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .
@@ -40,9 +40,10 @@ This command deletes an archive from the repository or the complete repository.
 Important: When deleting archives, repository disk space is \fBnot\fP freed until
 you run \fBborg compact\fP\&.
 .sp
-If you delete the complete repository, the local cache for it (if any) is
-also deleted. Alternatively, you can delete just the local cache with the
-\fB\-\-cache\-only\fP option.
+When you delete a complete repository, the security info and local cache for it
+(if any) are also deleted. Alternatively, you can delete just the local cache
+with the \fB\-\-cache\-only\fP option, or keep the security info with the
+\fB\-\-keep\-security\-info\fP option.
 .sp
 When using \fB\-\-stats\fP, you will get some statistics about how much data was
 deleted \- the "Deleted data" deduplicated size there is most interesting as
@@ -85,6 +86,9 @@ delete only the local cache for the given repository
 .B \-\-force
 force deletion of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work.
 .TP
+.B \-\-keep\-security\-info
+keep the local security info when deleting a repository
+.TP
 .B \-\-save\-space
 work slower, but using less space
 .UNINDENT

docs/man/borg-diff.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DIFF 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-DIFF 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .

docs/man/borg-export-tar.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXPORT-TAR 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-EXPORT-TAR 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .

docs/man/borg-extract.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXTRACT 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-EXTRACT 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .
@@ -81,7 +81,10 @@ do not actually change any files
 only obey numeric user and group identifiers
 .TP
 .B \-\-nobsdflags
-do not extract/set bsdflags (e.g. NODUMP, IMMUTABLE)
+deprecated, use \fB\-\-noflags\fP instead
+.TP
+.B \-\-noflags
+do not extract/set flags (e.g. NODUMP, IMMUTABLE)
 .TP
 .B \-\-stdout
 write all extracted data to stdout

docs/man/borg-info.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INFO 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-INFO 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .

docs/man/borg-init.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INIT 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-INIT 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .

docs/man/borg-key-change-passphrase.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-key-change-passphrase \- Change repository key file passphrase
 .

docs/man/borg-key-export.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-EXPORT 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-KEY-EXPORT 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .

docs/man/borg-key-import.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-IMPORT 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-KEY-IMPORT 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .

docs/man/borg-key-migrate-to-repokey.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
 .

docs/man/borg-key.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-KEY 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-key \- Manage a keyfile or repokey of a repository
 .

docs/man/borg-list.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-LIST 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-LIST 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .
@@ -53,6 +53,9 @@ paths to list; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
+.B \-\-consider\-checkpoints
+Show checkpoint archives in the repository contents list (default: hidden).
+.TP
 .B \-\-short
 only print file/directory names, nothing else
 .TP

docs/man/borg-mount.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-MOUNT 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-MOUNT 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .
@@ -93,6 +93,9 @@ paths to extract; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
+.B \-\-consider\-checkpoints
+Show checkpoint archives in the repository contents list (default: hidden).
+.TP
 .B \-f\fP,\fB  \-\-foreground
 stay in foreground, do not daemonize
 .TP

docs/man/borg-patterns.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PATTERNS 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-PATTERNS 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .
@@ -127,6 +127,9 @@ selector prefix is also supported for patterns loaded from a file. Due to
 whitespace removal paths with whitespace at the beginning or end can only be
 excluded using regular expressions.
 .sp
+To test your exclusion patterns without performing an actual backup you can
+run \fBborg create \-\-list \-\-dry\-run ...\fP\&.
+.sp
 Examples:
 .INDENT 0.0
 .INDENT 3.5

docs/man/borg-placeholders.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PLACEHOLDERS 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-PLACEHOLDERS 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-placeholders \- Details regarding placeholders
 .

docs/man/borg-prune.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PRUNE 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-PRUNE 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .

docs/man/borg-recreate.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RECREATE 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-RECREATE 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .

docs/man/borg-rename.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RENAME 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-RENAME 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-rename \- Rename an existing archive
 .

docs/man/borg-serve.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-SERVE 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-SERVE 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .

docs/man/borg-umount.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UMOUNT 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-UMOUNT 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .

docs/man/borg-upgrade.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UPGRADE 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-UPGRADE 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-upgrade \- upgrade a repository from a previous version
 .

docs/man/borg-with-lock.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-WITH-LOCK 1 "2019-11-01" "" "borg backup tool"
+.TH BORG-WITH-LOCK 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .

docs/man/borg.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG 1 "2019-11-01" "" "borg backup tool"
+.TH BORG 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borg \- deduplicating and encrypting backup tool
 .
@@ -465,9 +465,6 @@ in systemd.nspawn containers on some architectures (e.g. ARM).
 Using this does not affect data safety, but might result in a more bursty
 write to disk behaviour (not continuously streaming to disk).
 .UNINDENT
-.TP
-.B TMPDIR
-where temporary files are stored (might need a lot of temporary space for some operations), see \fI\%tempfile\fP for details
 .UNINDENT
 .TP
 .B Some automatic "answerers" (if set, they automatically answer confirmation questions):
@@ -492,31 +489,46 @@ For "recreate is an experimental feature."
 Note: answers are case sensitive. setting an invalid answer value might either give the default
 answer or ask you interactively, depending on whether retries are allowed (they by default are
 allowed). So please test your scripts interactively before making them a non\-interactive script.
+.UNINDENT
+.INDENT 0.0
 .TP
 .B Directories and files:
 .INDENT 7.0
 .TP
 .B BORG_BASE_DIR
-Default to \(aq$HOME\(aq, \(aq~$USER\(aq, \(aq~\(aq (in that order)\(aq.
-If we refer to ~ below, we in fact mean BORG_BASE_DIR.
-.TP
-.B BORG_CONFIG_DIR
-Default to \(aq~/.config/borg\(aq. This directory contains the whole config directories.
+Defaults to \fB$HOME\fP or \fB~$USER\fP or \fB~\fP (in that order).
+If you want to move all borg\-specific folders to a custom path at once, all you need to do is
+to modify \fBBORG_BASE_DIR\fP: the other paths for cache, config etc. will adapt accordingly
+(assuming you didn\(aqt set them to a different custom value).
 .TP
 .B BORG_CACHE_DIR
-Default to \(aq~/.cache/borg\(aq. This directory contains the local cache and might need a lot
-of space for dealing with big repositories.
+Defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
+\fI\%XDG env var\fP \fBXDG_CACHE_HOME\fP is set, then \fB$XDG_CACHE_HOME/borg\fP is being used instead.
+This directory contains the local cache and might need a lot
+of space for dealing with big repositories. Make sure you\(aqre aware of the associated
+security aspects of the cache location: \fIcache_security\fP
+.TP
+.B BORG_CONFIG_DIR
+Defaults to \fB$BORG_BASE_DIR/.config/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
+\fI\%XDG env var\fP \fBXDG_CONFIG_HOME\fP is set, then \fB$XDG_CONFIG_HOME/borg\fP is being used instead.
+This directory contains all borg configuration directories, see the FAQ
+for a security advisory about the data in this directory: \fIhome_config_borg\fP
 .TP
 .B BORG_SECURITY_DIR
-Default to \(aq~/.config/borg/security\(aq. This directory contains information borg uses to
-track its usage of NONCES ("numbers used once" \- usually in encryption context) and other
-security relevant data.
+Defaults to \fB$BORG_CONFIG_DIR/security\fP\&.
+This directory contains information borg uses to track its usage of NONCES ("numbers used
+once" \- usually in encryption context) and other security relevant data.
 .TP
 .B BORG_KEYS_DIR
-Default to \(aq~/.config/borg/keys\(aq. This directory contains keys for encrypted repositories.
+Defaults to \fB$BORG_CONFIG_DIR/keys\fP\&.
+This directory contains keys for encrypted repositories.
 .TP
 .B BORG_KEY_FILE
 When set, use the given filename as repository key file.
+.TP
+.B TMPDIR
+This is where temporary files are stored (might need a lot of temporary space for some
+operations), see \fI\%tempfile\fP for details.
 .UNINDENT
 .TP
 .B Building:
@@ -542,10 +554,10 @@ will be linked against the system libzstd instead of a bundled implementation. (
 Please note:
 .INDENT 0.0
 .IP \(bu 2
-be very careful when using the "yes" sayers, the warnings with prompt exist for your / your data\(aqs security/safety
+Be very careful when using the "yes" sayers, the warnings with prompt exist for your / your data\(aqs security/safety.
 .IP \(bu 2
-also be very careful when putting your passphrase into a script, make sure it has appropriate file permissions
-(e.g. mode 600, root:root).
+Also be very careful when putting your passphrase into a script, make sure it has appropriate file permissions (e.g.
+mode 600, root:root).
 .UNINDENT
 .SS File systems
 .sp
@@ -871,5 +883,7 @@ Security contact \fI\%https://borgbackup.readthedocs.io/en/latest/support.html#s
 .UNINDENT
 .SH AUTHOR
 The Borg Collective
+
+orphan: 
 .\" Generated by docutils manpage writer.
 .

docs/man/borgfs.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORGFS 1 "2019-11-01" "" "borg backup tool"
+.TH BORGFS 1 "2020-04-12" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .
@@ -96,6 +96,9 @@ paths to extract; patterns are supported
 .B \-V\fP,\fB  \-\-version
 show version number and exit
 .TP
+.B \-\-consider\-checkpoints
+Show checkpoint archives in the repository contents list (default: hidden).
+.TP
 .B \-f\fP,\fB  \-\-foreground
 stay in foreground, do not daemonize
 .TP

docs/usage/check.rst.inc

@@ -89,55 +89,56 @@ The check command verifies the consistency of a repository and the corresponding
 
 First, the underlying repository data files are checked:
 
-- For all segments the segment magic (header) is checked
-- For all objects stored in the segments, all metadata (e.g. crc and size) and
+- For all segments, the segment magic header is checked.
+- For all objects stored in the segments, all metadata (e.g. CRC and size) and
   all data is read. The read data is checked by size and CRC. Bit rot and other
   types of accidental damage can be detected this way.
-- If we are in repair mode and a integrity error is detected for a segment,
-  we try to recover as many objects from the segment as possible.
-- In repair mode, it makes sure that the index is consistent with the data
-  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.
+- In repair mode, if an integrity error is detected in a segment, try to recover
+  as many objects from the segment as possible.
+- In repair mode, make sure that the index is consistent with the data stored in
+  the segments.
+- If checking a remote repo via ``ssh:``, the repo check is executed on the server
+  without causing significant network traffic.
 - The repository check can be skipped using the ``--archives-only`` option.
-- A repository check can be time consuming. Partial checks are possible with the ``--max-duration`` option.
+- A repository check can be time consuming. Partial checks are possible with the
+  ``--max-duration`` option.
 
 Second, the consistency and correctness of the archive metadata is verified:
 
 - Is the repo manifest present? If not, it is rebuilt from archive metadata
   chunks (this requires reading and decrypting of all metadata and data).
-- Check if archive metadata chunk is present. if not, remove archive from
-  manifest.
+- Check if archive metadata chunk is present; if not, remove archive from manifest.
 - For all files (items) in the archive, for all chunks referenced by these
-  files, check if chunk is present.
-  If a chunk is not present and we are in repair mode, replace it with a same-size
-  replacement chunk of zeros.
-  If a previously lost chunk reappears (e.g. via a later backup) and we are in
-  repair mode, the all-zero replacement chunk will be replaced by the correct chunk.
-  This requires reading of archive and file metadata, but not data.
-- If we are in repair mode and we checked all the archives: delete orphaned
-  chunks from the repo.
-- if you use a remote repo server via ssh:, the archive check is executed on
-  the client machine (because if encryption is enabled, the checks will require
-  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
+  files, check if chunk is present. In repair mode, if a chunk is not present,
+  replace it with a same-size replacement chunk of zeroes. If a previously lost
+  chunk reappears (e.g. via a later backup), in repair mode the all-zero replacement
+  chunk will be replaced by the correct chunk. This requires reading of archive and
+  file metadata, but not data.
+- In repair mode, when all the archives were checked, orphaned chunks are deleted
+  from the repo. One cause of orphaned chunks are input file related errors (like
+  read errors) in the archive creation process.
+- If checking a remote repo via ``ssh:``, the archive check is executed on the
+  client machine because it requires decryption, and this is always done client-side
+  as key access is needed.
+- The archive checks can be time consuming; they can be skipped using the
   ``--repository-only`` option.
 
-The ``--max-duration`` option can be used to split a long-running repository check into multiple partial checks.
-After the given number of seconds the check is interrupted. The next partial check will continue where the
-previous one stopped, until the complete repository has been checked. Example: Assuming a full check took 7
-hours, then running a daily check with --max-duration=3600 (1 hour) would result in one full check per week.
+The ``--max-duration`` option can be used to split a long-running repository check
+into multiple partial checks. After the given number of seconds the check is
+interrupted. The next partial check will continue where the previous one stopped,
+until the complete repository has been checked. Example: Assuming a full check took 7
+hours, then running a daily check with --max-duration=3600 (1 hour) resulted in one
+full check per week.
 
-Attention: Partial checks can only do way less checks than a full check (only the CRC32 checks on segment file
-entries are done) and cannot be combined with ``--repair``. Partial checks may therefore be useful only with very
-large repositories where a full check would take too long. Doing a full repository check aborts a partial check;
-the next partial check will start from the beginning.
+Attention: Partial checks can only do way less checking than a full check (only the
+CRC32 checks on segment file entries are done), and cannot be combined with the
+``--repair`` option. Partial checks may therefore be useful only with very large
+repositories where a full check took too long. Doing a full repository check aborts a
+partial check; the next partial check will restart from the beginning.
 
 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
-tamper-resistant as well, unless the attacker has access to the keys.
-
-It is also very slow.
+tamper-resistant as well, unless the attacker has access to the keys. It is also very
+slow.

docs/usage/common-options.rst.inc

@@ -8,6 +8,7 @@
 -p, --progress     show progress information
 --log-json         Output one JSON object per log line instead of formatted text.
 --lock-wait SECONDS    wait at most SECONDS for acquiring a repository/cache lock (default: 1).
+--bypass-lock      Bypass locking mechanism
 --show-version     show/log the borg version
 --show-rc          show/log the return code (rc)
 --umask M          set umask to M (local and remote, default: 0077)

docs/usage/compact.rst.inc

@@ -12,19 +12,21 @@ borg compact
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+-----------------------+-------------------------------------------+
-    | **positional arguments**                                                                                                  |
-    +-------------------------------------------------------+-----------------------+-------------------------------------------+
-    |                                                       | ``REPOSITORY``        | repository to compact                     |
-    +-------------------------------------------------------+-----------------------+-------------------------------------------+
-    | **optional arguments**                                                                                                    |
-    +-------------------------------------------------------+-----------------------+-------------------------------------------+
-    |                                                       | ``--cleanup-commits`` | cleanup commit-only 17-byte segment files |
-    +-------------------------------------------------------+-----------------------+-------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                            |
-    |                                                                                                                           |
-    | :ref:`common_options`                                                                                                     |
-    +-------------------------------------------------------+-----------------------+-------------------------------------------+
+    +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
+    | **positional arguments**                                                                                                                         |
+    +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
+    |                                                       | ``REPOSITORY``          | repository to compact                                          |
+    +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
+    | **optional arguments**                                                                                                                           |
+    +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
+    |                                                       | ``--cleanup-commits``   | cleanup commit-only 17-byte segment files                      |
+    +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
+    |                                                       | ``--threshold PERCENT`` | set minimum threshold for saved space in PERCENT (Default: 10) |
+    +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                   |
+    |                                                                                                                                                  |
+    | :ref:`common_options`                                                                                                                            |
+    +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
 
     .. raw:: html
 
@@ -41,7 +43,8 @@ borg compact
 
 
     optional arguments
-        --cleanup-commits     cleanup commit-only 17-byte segment files
+        --cleanup-commits       cleanup commit-only 17-byte segment files
+        --threshold PERCENT     set minimum threshold for saved space in PERCENT (Default: 10)
 
 
     :ref:`common_options`
@@ -62,6 +65,8 @@ client or also from the server.
 Depending on the amount of segments that need compaction, it may take a while,
 so consider using the ``--progress`` option.
 
+A segment is compacted if the amount of saved space is above the percentage value
+given by the ``--threshold`` option. If ommitted, a threshold of 10% is used.
 When using ``--verbose``, borg will output an estimate of the freed space.
 
 After upgrading borg (server) to 1.2+, you can use ``borg compact --cleanup-commits``

docs/usage/create.rst.inc

@@ -71,7 +71,9 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--nobirthtime``                                 | do not store birthtime (creation date) into archive                                                                                               |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--nobsdflags``                                  | do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive                                                                              |
+    |                                                       | ``--nobsdflags``                                  | deprecated, use ``--noflags`` instead                                                                                                             |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--noflags``                                     | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive                                                                                 |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--files-cache MODE``                            | operate files cache in MODE. default: ctime,size,inode                                                                                            |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -137,7 +139,8 @@ borg create
         --atime                   do store atime into archive
         --noctime                 do not store ctime into archive
         --nobirthtime             do not store birthtime (creation date) into archive
-        --nobsdflags              do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive
+        --nobsdflags              deprecated, use ``--noflags`` instead
+        --noflags                 do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive
         --files-cache MODE        operate files cache in MODE. default: ctime,size,inode
         --read-special            open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.
 

docs/usage/delete.rst.inc

@@ -29,6 +29,8 @@ borg delete
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--force``                           | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.                                                       |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--keep-security-info``              | keep the local security info when deleting a repository                                                                                                |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--save-space``                      | work slower, but using less space                                                                                                                      |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                               |
@@ -69,6 +71,7 @@ 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.
+        --keep-security-info    keep the local security info when deleting a repository
         --save-space    work slower, but using less space
 
 
@@ -91,9 +94,10 @@ This command deletes an archive from the repository or the complete repository.
 Important: When deleting archives, repository disk space is **not** freed until
 you run ``borg compact``.
 
-If you delete the complete repository, the local cache for it (if any) is
-also deleted. Alternatively, you can delete just the local cache with the
-``--cache-only`` option.
+When you delete a complete repository, the security info and local cache for it
+(if any) are also deleted. Alternatively, you can delete just the local cache
+with the ``--cache-only`` option, or keep the security info with the
+``--keep-security-info`` option.
 
 When using ``--stats``, you will get some statistics about how much data was
 deleted - the "Deleted data" deduplicated size there is most interesting as

docs/usage/extract.rst.inc

@@ -27,7 +27,9 @@ borg extract
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``--numeric-owner``                   | only obey numeric user and group identifiers                                                              |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--nobsdflags``                      | do not extract/set bsdflags (e.g. NODUMP, IMMUTABLE)                                                      |
+    |                                                       | ``--nobsdflags``                      | deprecated, use ``--noflags`` instead                                                                     |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--noflags``                         | do not extract/set flags (e.g. NODUMP, IMMUTABLE)                                                         |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``--stdout``                          | write all extracted data to stdout                                                                        |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -70,7 +72,8 @@ borg extract
         --list            output verbose list of items (files, dirs, ...)
         -n, --dry-run     do not actually change any files
         --numeric-owner    only obey numeric user and group identifiers
-        --nobsdflags      do not extract/set bsdflags (e.g. NODUMP, IMMUTABLE)
+        --nobsdflags      deprecated, use ``--noflags`` instead
+        --noflags         do not extract/set flags (e.g. NODUMP, IMMUTABLE)
         --stdout          write all extracted data to stdout
         --sparse          create holes in output sparse file from all-zero chunks
 

docs/usage/help.rst.inc

@@ -96,6 +96,9 @@ selector prefix is also supported for patterns loaded from a file. Due to
 whitespace removal paths with whitespace at the beginning or end can only be
 excluded using regular expressions.
 
+To test your exclusion patterns without performing an actual backup you can
+run ``borg create --list --dry-run ...``.
+
 Examples::
 
     # Exclude '/home/user/file.o' but not '/home/user/file.odt':
@@ -134,6 +137,13 @@ Examples::
     A root path starts with the prefix `R`, followed by a path (a plain path, not a
     file pattern). An include rule starts with the prefix +, an exclude rule starts
     with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern.
+
+    .. note::
+
+        Via ``--pattern`` or ``--patterns-from`` you can define BOTH inclusion and exclusion
+        of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and
+        ``--exlude-from`` ONLY excludes are defined.
+
     Inclusion patterns are useful to include paths that are contained in an excluded
     path. The first matching pattern is used so if an include pattern matches before
     an exclude pattern, the file is backed up. If an exclude-norecurse pattern matches

docs/usage/list.rst.inc

@@ -21,6 +21,8 @@ borg list
     +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                                 |
     +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--consider-checkpoints``                    | Show checkpoint archives in the repository contents list (default: hidden).                                                                                                                                                                                              |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--short``                                   | only print file/directory names, nothing else                                                                                                                                                                                                                            |
     +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--format FORMAT``, ``--list-format FORMAT`` | specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {mtime} {path}{extra}{NL}")                                                                                                                                                               |
@@ -73,6 +75,7 @@ borg list
 
 
     optional arguments
+        --consider-checkpoints    Show checkpoint archives in the repository contents list (default: hidden).
         --short     only print file/directory names, nothing else
         --format FORMAT, --list-format FORMAT    specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {mtime} {path}{extra}{NL}")
         --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.

docs/usage/mount.rst.inc

@@ -23,6 +23,8 @@ borg mount
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **optional arguments**                                                                                                                                                                                                                                                       |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--consider-checkpoints``            | Show checkpoint archives in the repository contents list (default: hidden).                                                                            |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``-f``, ``--foreground``              | stay in foreground, do not daemonize                                                                                                                   |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``-o``                                | Extra mount options                                                                                                                                    |
@@ -75,6 +77,7 @@ borg mount
 
 
     optional arguments
+        --consider-checkpoints    Show checkpoint archives in the repository contents list (default: hidden).
         -f, --foreground    stay in foreground, do not daemonize
         -o     Extra mount options