build man

docs/man/borg-benchmark-crud.1

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

docs/man/borg-benchmark.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK 1 "2020-10-04" "" "borg backup tool"
+.TH BORG-BENCHMARK 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-CHECK 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-COMMON 1 "2020-12-06" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .

docs/man/borg-compact.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMPACT 1 "2020-10-04" "" "borg backup tool"
+.TH BORG-COMPACT 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-COMPRESSION 1 "2020-12-06" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .
@@ -79,6 +79,32 @@ The heuristic tries with lz4 whether the data is compressible.
 For incompressible data, it will not use compression (uses "none").
 For compressible data, it uses the given C[,L] compression \- with C[,L]
 being any valid compression specifier.
+.TP
+.B obfuscate,SPEC,C[,L]
+Use compressed\-size obfuscation to make fingerprinting attacks based on
+the observable stored chunk size more difficult.
+Note:
+\- you must combine this with encryption or it won\(aqt make any sense.
+\- your repo size will be bigger, of course.
+.sp
+The SPEC value will determine how the size obfuscation will work:
+.sp
+Relative random reciprocal size variation:
+Size will increase by a factor, relative to the compressed data size.
+Smaller factors are often used, larger factors rarely.
+1: factor 0.01 .. 100.0
+2: factor 0.1 .. 1000.0
+3: factor 1.0 .. 10000.0
+4: factor 10.0 .. 100000.0
+5: factor 100.0 .. 1000000.0
+6: factor 1000.0 .. 10000000.0
+.sp
+Add a randomly sized padding up to the given size:
+110: 1kiB
+\&...
+120: 1MiB
+\&...
+123: 8MiB (max.)
 .UNINDENT
 .sp
 Examples:
@@ -94,6 +120,9 @@ borg create \-\-compression zlib REPO::ARCHIVE data
 borg create \-\-compression zlib,1 REPO::ARCHIVE data
 borg create \-\-compression auto,lzma,6 REPO::ARCHIVE data
 borg create \-\-compression auto,lzma ...
+borg create \-\-compression obfuscate,3,none ...
+borg create \-\-compression obfuscate,3,auto,zstd,10 ...
+borg create \-\-compression obfuscate,2,zstd,6 ...
 .ft P
 .fi
 .UNINDENT

docs/man/borg-config.1

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

docs/man/borg-create.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CREATE 1 "2020-10-04" "" "borg backup tool"
+.TH BORG-CREATE 1 "2020-12-06" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .
@@ -94,6 +94,7 @@ ctime is a rather safe way to detect changes to a file (metadata and contents)
 as it can not be set from userspace. But, a metadata\-only change will already
 update the ctime, so there might be some unnecessary chunking/hashing even
 without content changes. Some filesystems do not support ctime (change time).
+E.g. doing a chown or chmod to a file will change its ctime.
 .IP \(bu 2
 mtime usually works and only updates if file contents were changed. But mtime
 can be arbitrarily set from userspace, e.g. to set mtime back to the same value
@@ -117,6 +118,7 @@ the state after creation. Also, the \fB\-\-stats\fP and \fB\-\-dry\-run\fP optio
 exclusive because the data is not actually compressed and deduplicated during a dry run.
 .sp
 See the output of the "borg help patterns" command for more help on exclude patterns.
+.sp
 See the output of the "borg help placeholders" command for more help on placeholders.
 .SH OPTIONS
 .sp
@@ -154,8 +156,26 @@ experimental: do not synchronize the cache. Implies not using the files cache.
 .BI \-\-stdin\-name \ NAME
 use NAME in archive for stdin data (default: \(aqstdin\(aq)
 .TP
+.BI \-\-stdin\-user \ USER
+set user USER in archive for stdin data (default: \(aqroot\(aq)
+.TP
+.BI \-\-stdin\-group \ GROUP
+set group GROUP in archive for stdin data (default: \(aqroot\(aq)
+.TP
+.BI \-\-stdin\-mode \ M
+set mode to M in archive for stdin data (default: 0660)
+.TP
 .B \-\-content\-from\-command
 interpret PATH as command and store its stdout. See also section Reading from stdin below.
+.TP
+.B \-\-paths\-from\-stdin
+read DELIM\-separated list of paths to backup from stdin. Will not recurse into directories.
+.TP
+.B \-\-paths\-from\-command
+interpret PATH as command and treat its output as \fB\-\-paths\-from\-stdin\fP
+.TP
+.BI \-\-paths\-delimiter \ DELIM
+set path delimiter for \fB\-\-paths\-from\-stdin\fP and \fB\-\-paths\-from\-command\fP (default: n)
 .UNINDENT
 .SS Exclusion options
 .INDENT 0.0
@@ -188,7 +208,7 @@ exclude files flagged NODUMP
 .INDENT 0.0
 .TP
 .B \-x\fP,\fB  \-\-one\-file\-system
-stay in the same file system and do not store mount points of other file systems
+stay in the same file system and do not store mount points of other file systems.  This might behave different from your expectations, see the docs.
 .TP
 .B \-\-numeric\-owner
 only store numeric user and group identifiers
@@ -327,6 +347,17 @@ all of its contents will be omitted from the backup.  If, however, you wish to
 only include the objects specified by \fB\-\-exclude\-if\-present\fP in your backup,
 and not include any other contents of the containing folder, this can be enabled
 through using the \fB\-\-keep\-exclude\-tags\fP option.
+.sp
+The \fB\-x\fP or \fB\-\-one\-file\-system\fP option excludes directories, that are mountpoints (and everything in them).
+It detects mountpoints by comparing the device number from the output of \fBstat()\fP of the directory and its
+parent directory. Specifically, it excludes directories for which \fBstat()\fP reports a device number different
+from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories
+with device number different from their parent, which the kernel does not consider a mountpoint and also the
+other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL
+subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when
+using \fB\-\-one\-file\-system\fP, one should make doubly sure that the backup works as intended especially when using
+btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution
+installer.
 .SS Item flags
 .sp
 \fB\-\-list\fP outputs a list of all files, directories and other

docs/man/borg-delete.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DELETE 1 "2020-10-04" "" "borg backup tool"
+.TH BORG-DELETE 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-DIFF 1 "2020-12-06" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .

docs/man/borg-export-tar.1

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

docs/man/borg-extract.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXTRACT 1 "2020-10-04" "" "borg backup tool"
+.TH BORG-EXTRACT 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-INFO 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-INIT 1 "2020-12-06" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .

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

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-10-04" "" "borg backup tool"
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-KEY-EXPORT 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-KEY-IMPORT 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-KEY 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-LIST 1 "2020-12-06" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .
@@ -122,6 +122,13 @@ lrwxrwxrwx root   root          0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdif
 \-rwxr\-xr\-x root   root       2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
 \&...
 
+$ borg list /path/to/repo::root\-2016\-02\-15 \-\-pattern "\- bin/ba*"
+drwxr\-xr\-x root   root          0 Mon, 2016\-02\-15 17:44:27 .
+drwxrwxr\-x root   root          0 Mon, 2016\-02\-15 19:04:49 bin
+lrwxrwxrwx root   root          0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff
+\-rwxr\-xr\-x root   root       2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
+\&...
+
 $ borg list /path/to/repo::archiveA \-\-format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
 drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 .
 drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code

docs/man/borg-mount.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-MOUNT 1 "2020-10-04" "" "borg backup tool"
+.TH BORG-MOUNT 1 "2020-12-06" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .

docs/man/borg-patterns.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PATTERNS 1 "2020-10-04" "" "borg backup tool"
+.TH BORG-PATTERNS 1 "2020-12-06" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .
@@ -173,6 +173,8 @@ $ cat >exclude.txt <<EOF
 fm:aa:something/*
 re:^home/[^/]\e.tmp/
 sh:home/*/.thumbnails
+# Example with spaces, no need to escape as it is processed by borg
+some file with spaces.txt
 EOF
 $ borg create \-\-exclude\-from exclude.txt backup /
 .ft P

docs/man/borg-placeholders.1

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

docs/man/borg-prune.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PRUNE 1 "2020-10-04" "" "borg backup tool"
+.TH BORG-PRUNE 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-RECREATE 1 "2020-12-06" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .

docs/man/borg-rename.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RENAME 1 "2020-10-04" "" "borg backup tool"
+.TH BORG-RENAME 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-SERVE 1 "2020-12-06" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .

docs/man/borg-umount.1

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

docs/man/borg-upgrade.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UPGRADE 1 "2020-10-04" "" "borg backup tool"
+.TH BORG-UPGRADE 1 "2020-12-06" "" "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 "2020-10-04" "" "borg backup tool"
+.TH BORG-WITH-LOCK 1 "2020-12-06" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .

docs/man/borg.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG 1 "2020-10-04" "" "borg backup tool"
+.TH BORG 1 "2020-12-06" "" "borg backup tool"
 .SH NAME
 borg \- deduplicating and encrypting backup tool
 .
@@ -441,6 +441,11 @@ the \fB\-\-rsh CMD\fP commandline option overrides the environment variable.
 When set, use the given path as borg executable on the remote (defaults to "borg" if unset).
 Using \fB\-\-remote\-path PATH\fP commandline option overrides the environment variable.
 .TP
+.B BORG_FILES_CACHE_SUFFIX
+When set to a value at least one character long, instructs borg to use a specifically named
+(based on the suffix) alternative files cache. This can be used to avoid loading and saving
+cache entries for backup sources other than the current sources.
+.TP
 .B BORG_FILES_CACHE_TTL
 When set to a numeric value, this determines the maximum "time to live" for the files cache
 entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
@@ -451,6 +456,23 @@ When set to no (default: yes), system information (like OS, Python version, ...)
 exceptions is not shown.
 Please only use for good reasons as it makes issues harder to analyze.
 .TP
+.B BORG_FUSE_IMPL
+Choose the lowlevel FUSE implementation borg shall use for \fBborg mount\fP\&.
+This is a comma\-separated list of implementation names, they are tried in the
+given order, e.g.:
+.INDENT 7.0
+.IP \(bu 2
+\fBpyfuse3,llfuse\fP: default, first try to load pyfuse3, then try to load llfuse.
+.IP \(bu 2
+\fBllfuse,pyfuse3\fP: first try to load llfuse, then try to load pyfuse3.
+.IP \(bu 2
+\fBpyfuse3\fP: only try to load pyfuse3
+.IP \(bu 2
+\fBllfuse\fP: only try to load llfuse
+.IP \(bu 2
+\fBnone\fP: do not try to load an implementation
+.UNINDENT
+.TP
 .B BORG_WORKAROUNDS
 A list of comma separated strings that trigger workarounds in borg,
 e.g. to work around bugs in other software.

docs/man/borgfs.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORGFS 1 "2020-10-04" "" "borg backup tool"
+.TH BORGFS 1 "2020-12-06" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .