man pages: add borg(1) master/intro page

27 files changed, 653 insertions, 41 deletions

diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1
index b5870e563..b8162436b 100644
--- a/docs/man/borg-break-lock.1
+++ b/docs/man/borg-break-lock.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BREAK-LOCK 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .
diff --git a/docs/man/borg-change-passphrase.1 b/docs/man/borg-change-passphrase.1
index fb32bfa20..b74dd336b 100644
--- a/docs/man/borg-change-passphrase.1
+++ b/docs/man/borg-change-passphrase.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CHANGE-PASSPHRASE 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-CHANGE-PASSPHRASE 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-change-passphrase \- Change repository key file passphrase
 .
diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1
index 6608887bc..8a0ec36bf 100644
--- a/docs/man/borg-check.1
+++ b/docs/man/borg-check.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CHECK 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-CHECK 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .
diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1
index 17afcff95..e480c1f8d 100644
--- a/docs/man/borg-common.1
+++ b/docs/man/borg-common.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMMON 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-COMMON 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .
diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1
index cc5fbafd7..51124fea3 100644
--- a/docs/man/borg-compression.1
+++ b/docs/man/borg-compression.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMPRESSION 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-COMPRESSION 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .
diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1
index 3e30a343e..d01d77e27 100644
--- a/docs/man/borg-create.1
+++ b/docs/man/borg-create.1
@@ -100,10 +100,10 @@ read exclude patterns from EXCLUDEFILE, one per line
 exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosaurus.com/cachedir/spec.html\fP)
 .TP
 .BI \-\-exclude\-if\-present \ NAME
-exclude directories that are tagged by containing a filesystem object with                                          the given 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
-keep tag objects (i.e.: arguments to \-\-exclude\-if\-present) in otherwise                                          excluded caches/directories
+keep tag objects (i.e.: arguments to \-\-exclude\-if\-present) in otherwise excluded caches/directories
 .UNINDENT
 .SS Filesystem options
 .INDENT 0.0
@@ -216,15 +216,12 @@ $ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f} ~
 .fi
 .UNINDENT
 .UNINDENT
-.SS Notes
-.INDENT 0.0
-.IP \(bu 2
-the \-\-exclude patterns are not like tar. In tar \-\-exclude .bundler/gems will
+.SH NOTES
+.sp
+The \-\-exclude patterns are not like tar. In tar \-\-exclude .bundler/gems will
 exclude foo/.bundler/gems. In borg it will not, you need to use \-\-exclude
 \(aq*/.bundler/gems\(aq to get the same effect. See \fBborg help patterns\fP for
 more information.
-.UNINDENT
-.SH NOTES
 .SS Item flags
 .sp
 \fB\-\-list\fP outputs a list of all files, directories and other
diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1
index e3a73797a..5b0ec5296 100644
--- a/docs/man/borg-delete.1
+++ b/docs/man/borg-delete.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DELETE 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-DELETE 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .
diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1
index dc3d9be99..f488a72ac 100644
--- a/docs/man/borg-diff.1
+++ b/docs/man/borg-diff.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DIFF 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-DIFF 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .
diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1
index 2770a5142..426be31e0 100644
--- a/docs/man/borg-extract.1
+++ b/docs/man/borg-extract.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXTRACT 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-EXTRACT 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .
diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1
index 2609912df..305f18fad 100644
--- a/docs/man/borg-info.1
+++ b/docs/man/borg-info.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INFO 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-INFO 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .
diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1
index 40d8a25dd..bbe020c43 100644
--- a/docs/man/borg-init.1
+++ b/docs/man/borg-init.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INIT 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-INIT 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .
@@ -82,32 +82,33 @@ You can change your passphrase for existing repos at any time, it won\(aqt affec
 the encryption/decryption key or other secrets.
 .SS Encryption modes
 .sp
-repokey and keyfile use AES\-CTR\-256 for encryption and HMAC\-SHA256 for
+\fIrepokey\fP and \fIkeyfile\fP use AES\-CTR\-256 for encryption and HMAC\-SHA256 for
 authentication in an encrypt\-then\-MAC (EtM) construction. The chunk ID hash
 is HMAC\-SHA256 as well (with a separate key).
 These modes are compatible with borg 1.0.x.
 .sp
-repokey\-blake2 and keyfile\-blake2 are also authenticated encryption modes,
+\fIrepokey\-blake2\fP and \fIkeyfile\-blake2\fP are also authenticated encryption modes,
 but use BLAKE2b\-256 instead of HMAC\-SHA256 for authentication. The chunk ID
 hash is a keyed BLAKE2b\-256 hash.
-These modes are new and not compatible with borg 1.0.x.
+These modes are new and \fInot\fP compatible with borg 1.0.x.
 .sp
-"authenticated" mode uses no encryption, but authenticates repository contents
+\fIauthenticated\fP mode uses no encryption, but authenticates repository contents
 through the same keyed BLAKE2b\-256 hash as the other blake2 modes (it uses it
 as chunk ID hash). The key is stored like repokey.
 This mode is new and not compatible with borg 1.0.x.
 .sp
-"none" mode uses no encryption and no authentication. It uses sha256 as chunk
+\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 is compatible with borg 1.0.x.
 .sp
 Hardware acceleration will be used automatically.
 .sp
-On modern Intel/AMD CPUs (except very cheap ones), AES is usually hw
-accelerated. BLAKE2b is faster than sha256 on Intel/AMD 64bit CPUs.
+On modern Intel/AMD CPUs (except very cheap ones), AES is usually
+hardware\-accelerated. BLAKE2b is faster than SHA256 on Intel/AMD 64bit CPUs,
+which makes \fIauthenticated\fP faster than \fInone\fP\&.
 .sp
-On modern ARM CPUs, NEON provides hw acceleration for sha256 making it faster
+On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster
 than BLAKE2b\-256 there.
 .SH OPTIONS
 .sp
@@ -122,7 +123,7 @@ repository to create
 .INDENT 0.0
 .TP
 .B \-e\fP,\fB  \-\-encryption
-select encryption key mode (default: "None")
+select encryption key mode
 .TP
 .B \-a\fP,\fB  \-\-append\-only
 create an append\-only mode repository
diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1
index 63a58b0c5..86a30ebfa 100644
--- a/docs/man/borg-key-change-passphrase.1
+++ b/docs/man/borg-key-change-passphrase.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-key-change-passphrase \- Change repository key file passphrase
 .
diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1
index 3a8158146..672023032 100644
--- a/docs/man/borg-key-export.1
+++ b/docs/man/borg-key-export.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-EXPORT 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-KEY-EXPORT 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .
diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1
index 7215df92a..91ce569dd 100644
--- a/docs/man/borg-key-import.1
+++ b/docs/man/borg-key-import.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-IMPORT 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-KEY-IMPORT 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .
diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1
index c1c5e95f1..774c9199b 100644
--- a/docs/man/borg-key-migrate-to-repokey.1
+++ b/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-02-05" "" "borg backup tool"
+.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
 .
diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1
new file mode 100644
index 000000000..2d82f003c
--- /dev/null
+++ b/docs/man/borg-key.1
@@ -0,0 +1,47 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-KEY 1 "2017-02-11" "" "borg backup tool"
+.SH NAME
+borg-key \- Manage a keyfile or repokey of a repository
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH SYNOPSIS
+.nf
+borg key export ...
+borg key import ...
+borg key change\-passphrase ...
+borg key migrate\-to\-repokey ...
+.fi
+.sp
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP, \fIborg\-key\-migrate\-to\-repokey(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.
diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1
index e788bdbae..63a12ceec 100644
--- a/docs/man/borg-mount.1
+++ b/docs/man/borg-mount.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-MOUNT 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-MOUNT 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .
diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1
index f814edc3c..646694bfc 100644
--- a/docs/man/borg-patterns.1
+++ b/docs/man/borg-patterns.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PATTERNS 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-PATTERNS 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .
diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1
index bff600a45..49cfb6dc7 100644
--- a/docs/man/borg-placeholders.1
+++ b/docs/man/borg-placeholders.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PLACEHOLDERS 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-PLACEHOLDERS 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-placeholders \- Details regarding placeholders
 .
diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1
index 81756e66d..ff8afa1d5 100644
--- a/docs/man/borg-prune.1
+++ b/docs/man/borg-prune.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PRUNE 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-PRUNE 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .
diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1
index 55b01cc82..db822491d 100644
--- a/docs/man/borg-recreate.1
+++ b/docs/man/borg-recreate.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RECREATE 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-RECREATE 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .
diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1
index ee568f2f5..e3c1ee773 100644
--- a/docs/man/borg-rename.1
+++ b/docs/man/borg-rename.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RENAME 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-RENAME 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-rename \- Rename an existing archive
 .
diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1
index 673ae2696..ee62ee7f8 100644
--- a/docs/man/borg-serve.1
+++ b/docs/man/borg-serve.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-SERVE 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-SERVE 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .
diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1
index 4de127a5c..7d8af5878 100644
--- a/docs/man/borg-umount.1
+++ b/docs/man/borg-umount.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UMOUNT 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-UMOUNT 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .
diff --git a/docs/man/borg-upgrade.1 b/docs/man/borg-upgrade.1
index d329fa885..0c0df0d59 100644
--- a/docs/man/borg-upgrade.1
+++ b/docs/man/borg-upgrade.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UPGRADE 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-UPGRADE 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-upgrade \- upgrade a repository from a previous version
 .
diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1
index d6e19958b..2db9c3fc8 100644
--- a/docs/man/borg-with-lock.1
+++ b/docs/man/borg-with-lock.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-WITH-LOCK 1 "2017-02-05" "" "borg backup tool"
+.TH BORG-WITH-LOCK 1 "2017-02-11" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .
diff --git a/docs/man/borg.1 b/docs/man/borg.1
new file mode 100644
index 000000000..b720d71c2
--- /dev/null
+++ b/docs/man/borg.1
@@ -0,0 +1,567 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg \- deduplicating and encrypting backup tool
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH SYNOPSIS
+.sp
+borg <command> [options] [arguments]
+.SH DESCRIPTION
+.\" we don't include the README.rst here since we want to keep this terse.
+.
+.sp
+BorgBackup (short: Borg) is a deduplicating backup program.
+Optionally, it supports compression and authenticated encryption.
+.sp
+The main goal of Borg is to provide an efficient and secure way to backup data.
+The data deduplication technique used makes Borg suitable for daily backups
+since only changes are stored.
+The authenticated encryption technique makes it suitable for backups to not
+fully trusted targets.
+.sp
+Borg stores a set of files in an \fIarchive\fP\&. A \fIrepository\fP is a collection
+of \fIarchives\fP\&. The format of repositories is Borg\-specific. Borg does not
+distinguish archives from each other in a any way other than their name,
+it does not matter when or where archives where created (eg. different hosts).
+.SH EXAMPLES
+.SS A step\-by\-step example
+.INDENT 0.0
+.IP 1. 3
+Before a backup can be made a repository has to be initialized:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg init \-\-encryption=repokey /path/to/repo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 2. 3
+Backup the \fB~/src\fP and \fB~/Documents\fP directories into an archive called
+\fIMonday\fP:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg create /path/to/repo::Monday ~/src ~/Documents
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 3. 3
+The next day create a new archive called \fITuesday\fP:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg create \-\-stats /path/to/repo::Tuesday ~/src ~/Documents
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This backup will be a lot quicker and a lot smaller since only new never
+before seen data is stored. The \fB\-\-stats\fP option causes Borg to
+output statistics about the newly created archive such as the amount of unique
+data (not shared with other archives):
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+Archive name: Tuesday
+Archive fingerprint: bd31004d58f51ea06ff735d2e5ac49376901b21d58035f8fb05dbf866566e3c2
+Time (start): Tue, 2016\-02\-16 18:15:11
+Time (end):   Tue, 2016\-02\-16 18:15:11
+
+Duration: 0.19 seconds
+Number of files: 127
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+                      Original size      Compressed size    Deduplicated size
+This archive:                4.16 MB              4.17 MB             26.78 kB
+All archives:                8.33 MB              8.34 MB              4.19 MB
+
+                      Unique chunks         Total chunks
+Chunk index:                     132                  261
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 4. 3
+List all archives in the repository:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg list /path/to/repo
+Monday                               Mon, 2016\-02\-15 19:14:44
+Tuesday                              Tue, 2016\-02\-16 19:15:11
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 5. 3
+List the contents of the \fIMonday\fP archive:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg list /path/to/repo::Monday
+drwxr\-xr\-x user   group          0 Mon, 2016\-02\-15 18:22:30 home/user/Documents
+\-rw\-r\-\-r\-\- user   group       7961 Mon, 2016\-02\-15 18:22:30 home/user/Documents/Important.doc
+\&...
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 6. 3
+Restore the \fIMonday\fP archive by extracting the files relative to the current directory:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg extract /path/to/repo::Monday
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 7. 3
+Recover disk space by manually deleting the \fIMonday\fP archive:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg delete /path/to/repo::Monday
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Borg is quiet by default (it works on WARNING log level).
+You can use options like \fB\-\-progress\fP or \fB\-\-list\fP to get specific
+reports during command execution.  You can also add the \fB\-v\fP (or
+\fB\-\-verbose\fP or \fB\-\-info\fP) option to adjust the log level to INFO to
+get other informational messages.
+.UNINDENT
+.UNINDENT
+.SH NOTES
+.SS Repository URLs
+.sp
+\fBLocal filesystem\fP (or locally mounted network filesystem):
+.sp
+\fB/path/to/repo\fP \- filesystem path to repo directory, absolute path
+.sp
+\fBpath/to/repo\fP \- filesystem path to repo directory, relative path
+.sp
+Also, stuff like \fB~/path/to/repo\fP or \fB~other/path/to/repo\fP works (this is
+expanded by your shell).
+.sp
+Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style.
+.sp
+\fBRemote repositories\fP accessed via ssh \fI\%user@host\fP:
+.sp
+\fBuser@host:/path/to/repo\fP \- remote repo, absolute path
+.sp
+\fBssh://user@host:port/path/to/repo\fP \- same, alternative syntax, port can be given
+.sp
+\fBRemote repositories with relative pathes\fP can be given using this syntax:
+.sp
+\fBuser@host:path/to/repo\fP \- path relative to current directory
+.sp
+\fBuser@host:~/path/to/repo\fP \- path relative to user\(aqs home directory
+.sp
+\fBuser@host:~other/path/to/repo\fP \- path relative to other\(aqs home directory
+.sp
+Note: giving \fBuser@host:/./path/to/repo\fP or \fBuser@host:/~/path/to/repo\fP or
+\fBuser@host:/~other/path/to/repo\fP is also supported, but not required here.
+.sp
+\fBRemote repositories with relative pathes, alternative syntax with port\fP:
+.sp
+\fBssh://user@host:port/./path/to/repo\fP \- path relative to current directory
+.sp
+\fBssh://user@host:port/~/path/to/repo\fP \- path relative to user\(aqs home directory
+.sp
+\fBssh://user@host:port/~other/path/to/repo\fP \- path relative to other\(aqs home directory
+.sp
+If you frequently need the same repo URL, it is a good idea to set the
+\fBBORG_REPO\fP environment variable to set a default for the repo URL:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+export BORG_REPO=\(aqssh://user@host:port/path/to/repo\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Then just leave away the repo URL if only a repo URL is needed and you want
+to use the default \- it will be read from BORG_REPO then.
+.sp
+Use \fB::\fP syntax to give the repo URL when syntax requires giving a positional
+argument for the repo (e.g. \fBborg mount :: /mnt\fP).
+.SS Repository / Archive Locations
+.sp
+Many commands want either a repository (just give the repo URL, see above) or
+an archive location, which is a repo URL followed by \fB::archive_name\fP\&.
+.sp
+Archive names must not contain the \fB/\fP (slash) character. For simplicity,
+maybe also avoid blanks or other characters that have special meaning on the
+shell or in a filesystem (borg mount will use the archive name as directory
+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
+.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
+warnings, errors and critical messages, unless output has been requested
+by supplying an option that implies output (eg, \-\-list or \-\-progress).
+.sp
+Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
+.sp
+Use \fB\-\-debug\fP to set DEBUG log level \-
+to get debug, info, warning, error and critical level output.
+.sp
+Use \fB\-\-info\fP (or \fB\-v\fP or \fB\-\-verbose\fP) to set INFO log level \-
+to get info, warning, error and critical level output.
+.sp
+Use \fB\-\-warning\fP (default) to set WARNING log level \-
+to get warning, error and critical level output.
+.sp
+Use \fB\-\-error\fP to set ERROR log level \-
+to get error and critical level output.
+.sp
+Use \fB\-\-critical\fP to set CRITICAL log level \-
+to get critical level output.
+.sp
+While you can set misc. log levels, do not expect that every command will
+give different output on different log levels \- it\(aqs just a possibility.
+.sp
+\fBWARNING:\fP
+.INDENT 0.0
+.INDENT 3.5
+Options \-\-critical and \-\-error are provided for completeness,
+their usage is not recommended as you might miss important information.
+.UNINDENT
+.UNINDENT
+.SS Return codes
+.sp
+Borg can exit with the following return codes (rc):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+0 = success (logged as INFO)
+1 = warning (operation reached its normal end, but there were warnings \-
+    you should check the log, logged as WARNING)
+2 = error (like a fatal error, a local or remote exception, the operation
+    did not reach its normal end, logged as ERROR)
+128+N = killed by signal N (e.g. 137 == kill \-9)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If you use \fB\-\-show\-rc\fP, the return code is also logged at the indicated
+level as the last log entry.
+.SS Environment Variables
+.sp
+Borg uses some environment variables for automation:
+.INDENT 0.0
+.TP
+.B General:
+.INDENT 7.0
+.TP
+.B BORG_REPO
+When set, use the value to give the default repository location. If a command needs an archive
+parameter, you can abbreviate as \fI::archive\fP\&. If a command needs a repository parameter, you
+can either leave it away or abbreviate as \fI::\fP, if a positional parameter is required.
+.TP
+.B BORG_PASSPHRASE
+When set, use the value to answer the passphrase question for encrypted repositories.
+It is used when a passphrase is needed to access a encrypted repo as well as when a new
+passphrase should be initially set when initializing an encrypted repo.
+See also BORG_NEW_PASSPHRASE.
+.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 will be checked also.
+Main usecase for this is to fully automate \fBborg change\-passphrase\fP\&.
+.TP
+.B BORG_DISPLAY_PASSPHRASE
+When set, use the value to answer the "display the passphrase for verification" question when defining a new passphrase for encrypted repositories.
+.TP
+.B BORG_LOGGING_CONF
+When set, use the given filename as \fI\%INI\