build_man

docs/man/borg-benchmark-crud.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK-CRUD 1 "2020-04-12" "" "borg backup tool"
+.TH BORG-BENCHMARK-CRUD 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-BENCHMARK 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-CHECK 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-COMMON 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-COMPACT 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-COMPRESSION 1 "2020-04-21" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .

docs/man/borg-config.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CONFIG 1 "2020-04-12" "" "borg backup tool"
+.TH BORG-CONFIG 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-CREATE 1 "2020-04-21" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .

docs/man/borg-delete.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DELETE 1 "2020-04-12" "" "borg backup tool"
+.TH BORG-DELETE 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-DIFF 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-EXPORT-TAR 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-EXTRACT 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-INFO 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-INIT 1 "2020-04-21" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .
@@ -43,7 +43,11 @@ Encryption can be enabled at repository init time. It cannot be changed later.
 It is not recommended to work without encryption. Repository encryption protects
 you e.g. against the case that an attacker has access to your backup repository.
 .sp
-But be careful with the key / the passphrase:
+Borg relies on randomly generated key material and uses that for chunking, id
+generation, encryption and authentication. The key material is encrypted using
+the passphrase you give before it is stored on\-disk.
+.sp
+You need to be careful with the key / the passphrase:
 .sp
 If you want "passphrase\-only" security, use one of the repokey modes. The
 key will be stored inside the repository (in its "config" file). In above
@@ -81,6 +85,12 @@ a different keyboard layout.
 You can change your passphrase for existing repos at any time, it won\(aqt affect
 the encryption/decryption key or other secrets.
 .SS Encryption modes
+.sp
+You can choose from the encryption modes seen in the table below on a per\-repo
+basis. The mode determines encryption algorithm, hash/MAC algorithm and also the
+key storage location.
+.sp
+Example: \fIborg init \-\-encryption repokey ...\fP
 .\" nanorst: inline-fill
 .
 .TS
@@ -126,7 +136,8 @@ _
 .\" nanorst: inline-replace
 .
 .sp
-\fIMarked modes\fP are new in Borg 1.1 and are not backwards\-compatible with Borg 1.0.x.
+Modes \fImarked like this\fP in the above table are new in Borg 1.1 and are not
+backwards\-compatible with Borg 1.0.x.
 .sp
 On modern Intel/AMD CPUs (except very cheap ones), AES is usually
 hardware\-accelerated.
@@ -159,8 +170,8 @@ from the other blake2 modes.
 This mode is new and \fInot\fP compatible with Borg 1.0.x.
 .sp
 \fInone\fP mode uses no encryption and no authentication. It uses SHA256 as chunk
-ID hash. Not recommended, rather consider using an authenticated or
-authenticated/encrypted mode. This mode has possible denial\-of\-service issues
+ID hash. This mode is not recommended, you should rather consider using an authenticated
+or authenticated/encrypted mode. This mode has possible denial\-of\-service issues
 when running \fBborg create\fP on contents controlled by an attacker.
 Use it only for new repositories where no encryption is wanted \fBand\fP when compatibility
 with 1.0.x is important. If compatibility with 1.0.x is not important, use
@@ -203,9 +214,11 @@ $ borg init \-\-encryption=repokey\-blake2 /path/to/repo
 $ borg init \-\-encryption=none /path/to/repo
 
 # Remote repository (accesses a remote borg via ssh)
+# repokey: stores the (encrypted) key into <REPO_DIR>/config
 $ borg init \-\-encryption=repokey\-blake2 user@hostname:backup
 
-# Remote repository (store the key your home dir)
+# Remote repository (accesses a remote borg via ssh)
+# keyfile: stores the (encrypted) key into ~/.config/borg/keys/
 $ borg init \-\-encryption=keyfile user@hostname:backup
 .ft P
 .fi

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

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-04-12" "" "borg backup tool"
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-KEY-EXPORT 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-KEY-IMPORT 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-KEY 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-LIST 1 "2020-04-21" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .

docs/man/borg-mount.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-MOUNT 1 "2020-04-12" "" "borg backup tool"
+.TH BORG-MOUNT 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-PATTERNS 1 "2020-04-21" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .
@@ -37,17 +37,27 @@ 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.
+will look like \fIrelative/.../file.ext\fP\&. When you give \fI/absolute/\fP as
+root, they will look like \fI/absolute/.../file.ext\fP\&.
+.sp
+File paths in Borg archives are always stored normalized and relative.
+This means that e.g. \fBborg create /path/to/repo ../some/path\fP will
+store all files as \fIsome/path/.../file.ext\fP and \fBborg create
+/path/to/repo /home/user\fP will store all files as
+\fIhome/user/.../file.ext\fP\&.
 .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
-option.
+\fB\-\-exclude\fP patterns and shell\-style is used for the experimental
+\fB\-\-pattern\fP option.
+.sp
+Starting with Borg 1.2, for all but regular expression pattern matching
+styles, all paths are treated as relative, meaning that a leading path
+separator is removed after normalizing and before matching. This allows
+you to use absolute or relative patterns arbitrarily.
 .sp
-If followed by a colon (\(aq:\(aq) the first two characters of a pattern are used as a
-style selector. Explicit style selection is necessary when a
+If followed by a colon (\(aq:\(aq) the first two characters of a pattern are
+used as a style selector. Explicit style selection is necessary when a
 non\-default style is desired or when the desired pattern starts with
 two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP).
 .INDENT 0.0
@@ -65,14 +75,15 @@ 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.
+separator, a \(aq*\(aq is appended before matching is attempted. A leading
+path separator is always removed.
 .TP
 .B Shell\-style patterns, selector \fIsh:\fP
 This is the default style for \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP\&.
 Like fnmatch patterns these are similar to shell patterns. The difference
 is that the pattern may include \fI**/\fP for matching zero or more directory
 levels, \fI*\fP for matching zero or more arbitrary characters with the
-exception of any path separator.
+exception of any path separator. A leading path separator is always removed.
 .TP
 .B Regular expressions, selector \fIre:\fP
 Regular expressions similar to those found in Perl are supported. Unlike
@@ -86,13 +97,14 @@ the re module\fP\&.
 .TP
 .B Path prefix, selector \fIpp:\fP
 This pattern style is useful to match whole sub\-directories. The pattern
-\fIpp:root/somedir\fP matches \fIroot/somedir\fP and everything therein.
+\fIpp:root/somedir\fP matches \fIroot/somedir\fP and everything therein. A leading
+path separator is always removed.
 .TP
 .B Path full\-match, selector \fIpf:\fP
 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 path must be given.
-\fIpf:root/file.ext\fP matches \fIroot/file.txt\fP only.
+unspecified parts \- the full path must be given. \fIpf:root/file.ext\fP matches
+\fIroot/file.txt\fP only. A leading path separator is always removed.
 .sp
 Implementation note: this is implemented via very time\-efficient O(1)
 hashtable lookups (this means you can have huge amounts of such patterns
@@ -144,7 +156,7 @@ $ borg create \-e \(aq*.o\(aq backup /
 $ borg create \-e \(aq/home/*/junk\(aq backup /
 
 # Exclude the contents of \(aq/home/user/cache\(aq but not the directory itself:
-$ borg create \-e /home/user/cache/ backup /
+$ borg create \-e home/user/cache/ backup /
 
 # The file \(aq/home/user/cache/important\(aq is *not* backed up:
 $ borg create \-e /home/user/cache/ backup / /home/user/cache/important
@@ -159,8 +171,8 @@ $ cat >exclude.txt <<EOF
 /home/*/junk
 *.tmp
 fm:aa:something/*
-re:^/home/[^/]\e.tmp/
-sh:/home/*/.thumbnails
+re:^home/[^/]\e.tmp/
+sh:home/*/.thumbnails
 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-04-12" "" "borg backup tool"
+.TH BORG-PLACEHOLDERS 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-PRUNE 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-RECREATE 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-RENAME 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-SERVE 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-UMOUNT 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-UPGRADE 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG-WITH-LOCK 1 "2020-04-21" "" "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-04-12" "" "borg backup tool"
+.TH BORG 1 "2020-04-21" "" "borg backup tool"
 .SH NAME
 borg \- deduplicating and encrypting backup tool
 .

docs/man/borgfs.1

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