Merge pull request #4398 from ThomasWaldmann/rel120a2

Release 1.2.0a2

docs/changes.rst

@@ -171,8 +171,8 @@ The best check that everything is ok is to run a dry-run extraction::
 Changelog
 =========
 
-Version 1.2.0a2 and earlier (not released yet)
-----------------------------------------------
+Version 1.2.0a2 and earlier (2019-02-24)
+----------------------------------------
 
 Please note:
 

docs/man/borg-benchmark-crud.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK-CRUD 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-BENCHMARK-CRUD 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .
@@ -39,7 +39,7 @@ This command benchmarks borg CRUD (create, read, update, delete) operations.
 .sp
 It creates input data below the given PATH and backups this data into the given REPO.
 The REPO must already exist (it could be a fresh empty repo or an existing repo, the
-command will create / read / update / delete some archives named borg\-test\-data* there.
+command will create / read / update / delete some archives named borg\-benchmark\-crud* there.
 .sp
 Make sure you have free space there, you\(aqll need about 1GB each (+ overhead).
 .sp
@@ -60,13 +60,7 @@ C\-R\- == random files. no dedup, measuring throughput through all processing st
 .B R\- == borg extract (extract archive, dry\-run, do everything, but do not write files to disk)
 R\-Z\- == all zero files. Measuring heavily duplicated files.
 R\-R\- == random files. No duplication here, measuring throughput through all processing
-.IP "System Message: ERROR/3 (docs/virtmanpage.rst:, line 56)"
-Unexpected indentation.
-.INDENT 7.0
-.INDENT 3.5
 stages, except writing to disk.
-.UNINDENT
-.UNINDENT
 .TP
 .B U\- == borg create (2nd archive creation of unchanged input files, measure files cache speed)
 The throughput value is kind of virtual here, it does not actually read the file.

docs/man/borg-benchmark.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-BENCHMARK 1 "2019-02-24" "" "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 "2017-11-25" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2019-02-24" "" "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 "2017-11-25" "" "borg backup tool"
+.TH BORG-CHECK 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .

docs/man/borg-common.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMMON 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-COMMON 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .
@@ -83,6 +83,9 @@ treat part files like normal files (e.g. to list/extract them)
 .TP
 .BI \-\-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".
+.TP
+.BI \-\-rsh \ RSH
+Use this command to connect to the \(aqborg serve\(aq process (default: \(aqssh\(aq)
 .UNINDENT
 .SH SEE ALSO
 .sp

docs/man/borg-compact.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMPACT 1 "2018-07-14" "" "borg backup tool"
+.TH BORG-COMPACT 1 "2019-02-24" "" "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 "2017-11-25" "" "borg backup tool"
+.TH BORG-COMPRESSION 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .
@@ -50,7 +50,13 @@ Valid compression specifiers are:
 Do not compress.
 .TP
 .B lz4
-Use lz4 compression. High speed, low compression. (default)
+Use lz4 compression. Very high speed, very low compression. (default)
+.TP
+.B zstd[,L]
+Use zstd ("zstandard") compression, a modern wide\-range algorithm.
+If you do not explicitly give the compression level L (ranging from 1
+to 22), it will use level 3.
+Archives compressed with zstd are not compatible with borg < 1.1.4.
 .TP
 .B zlib[,L]
 Use zlib ("gz") compression. Medium speed, medium compression.
@@ -82,6 +88,8 @@ Examples:
 .nf
 .ft C
 borg create \-\-compression lz4 REPO::ARCHIVE data
+borg create \-\-compression zstd REPO::ARCHIVE data
+borg create \-\-compression zstd,10 REPO::ARCHIVE data
 borg create \-\-compression zlib REPO::ARCHIVE data
 borg create \-\-compression zlib,1 REPO::ARCHIVE data
 borg create \-\-compression auto,lzma,6 REPO::ARCHIVE data

docs/man/borg-config.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CONFIG 1 "2017-12-13" "" "borg backup tool"
+.TH BORG-CONFIG 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-config \- get, set, and delete values in a repository or cache config file
 .
@@ -32,16 +32,18 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg [common options] config [options] REPOSITORY NAME [VALUE]
+borg [common options] config [options] REPOSITORY [NAME] [VALUE]
 .SH DESCRIPTION
 .sp
 This command gets and sets options in a local repository or cache config file.
 For security reasons, this command only works on local repositories.
 .sp
-To delete a config value entirely, use \fB\-\-delete\fP\&. To get an existing key, pass
-only the key name. To set a key, pass both the key name and the new value. Keys
-can be specified in the format "section.name" or simply "name"; the section will
-default to "repository" and "cache" for the repo and cache configs, respectively.
+To delete a config value entirely, use \fB\-\-delete\fP\&. To list the values
+of the configuration file or the default values, use \fB\-\-list\fP\&.  To get and existing
+key, pass only the key name. To set a key, pass both the key name and
+the new value. Keys can be specified in the format "section.name" or
+simply "name"; the section will default to "repository" and "cache" for
+the repo and cache configs, respectively.
 .sp
 By default, borg config manipulates the repository config file. Using \fB\-\-cache\fP
 edits the repository cache\(aqs config file instead.
@@ -68,6 +70,9 @@ get and set values from the repo cache
 .TP
 .B \-d\fP,\fB  \-\-delete
 delete the key from the config file
+.TP
+.B \-l\fP,\fB  \-\-list
+list the configuration of the repo
 .UNINDENT
 .SH EXAMPLES
 .sp

docs/man/borg-create.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CREATE 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-CREATE 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .
@@ -149,8 +149,8 @@ output stats as JSON. Implies \fB\-\-stats\fP\&.
 .B \-\-no\-cache\-sync
 experimental: do not synchronize the cache. Implies not using the files cache.
 .TP
-.B \-\-no\-files\-cache
-do not load/update the file metadata cache used to detect unchanged files
+.BI \-\-stdin\-name \ NAME
+use NAME in archive for stdin data (default: "stdin")
 .UNINDENT
 .SS Exclusion options
 .INDENT 0.0
@@ -168,12 +168,12 @@ experimental: include/exclude paths matching PATTERN
 experimental: read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .B \-\-exclude\-caches
-exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosaurus.com/cachedir/spec.html\fP)
+exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP)
 .TP
 .BI \-\-exclude\-if\-present \ NAME
 exclude directories that are tagged by containing a filesystem object with the given NAME
 .TP
-.B \-\-keep\-exclude\-tags\fP,\fB  \-\-keep\-tag\-files
+.B \-\-keep\-exclude\-tags
 if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive
 .TP
 .B \-\-exclude\-nodump
@@ -200,9 +200,6 @@ do not store birthtime (creation date) into archive
 .B \-\-nobsdflags
 do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive
 .TP
-.B \-\-ignore\-inode
-ignore inode data in the file metadata cache used to detect unchanged files.
-.TP
 .BI \-\-files\-cache \ MODE
 operate files cache in MODE. default: ctime,size,inode
 .TP
@@ -222,7 +219,7 @@ manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss form
 write checkpoint every SECONDS seconds (Default: 1800)
 .TP
 .BI \-\-chunker\-params \ PARAMS
-specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
+specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095
 .TP
 .BI \-C \ COMPRESSION\fP,\fB \ \-\-compression \ COMPRESSION
 select compression algorithm, see the output of the "borg help compression" command for details.
@@ -252,7 +249,7 @@ $ borg create /path/to/repo::my\-files /home \e
 
 # Backup the root filesystem into an archive named "root\-YYYY\-MM\-DD"
 # use zlib compression (good, but slow) \- default is lz4 (fast, low compression ratio)
-$ borg create \-C zlib,6 /path/to/repo::root\-{now:%Y\-%m\-%d} / \-\-one\-file\-system
+$ borg create \-C zlib,6 \-\-one\-file\-system /path/to/repo::root\-{now:%Y\-%m\-%d} /
 
 # Backup a remote host locally ("pull" style) using sshfs
 $ mkdir sshfs\-mount
@@ -265,10 +262,10 @@ $ fusermount \-u sshfs\-mount
 # Make a big effort in fine granular deduplication (big chunk management
 # overhead, needs a lot of RAM and disk space, see formula in internals
 # docs \- same parameters as borg < 1.0 or attic):
-$ borg create \-\-chunker\-params 10,23,16,4095 /path/to/repo::small /smallstuff
+$ borg create \-\-chunker\-params buzhash,10,23,16,4095 /path/to/repo::small /smallstuff
 
 # Backup a raw device (must not be active/in use/mounted at that time)
-$ dd if=/dev/sdx bs=10M | borg create /path/to/repo::my\-sdx \-
+$ dd if=/dev/sdx bs=4M | borg create \-\-chunker\-params fixed,4194304 /path/to/repo::my\-sdx \-
 
 # No compression (none)
 $ borg create \-\-compression none /path/to/repo::arch ~

docs/man/borg-delete.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DELETE 1 "2018-07-14" "" "borg backup tool"
+.TH BORG-DELETE 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .

docs/man/borg-diff.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DIFF 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-DIFF 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .
@@ -32,12 +32,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg [common options] diff [options] REPO_ARCHIVE1 ARCHIVE2 [PATH...]
+borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
 .SH DESCRIPTION
 .sp
 This command finds differences (file contents, user/group/mode) between archives.
 .sp
-A repository location and an archive name must be specified for REPO_ARCHIVE1.
+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).
 .sp
@@ -57,7 +57,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B REPO_ARCHIVE1
+.B REPO::ARCHIVE1
 repository location and ARCHIVE1 name
 .TP
 .B ARCHIVE2

docs/man/borg-export-tar.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXPORT-TAR 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-EXPORT-TAR 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .
@@ -127,11 +127,11 @@ $ borg export\-tar /path/to/repo::Monday Monday.tar
 $ borg export\-tar /path/to/repo::Monday Monday.tar.gz \-\-exclude \(aq*.so\(aq
 
 # use higher compression level with gzip
-$ borg export\-tar testrepo::linux \-\-tar\-filter="gzip \-9" Monday.tar.gz
+$ borg export\-tar \-\-tar\-filter="gzip \-9" testrepo::linux Monday.tar.gz
 
-# export a gzipped tar, but instead of storing it on disk,
+# export a tar, but instead of storing it on disk,
 # upload it to a remote site using curl.
-$ borg export\-tar ... \-\-tar\-filter="gzip" \- | curl \-\-data\-binary @\- https://somewhere/to/POST
+$ borg export\-tar /path/to/repo::Monday \- | curl \-\-data\-binary @\- https://somewhere/to/POST
 
 # remote extraction via "tarpipe"
 $ borg export\-tar /path/to/repo::Monday \- | ssh somewhere "cd extracted; tar x"

docs/man/borg-extract.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXTRACT 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-EXTRACT 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .

docs/man/borg-info.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INFO 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-INFO 1 "2019-02-24" "" "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 "2017-11-25" "" "borg backup tool"
+.TH BORG-INIT 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .
@@ -182,10 +182,13 @@ repository to create
 select encryption key mode \fB(required)\fP
 .TP
 .B \-\-append\-only
-create an append\-only mode repository
+create an append\-only mode repository. Note that this only affects the low level structure of the repository, and running \fIdelete\fP or \fIprune\fP will still be allowed. See \fIappend_only_mode\fP in Additional Notes for more details.
 .TP
 .BI \-\-storage\-quota \ QUOTA
 Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
+.TP
+.B \-\-make\-parent\-dirs
+create the parent directories of the repository directory, if they are missing.
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0

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

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2019-02-24" "" "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 "2017-11-25" "" "borg backup tool"
+.TH BORG-KEY-EXPORT 1 "2019-02-24" "" "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 "2017-11-25" "" "borg backup tool"
+.TH BORG-KEY-IMPORT 1 "2019-02-24" "" "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 "2017-11-25" "" "borg backup tool"
+.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2019-02-24" "" "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 "2017-11-25" "" "borg backup tool"
+.TH BORG-KEY 1 "2019-02-24" "" "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 "2017-11-25" "" "borg backup tool"
+.TH BORG-LIST 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .
@@ -169,6 +169,10 @@ start: time (start) of creation of the archive
 time: alias of "start"
 .IP \(bu 2
 end: time (end) of creation of the archive
+.IP \(bu 2
+hostname: hostname of host on which this archive was created
+.IP \(bu 2
+username: username of user who created this archive
 .UNINDENT
 .sp
 Keys for listing archive files:

docs/man/borg-mount.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-MOUNT 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-MOUNT 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .
@@ -47,8 +47,9 @@ used in fstab entries:
 To allow a regular user to use fstab entries, add the \fBuser\fP option:
 \fB/path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0\fP
 .sp
-For mount options, see the fuse(8) manual page. Additional mount options
-supported by borg:
+For FUSE configuration and mount options, see the mount.fuse(8) manual page.
+.sp
+Additional mount options supported by borg:
 .INDENT 0.0
 .IP \(bu 2
 versions: when used with a repository mount, this gives a merged, versioned
@@ -57,6 +58,10 @@ 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 \fB\-\-repair\fP) are not readable and
 return EIO (I/O error). Set this option to read such files.
+.IP \(bu 2
+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".
 .UNINDENT
 .sp
 The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users

docs/man/borg-patterns.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PATTERNS 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-PATTERNS 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .
@@ -32,6 +32,15 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH DESCRIPTION
 .sp
+The path/filenames used as input for the pattern matching start from the
+currently active recursion root. You usually give the recursion root(s)
+when invoking borg and these can be either relative or absolute paths.
+.sp
+So, when you give \fIrelative/\fP as root, the paths going into the matcher
+will look like \fIrelative/.../file.ext\fP\&. When you give \fI/absolute/\fP as root,
+they will look like \fI/absolute/.../file.ext\fP\&. This is meant when we talk
+about "full path" below.
+.sp
 File patterns support these styles: fnmatch, shell, regular expressions,
 path prefixes and path full\-matches. By default, fnmatch is used for
 \fB\-\-exclude\fP patterns and shell\-style is used for the experimental \fB\-\-pattern\fP
@@ -49,11 +58,11 @@ These patterns use a variant of shell pattern syntax, with \(aq*\(aq matching
 any number of characters, \(aq?\(aq matching any single character, \(aq[...]\(aq
 matching any single character specified, including ranges, and \(aq[!...]\(aq
 matching any character not specified. For the purpose of these patterns,
-the path separator (\(aq\(aq for Windows and \(aq/\(aq on other systems) is not
+the path separator (backslash for Windows and \(aq/\(aq on other systems) is not
 treated specially. Wrap meta\-characters in brackets for a literal
 match (i.e. \fI[?]\fP to match the literal character \fI?\fP). For a path
-to match a pattern, it must completely match from start to end, or
-must match from the start to just before a path separator. Except
+to match a pattern, the full path must match, or it must match
+from the start of the full path to just before a path separator. Except
 for the root path, paths will never end in the path separator when
 matching is attempted.  Thus, if a given pattern ends in a path
 separator, a \(aq*\(aq is appended before matching is attempted.
@@ -67,23 +76,23 @@ exception of any path separator.
 .TP
 .B Regular expressions, selector \fIre:\fP
 Regular expressions similar to those found in Perl are supported. Unlike
-shell patterns regular expressions are not required to match the complete
+shell patterns regular expressions are not required to match the full
 path and any substring match is sufficient. It is strongly recommended to
 anchor patterns to the start (\(aq^\(aq), to the end (\(aq$\(aq) or both. Path
-separators (\(aq\(aq for Windows and \(aq/\(aq on other systems) in paths are
+separators (backslash for Windows and \(aq/\(aq on other systems) in paths are
 always normalized to a forward slash (\(aq/\(aq) before applying a pattern. The
 regular expression syntax is described in the \fI\%Python documentation for
 the re module\fP\&.
 .TP
 .B Path prefix, selector \fIpp:\fP
 This pattern style is useful to match whole sub\-directories. The pattern
-\fIpp:/data/bar\fP matches \fI/data/bar\fP and everything therein.
+\fIpp:root/somedir\fP matches \fIroot/somedir\fP and everything therein.
 .TP
 .B Path full\-match, selector \fIpf:\fP
-This pattern style is useful to match whole paths.
+This pattern style is (only) useful to match full paths.
 This is kind of a pseudo pattern as it can not have any variable or
-unspecified parts \- the full, precise path must be given.
-\fIpf:/data/foo.txt\fP matches \fI/data/foo.txt\fP only.
+unspecified parts \- the full path must be given.
+\fIpf:root/file.ext\fP matches \fIroot/file.txt\fP only.
 .sp
 Implementation note: this is implemented via very time\-efficient O(1)
 hashtable lookups (this means you can have huge amounts of such patterns
@@ -175,7 +184,24 @@ Patterns (\fB\-\-pattern\fP) and excludes (\fB\-\-exclude\fP) from the command l
 considered first (in the order of appearance). Then patterns from \fB\-\-patterns\-from\fP
 are added. Exclusion patterns from \fB\-\-exclude\-from\fP files are appended last.
 .sp
-An example \fB\-\-patterns\-from\fP file could look like that:
+Examples:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# backup pics, but not the ones from 2018, except the good ones:
+# note: using = is essential to avoid cmdline argument parsing issues.
+borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 repo::arch pics
+
+# use a file with patterns:
+borg create \-\-patterns\-from patterns.lst repo::arch
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The patterns.lst file could look like that:
 .INDENT 0.0
 .INDENT 3.5
 .sp

docs/man/borg-placeholders.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PLACEHOLDERS 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-PLACEHOLDERS 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-placeholders \- Details regarding placeholders
 .
@@ -42,7 +42,7 @@ The (short) hostname of the machine.
 .B {fqdn}
 The full name of the machine.
 .TP
-.B {reverse-fqdn}
+.B {reverse\-fqdn}
 The full name of the machine in reverse domain name notation.
 .TP
 .B {now}

docs/man/borg-prune.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PRUNE 1 "2018-07-14" "" "borg backup tool"
+.TH BORG-PRUNE 1 "2019-02-24" "" "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 "2018-07-14" "" "borg backup tool"
+.TH BORG-RECREATE 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .
@@ -126,12 +126,12 @@ experimental: include/exclude paths matching PATTERN
 experimental: read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .B \-\-exclude\-caches
-exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosaurus.com/cachedir/spec.html\fP)
+exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP)
 .TP
 .BI \-\-exclude\-if\-present \ NAME
 exclude directories that are tagged by containing a filesystem object with the given NAME
 .TP
-.B \-\-keep\-exclude\-tags\fP,\fB  \-\-keep\-tag\-files
+.B \-\-keep\-exclude\-tags
 if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive
 .UNINDENT
 .SS Archive options
@@ -156,7 +156,7 @@ select compression algorithm, see the output of the "borg help compression" comm
 recompress data chunks according to \fB\-\-compression\fP\&. MODE \fIif\-different\fP: recompress if current compression is with a different compression algorithm (the level is not considered). MODE \fIalways\fP: recompress even if current compression is with the same compression algorithm (use this to change the compression level). MODE \fInever\fP (default): do not recompress.
 .TP
 .BI \-\-chunker\-params \ PARAMS
-specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or \fIdefault\fP to use the current defaults. default: 19,23,21,4095
+specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or \fIdefault\fP to use the current defaults. default: buzhash,19,23,21,4095
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0

docs/man/borg-rename.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RENAME 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-RENAME 1 "2019-02-24" "" "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 "2017-11-25" "" "borg backup tool"
+.TH BORG-SERVE 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .
@@ -49,7 +49,7 @@ restrict repository access to PATH. Can be specified multiple times to allow the
 restrict repository access. Only the repository located at PATH (no sub\-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike \fB\-\-restrict\-to\-path\fP sub\-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
 .TP
 .B \-\-append\-only
-only allow appending to repository segment files
+only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running \fIdelete\fP or \fIprune\fP will still be allowed. See \fIappend_only_mode\fP in Additional Notes for more details.
 .TP
 .BI \-\-storage\-quota \ QUOTA
 Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.

docs/man/borg-umount.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UMOUNT 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-UMOUNT 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .
@@ -82,6 +82,11 @@ $ borg umount /tmp/mymountpoint
 # These are especially handy for the "versions view",
 # which does not support lazy processing of archives.
 $ borg mount \-o versions \-\-glob\-archives \(aq*\-my\-home\(aq \-\-last 10 /path/to/repo /tmp/mymountpoint
+
+# Exclusion options are supported.
+# These can speed up mounting and lower memory needs significantly.
+$ borg mount /path/to/repo /tmp/mymountpoint only/that/path
+$ borg mount \-\-exclude \(aq...\(aq /path/to/repo /tmp/mymountpoint
 .ft P
 .fi
 .UNINDENT

docs/man/borg-upgrade.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UPGRADE 1 "2017-11-25" "" "borg backup tool"
+.TH BORG-UPGRADE 1 "2019-02-24" "" "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 "2017-11-25" "" "borg backup tool"
+.TH BORG-WITH-LOCK 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .

docs/man/borg.1

@@ -186,6 +186,26 @@ get other informational messages.
 .UNINDENT
 .UNINDENT
 .SH NOTES
+.SS Positional Arguments and Options: Order matters
+.sp
+Borg only supports taking options (\fB\-s\fP and \fB\-\-progress\fP in the example)
+to the left or right of all positional arguments (\fBrepo::archive\fP and \fBpath\fP
+in the example), but not in between them:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+borg create \-s \-\-progress repo::archive path  # good and preferred
+borg create repo::archive path \-s \-\-progress  # also works
+borg create \-s repo::archive path \-\-progress  # works, but ugly
+borg create repo::archive \-s \-\-progress path  # BAD
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This is due to a problem in the argparse module: \fI\%http://bugs.python.org/issue15112\fP
 .SS Repository URLs
 .sp
 \fBLocal filesystem\fP (or locally mounted network filesystem):
@@ -254,7 +274,26 @@ name).
 .sp
 If you have set BORG_REPO (see above) and an archive location is needed, use
 \fB::archive_name\fP \- the repo URL part is then read from BORG_REPO.
-.SS Type of log output
+.SS Logging
+.sp
+Borg writes all log output to stderr by default. But please note that something
+showing up on stderr does \fInot\fP indicate an error condition just because it is
+on stderr. Please check the log levels of the messages and the return code of
+borg for determining error, warning or success conditions.
+.sp
+If you want to capture the log output to a file, just redirect it:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+borg create repo::archive myfiles 2>> logfile
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Custom logging configurations can be implemented via BORG_LOGGING_CONF.
 .sp
 The log level of the builtin logging configuration defaults to WARNING.
 This is because we want Borg to be mostly silent and only output
@@ -355,10 +394,18 @@ When set, use the standard output of the command (trailing newlines are stripped
 passphrase question for encrypted repositories.
 It is used when a passphrase is needed to access an encrypted repo as well as when a new
 passphrase should be initially set when initializing an encrypted repo. Note that the command
-is executed without a shell. So variables, like \fB$HOME\fP\ will work, but \fB~\fP\ won't.
+is executed without a shell. So variables, like \fB$HOME\fP will work, but \fB~\fP won\(aqt.
 If BORG_PASSPHRASE is also set, it takes precedence.
 See also BORG_NEW_PASSPHRASE.
 .TP
+.B BORG_PASSPHRASE_FD
+When set, specifies a file descriptor to read a passphrase
+from. Programs starting borg may choose to open an anonymous pipe
+and use it to pass a passphrase. This is safer than passing via
+BORG_PASSPHRASE, because on some systems (e.g. Linux) environment
+can be examined by other processes.
+If BORG_PASSPHRASE or BORG_PASSCOMMAND are also set, they take precedence.
+.TP
 .B BORG_NEW_PASSPHRASE
 When set, use the value to answer the passphrase question when a \fBnew\fP passphrase is asked for.
 This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also
@@ -373,13 +420,21 @@ Borg assumes that it can derive a unique hostname / identity (see \fBborg debug
 If this is not the case or you do not want Borg to automatically remove stale locks,
 set this to \fIno\fP\&.
 .TP
+.B BORG_HOST_ID
+Borg usually computes a host id from the FQDN plus the results of \fBuuid.getnode()\fP (which usually returns
+a unique id based on the MAC address of the network interface. Except if that MAC happens to be all\-zero \- in
+that case it returns a random value, which is not what we want (because it kills automatic stale lock removal).
+So, if you have a all\-zero MAC address or other reasons to better externally control the host id, just set this
+environment variable to a unique value. If all your FQDNs are unique, you can just use the FQDN. If not,
+use \fI\%fqdn@uniqueid\fP\&.
+.TP
 .B BORG_LOGGING_CONF
 When set, use the given filename as \fI\%INI\fP\-style logging configuration.
 .TP
 .B BORG_RSH
 When set, use this command instead of \fBssh\fP\&. This can be used to specify ssh options, such as
-a custom identity file \fBssh \-i /path/to/private/key\fP\&. See \fBman ssh\fP for other options.
-Using the \fB\-\-rsh CMD\fP commandline option overrides the environment variable.
+a custom identity file \fBssh \-i /path/to/private/key\fP\&. See \fBman ssh\fP for other options. Using
+the \fB\-\-rsh CMD\fP commandline option overrides the environment variable.
 .TP
 .B BORG_REMOTE_PATH
 When set, use the given path as borg executable on the remote (defaults to "borg" if unset).
@@ -390,8 +445,13 @@ When set to a numeric value, this determines the maximum "time to live" for the
 entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
 The FAQ explains this more detailed in: \fIalways_chunking\fP
 .TP
+.B BORG_SHOW_SYSINFO
+When set to no (default: yes), system information (like OS, Python version, ...) in
+exceptions is not shown.
+Please only use for good reasons as it makes issues harder to analyze.
+.TP
 .B TMPDIR
-where temporary files are stored (might need a lot of temporary space for some operations)
+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):
@@ -420,23 +480,27 @@ allowed). So please test your scripts interactively before making them a non\-in
 .B Directories and files:
 .INDENT 7.0
 .TP
-.B BORG_KEYS_DIR
-Default to \(aq~/.config/borg/keys\(aq. This directory contains keys for encrypted repositories.
+.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_KEY_FILE
-When set, use the given filename as repository key file.
+.B BORG_CONFIG_DIR
+Default to \(aq~/.config/borg\(aq. This directory contains the whole config directories.
+.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.
 .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.
 .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).
+.B BORG_KEYS_DIR
+Default to \(aq~/.config/borg/keys\(aq. This directory contains keys for encrypted repositories.
 .TP
-.B BORG_CONFIG_DIR
-Default to \(aq~/.config/borg\(aq. This directory contains the whole config directories.
+.B BORG_KEY_FILE
+When set, use the given filename as repository key file.
 .UNINDENT
 .TP
 .B Building:
@@ -445,12 +509,17 @@ Default to \(aq~/.config/borg\(aq. This directory contains the whole config dire
 .B BORG_OPENSSL_PREFIX
 Adds given OpenSSL header file directory to the default locations (setup.py).
 .TP
-.B BORG_LZ4_PREFIX
-Adds given LZ4 header file directory to the default locations (setup.py).
+.B BORG_LIBLZ4_PREFIX
+Adds given prefix directory to the default locations. If a \(aqinclude/lz4.h\(aq is found Borg
+will be linked against the system liblz4 instead of a bundled implementation. (setup.py)
 .TP
 .B BORG_LIBB2_PREFIX
 Adds given prefix directory to the default locations. If a \(aqinclude/blake2.h\(aq is found Borg
 will be linked against the system libb2 instead of a bundled implementation. (setup.py)
+.TP
+.B BORG_LIBZSTD_PREFIX
+Adds given prefix directory to the default locations. If a \(aqinclude/zstd.h\(aq is found Borg
+will be linked against the system libzstd instead of a bundled implementation. (setup.py)
 .UNINDENT
 .UNINDENT
 .sp
@@ -522,12 +591,23 @@ server to get the approximate resource usage.
 .INDENT 0.0
 .TP
 .B CPU client:
-borg create: does chunking, hashing, compression, crypto (high CPU usage)
-chunks cache sync: quite heavy on CPU, doing lots of hashtable operations.
-borg extract: crypto, decompression (medium to high CPU usage)
-borg check: similar to extract, but depends on options given.
-borg prune / borg delete archive: low to medium CPU usage
-borg delete repo: done on the server
+.INDENT 7.0
+.IP \(bu 2
+\fBborg create:\fP does chunking, hashing, compression, crypto (high CPU usage)
+.IP \(bu 2
+\fBchunks cache sync:\fP quite heavy on CPU, doing lots of hashtable operations.
+.IP \(bu 2
+\fBborg extract:\fP crypto, decompression (medium to high CPU usage)
+.IP \(bu 2
+\fBborg check:\fP similar to extract, but depends on options given.
+.IP \(bu 2
+\fBborg prune / borg delete archive:\fP low to medium CPU usage
+.IP \(bu 2
+\fBborg delete repo:\fP done on the server
+.UNINDENT
+.IP "System Message: WARNING/2 (docs/usage_general.rst.inc:, line 354)"
+Bullet list ends without a blank line; unexpected unindent.
+.sp
 It won\(aqt go beyond 100% of 1 core as the code is currently single\-threaded.
 Especially higher zlib and lzma compression levels use significant amounts
 of CPU cycles. Crypto might be cheap on the CPU (if hardware accelerated) or
@@ -616,6 +696,8 @@ hardlinked regular files, devices, FIFOs (considering all items in the same arch
 .IP \(bu 2
 timestamps in nanosecond precision: mtime, atime, ctime
 .IP \(bu 2
+other timestamps: birthtime (on platforms supporting it)
+.IP \(bu 2
 permissions:
 .INDENT 2.0
 .IP \(bu 2
@@ -673,6 +755,8 @@ T}	T{
 Yes
 T}	T{
 Yes
+T}	T{
+Yes (all)
 T}
 _
 T{
@@ -681,6 +765,8 @@ T}	T{
 n/a
 T}	T{
 n/a
+T}	T{
+Yes (all)
 T}
 _
 T{
@@ -689,10 +775,14 @@ T}	T{
 n/a
 T}	T{
 No [2]
+T}	T{
+Yes (all)
 T}
 _
 T{
-Solaris 11
+Solaris and derivatives
+T}	T{
+No [3]
 T}	T{
 No [3]
 T}	T{
@@ -700,10 +790,6 @@ n/a
 T}
 _
 T{
-OpenIndiana
-T}
-_
-T{
 Windows (cygwin)
 T}	T{
 No [4]

docs/man/borgfs.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORGFS 1 "2017-11-25" "" "borg backup tool"
+.TH BORGFS 1 "2019-02-24" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .
@@ -47,8 +47,9 @@ used in fstab entries:
 To allow a regular user to use fstab entries, add the \fBuser\fP option:
 \fB/path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0\fP
 .sp
-For mount options, see the fuse(8) manual page. Additional mount options
-supported by borg:
+For FUSE configuration and mount options, see the mount.fuse(8) manual page.
+.sp
+Additional mount options supported by borg:
 .INDENT 0.0
 .IP \(bu 2
 versions: when used with a repository mount, this gives a merged, versioned
@@ -57,6 +58,10 @@ 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 \fB\-\-repair\fP) are not readable and
 return EIO (I/O error). Set this option to read such files.
+.IP \(bu 2
+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".
 .UNINDENT
 .sp
 The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users

docs/usage/benchmark_crud.rst.inc

@@ -50,7 +50,7 @@ This command benchmarks borg CRUD (create, read, update, delete) operations.
 
 It creates input data below the given PATH and backups this data into the given REPO.
 The REPO must already exist (it could be a fresh empty repo or an existing repo, the
-command will create / read / update / delete some archives named borg-test-data\* there.
+command will create / read / update / delete some archives named borg-benchmark-crud\* there.
 
 Make sure you have free space there, you'll need about 1GB each (+ overhead).
 
@@ -70,7 +70,7 @@ C- == borg create (1st archive creation, no compression, do not use files cache)
 R- == borg extract (extract archive, dry-run, do everything, but do not write files to disk)
       R-Z- == all zero files. Measuring heavily duplicated files.
       R-R- == random files. No duplication here, measuring throughput through all processing
-              stages, except writing to disk.
+      stages, except writing to disk.
 
 U- == borg create (2nd archive creation of unchanged input files, measure files cache speed)
       The throughput value is kind of virtual here, it does not actually read the file.

docs/usage/common-options.rst.inc

@@ -15,3 +15,4 @@
 --remote-ratelimit RATE    set remote network upload rate limit in kiByte/s (default: 0=unlimited)
 --consider-part-files    treat part files like normal files (e.g. to list/extract them)
 --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')

docs/usage/config.rst.inc

@@ -6,7 +6,7 @@ borg config
 -----------
 .. code-block:: none
 
-    borg [common options] config [options] REPOSITORY NAME [VALUE]
+    borg [common options] config [options] REPOSITORY [NAME] [VALUE]
 
 .. only:: html
 
@@ -27,6 +27,8 @@ borg config
     +-------------------------------------------------------+----------------------+----------------------------------------+
     |                                                       | ``-d``, ``--delete`` | delete the key from the config file    |
     +-------------------------------------------------------+----------------------+----------------------------------------+
+    |                                                       | ``-l``, ``--list``   | list the configuration of the repo     |
+    +-------------------------------------------------------+----------------------+----------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                        |
     |                                                                                                                       |
     | :ref:`common_options`                                                                                                 |
@@ -51,8 +53,9 @@ borg config
 
 
     optional arguments
-        -c, --cache      get and set values from the repo cache
-        -d, --delete     delete the key from the config file
+        -c, --cache    get and set values from the repo cache
+        -d, --delete    delete the key from the config file
+        -l, --list     list the configuration of the repo
 
 
     :ref:`common_options`
@@ -64,10 +67,13 @@ Description
 This command gets and sets options in a local repository or cache config file.
 For security reasons, this command only works on local repositories.
 
-To delete a config value entirely, use ``--delete``. To get an existing key, pass
-only the key name. To set a key, pass both the key name and the new value. Keys
-can be specified in the format "section.name" or simply "name"; the section will
-default to "repository" and "cache" for the repo and cache configs, respectively.
+To delete a config value entirely, use ``--delete``. To list the values
+of the configuration file or the default values, use ``--list``.  To get and existing
+key, pass only the key name. To set a key, pass both the key name and
+the new value. Keys can be specified in the format "section.name" or
+simply "name"; the section will default to "repository" and "cache" for
+the repo and cache configs, respectively.
+
 
 By default, borg config manipulates the repository config file. Using ``--cache``
 edits the repository cache's config file instead.

docs/usage/create.rst.inc

@@ -33,7 +33,7 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--no-cache-sync``                               | experimental: do not synchronize the cache. Implies not using the files cache.                                                                    |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--no-files-cache``                              | do not load/update the file metadata cache used to detect unchanged files                                                                         |
+    |                                                       | ``--stdin-name NAME``                             | use NAME in archive for stdin data (default: "stdin")                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                |
     |                                                                                                                                                                                                                                                               |
@@ -49,11 +49,11 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--patterns-from PATTERNFILE``                   | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                        |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)                                              |
+    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                   |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--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                         |
+    |                                                       | ``--keep-exclude-tags``                           | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                         |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-nodump``                              | exclude files flagged NODUMP                                                                                                                      |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -71,8 +71,6 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--nobsdflags``                                  | do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive                                                                              |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--ignore-inode``                                | ignore inode data in the file metadata cache used to detect unchanged files.                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--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. |
@@ -85,7 +83,7 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                            |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095                           |
+    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095             |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details.                                                  |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -113,7 +111,7 @@ borg create
         --filter STATUSCHARS    only display items with the given status characters (see description)
         --json          output stats as JSON. Implies ``--stats``.
         --no-cache-sync    experimental: do not synchronize the cache. Implies not using the files cache.
-        --no-files-cache    do not load/update the file metadata cache used to detect unchanged files
+        --stdin-name NAME    use NAME in archive for stdin data (default: "stdin")
 
 
     :ref:`common_options`
@@ -124,9 +122,9 @@ borg create
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
         --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
-        --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
+        --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)
         --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
+        --keep-exclude-tags               if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
         --exclude-nodump                  exclude files flagged NODUMP
 
 
@@ -137,7 +135,6 @@ borg create
         --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
-        --ignore-inode            ignore inode data in the file metadata cache used to detect unchanged files.
         --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.
 
@@ -146,7 +143,7 @@ borg create
         --comment COMMENT                             add a comment text to the archive
         --timestamp TIMESTAMP                         manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory.
         -c SECONDS, --checkpoint-interval SECONDS     write checkpoint every SECONDS seconds (Default: 1800)
-        --chunker-params PARAMS                       specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
+        --chunker-params PARAMS                       specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095
         -C COMPRESSION, --compression COMPRESSION     select compression algorithm, see the output of the "borg help compression" command for details.
 
 

docs/usage/diff.rst.inc

@@ -6,7 +6,7 @@ borg diff
 ---------
 .. code-block:: none
 
-    borg [common options] diff [options] REPO_ARCHIVE1 ARCHIVE2 [PATH...]
+    borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
 
 .. only:: html
 
@@ -15,7 +15,7 @@ borg diff
     +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
     | **positional arguments**                                                                                                                                                   |
     +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``REPO_ARCHIVE1``                     | repository location and ARCHIVE1 name                                      |
+    |                                                       | ``REPO::ARCHIVE1``                    | repository location and ARCHIVE1 name                                      |
     +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
     |                                                       | ``ARCHIVE2``                          | ARCHIVE2 name (no repository location allowed)                             |
     +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
@@ -54,7 +54,7 @@ borg diff
 
 .. only:: latex
 
-    REPO_ARCHIVE1
+    REPO::ARCHIVE1
         repository location and ARCHIVE1 name
     ARCHIVE2
         ARCHIVE2 name (no repository location allowed)
@@ -83,7 +83,7 @@ Description
 
 This command finds differences (file contents, user/group/mode) between archives.
 
-A repository location and an archive name must be specified for REPO_ARCHIVE1.
+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).
 

docs/usage/help.rst.inc

@@ -6,6 +6,15 @@ borg help patterns
 ~~~~~~~~~~~~~~~~~~
 
 
+The path/filenames used as input for the pattern matching start from the
+currently active recursion root. You usually give the recursion root(s)
+when invoking borg and these can be either relative or absolute paths.
+
+So, when you give `relative/` as root, the paths going into the matcher
+will look like `relative/.../file.ext`. When you give `/absolute/` as root,
+they will look like `/absolute/.../file.ext`. This is meant when we talk
+about "full path" below.
+
 File patterns support these styles: fnmatch, shell, regular expressions,
 path prefixes and path full-matches. By default, fnmatch is used for
 ``--exclude`` patterns and shell-style is used for the experimental ``--pattern``
@@ -22,11 +31,11 @@ two alphanumeric characters followed by a colon (i.e. `aa:something/*`).
     any number of characters, '?' matching any single character, '[...]'
     matching any single character specified, including ranges, and '[!...]'
     matching any character not specified. For the purpose of these patterns,
-    the path separator ('\' for Windows and '/' on other systems) is not
+    the path separator (backslash for Windows and '/' on other systems) is not
     treated specially. Wrap meta-characters in brackets for a literal
     match (i.e. `[?]` to match the literal character `?`). For a path
-    to match a pattern, it must completely match from start to end, or
-    must match from the start to just before a path separator. Except
+    to match a pattern, the full path must match, or it must match
+    from the start of the full path to just before a path separator. Except
     for the root path, paths will never end in the path separator when
     matching is attempted.  Thus, if a given pattern ends in a path
     separator, a '\*' is appended before matching is attempted.
@@ -40,23 +49,23 @@ Shell-style patterns, selector `sh:`
 
 Regular expressions, selector `re:`
     Regular expressions similar to those found in Perl are supported. Unlike
-    shell patterns regular expressions are not required to match the complete
+    shell patterns regular expressions are not required to match the full
     path and any substring match is sufficient. It is strongly recommended to
     anchor patterns to the start ('^'), to the end ('$') or both. Path
-    separators ('\' for Windows and '/' on other systems) in paths are
+    separators (backslash for Windows and '/' on other systems) in paths are
     always normalized to a forward slash ('/') before applying a pattern. The
     regular expression syntax is described in the `Python documentation for
     the re module <https://docs.python.org/3/library/re.html>`_.
 
 Path prefix, selector `pp:`
     This pattern style is useful to match whole sub-directories. The pattern
-    `pp:/data/bar` matches `/data/bar` and everything therein.
+    `pp:root/somedir` matches `root/somedir` and everything therein.
 
 Path full-match, selector `pf:`
-    This pattern style is useful to match whole paths.
+    This pattern style is (only) useful to match full paths.
     This is kind of a pseudo pattern as it can not have any variable or
-    unspecified parts - the full, precise path must be given.
-    `pf:/data/foo.txt` matches `/data/foo.txt` only.
+    unspecified parts - the full path must be given.
+    `pf:root/file.ext` matches `root/file.txt` only.
 
     Implementation note: this is implemented via very time-efficient O(1)
     hashtable lookups (this means you can have huge amounts of such patterns
@@ -139,7 +148,16 @@ Examples::
     considered first (in the order of appearance). Then patterns from ``--patterns-from``
     are added. Exclusion patterns from ``--exclude-from`` files are appended last.
 
-    An example ``--patterns-from`` file could look like that::
+    Examples::
+
+        # backup pics, but not the ones from 2018, except the good ones:
+        # note: using = is essential to avoid cmdline argument parsing issues.
+        borg create --pattern=+pics/2018/good --pattern=-pics/2018 repo::arch pics
+
+        # use a file with patterns:
+        borg create --patterns-from patterns.lst repo::arch
+
+    The patterns.lst file could look like that::
 
         # "sh:" pattern style is the default, so the following line is not needed:
         P sh
@@ -241,7 +259,13 @@ none
     Do not compress.
 
 lz4
-    Use lz4 compression. High speed, low compression. (default)
+    Use lz4 compression. Very high speed, very low compression. (default)
+
+zstd[,L]
+    Use zstd ("zstandard") compression, a modern wide-range algorithm.
+    If you do not explicitly give the compression level L (ranging from 1
+    to 22), it will use level 3.
+    Archives compressed with zstd are not compatible with borg < 1.1.4.
 
 zlib[,L]
     Use zlib ("gz") compression. Medium speed, medium compression.
@@ -268,6 +292,8 @@ auto,C[,L]
 Examples::
 
     borg create --compression lz4 REPO::ARCHIVE data
+    borg create --compression zstd REPO::ARCHIVE data
+    borg create --compression zstd,10 REPO::ARCHIVE data
     borg create --compression zlib REPO::ARCHIVE data
     borg create --compression zlib,1 REPO::ARCHIVE data
     borg create --compression auto,lzma,6 REPO::ARCHIVE data

docs/usage/init.rst.inc

@@ -12,23 +12,25 @@ borg init
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                 |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    |                                                       | ``REPOSITORY``                     | repository to create                                                        |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                   |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    |                                                       | ``-e MODE``, ``--encryption MODE`` | select encryption key mode **(required)**                                   |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    |                                                       | ``--append-only``                  | create an append-only mode repository                                       |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    |                                                       | ``--storage-quota QUOTA``          | Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota. |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                           |
-    |                                                                                                                                                                          |
-    | :ref:`common_options`                                                                                                                                                    |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                                                                                                                            |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``REPOSITORY``                     | repository to create                                                                                                                                                                                                                   |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                                                                                                                                              |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-e MODE``, ``--encryption MODE`` | select encryption key mode **(required)**                                                                                                                                                                                              |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--append-only``                  | create an append-only mode repository. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details. |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--storage-quota QUOTA``          | Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.                                                                                                                                                            |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--make-parent-dirs``             | create the parent directories of the repository directory, if they are missing.                                                                                                                                                        |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                                                                      |
+    |                                                                                                                                                                                                                                                                                                                                     |
+    | :ref:`common_options`                                                                                                                                                                                                                                                                                                               |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -46,8 +48,9 @@ borg init
 
     optional arguments
         -e MODE, --encryption MODE     select encryption key mode **(required)**
-        --append-only                  create an append-only mode repository
+        --append-only                  create an append-only mode repository. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.
         --storage-quota QUOTA          Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
+        --make-parent-dirs             create the parent directories of the repository directory, if they are missing.
 
 
     :ref:`common_options`

docs/usage/key_import.rst.inc

@@ -58,4 +58,4 @@ This command restores a key previously backed up with the export command.
 
 If the ``--paper`` option is given, the import will be an interactive
 process in which each line is checked for plausibility before
-proceeding to the next line. For this format PATH must not be given.
+proceeding to the next line. For this format PATH must not be given.

docs/usage/list.rst.inc

@@ -129,6 +129,9 @@ Keys for listing repository archives:
 - time: alias of "start"
 - end: time (end) of creation of the archive
 
+- hostname: hostname of host on which this archive was created
+- username: username of user who created this archive
+
 
 Keys for listing archive files:
 

docs/usage/mount.rst.inc

@@ -113,14 +113,18 @@ used in fstab entries:
 To allow a regular user to use fstab entries, add the ``user`` option:
 ``/path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0``
 
-For mount options, see the fuse(8) manual page. Additional mount options
-supported by borg:
+For FUSE configuration and mount options, see the mount.fuse(8) manual page.
+
+Additional mount options 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
   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".
 
 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

docs/usage/recreate.rst.inc

@@ -43,11 +43,11 @@ borg recreate
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--patterns-from PATTERNFILE``                   | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                                                                                                                                                 |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)                                                                                                                                                                                                                                                                       |
+    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                                                                                                                                                                                                                                            |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--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                                                                                                                                                                                                                                                  |
+    |                                                       | ``--keep-exclude-tags``                           | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                                                                                                                                                                                                                                                  |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **Archive options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -63,7 +63,7 @@ borg recreate
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--recompress MODE``                             | recompress data chunks according to ``--compression``. MODE `if-different`: recompress if current compression is with a different compression algorithm (the level is not considered). MODE `always`: recompress even if current compression is with the same compression algorithm (use this to change the compression level). MODE `never` (default): do not recompress. |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--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                                                                                                                                                                                                           |
+    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: buzhash,19,23,21,4095                                                                                                                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
@@ -97,9 +97,9 @@ borg recreate
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
         --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
-        --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
+        --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)
         --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
+        --keep-exclude-tags               if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
 
 
     Archive options
@@ -109,7 +109,7 @@ borg recreate
         --timestamp TIMESTAMP                         manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
         -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 ``--compression``. MODE `if-different`: recompress if current compression is with a different compression algorithm (the level is not considered). MODE `always`: recompress even if current compression is with the same compression algorithm (use this to change the compression level). MODE `never` (default): do not recompress.
-        --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
+        --chunker-params PARAMS                       specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: buzhash,19,23,21,4095
 
 
 Description

docs/usage/serve.rst.inc

@@ -19,7 +19,7 @@ borg serve
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--restrict-to-repository PATH`` | restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--append-only``                 | only allow appending to repository segment files                                                                                                                                                                                                                                                                                                                                                                                                                      |
+    |                                                       | ``--append-only``                 | only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.                                                                                                                                                                                                                     |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--storage-quota QUOTA``         | Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.                                                                                                                                                                                                                                                                                              |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -43,7 +43,7 @@ borg serve
     optional arguments
         --restrict-to-path PATH    restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository.
         --restrict-to-repository PATH    restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
-        --append-only             only allow appending to repository segment files
+        --append-only             only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.
         --storage-quota QUOTA     Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.
 
 

docs/usage/with-lock.rst.inc

@@ -57,5 +57,9 @@ running in the repo), then execute the given command as a subprocess and wait
 for its termination, release the lock and return the user command's return
 code as borg's return code.
 
-As example you can use "borg with-lock" to copy a repo to another location
-(see :ref:`can_i_copy_or_synchronize_my_repo_to_another_location` in the FAQ).
+.. note::
+
+    If you copy a repository with the lock held, the lock will be present in
+    the copy. Thus, before using borg on the copy from a different host,
+    you need to use "borg break-lock" on the copied repository, because
+    Borg is cautious and does not automatically remove stale locks made by a different host.