docs: ran build_man, build_usage

31 files changed, 225 insertions, 82 deletions

diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1
new file mode 100644
index 000000000..ed1a5e1e0
--- /dev/null
+++ b/docs/man/borg-benchmark-crud.1
@@ -0,0 +1,101 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-BENCHMARK-CRUD 1 "2017-05-17" "" "borg backup tool"
+.SH NAME
+borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
+.
+.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 [common options] benchmark crud <options> REPO PATH
+.SH DESCRIPTION
+.sp
+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.
+.sp
+Make sure you have free space there, you\(aqll need about 1GB each (+ overhead).
+.sp
+If your repository is encrypted and borg needs a passphrase to unlock the key, use:
+.sp
+BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
+.sp
+Measurements are done with different input file sizes and counts.
+The file contents are very artificial (either all zero or all random),
+thus the measurement results do not necessarily reflect performance with real data.
+Also, due to the kind of content used, no compression is used in these benchmarks.
+.INDENT 0.0
+.TP
+.B C\- == borg create (1st archive creation, no compression, do not use files cache)
+C\-Z\- == all\-zero files. full dedup, this is primarily measuring reader/chunker/hasher.
+C\-R\- == random files. no dedup, measuring throughput through all processing stages.
+.TP
+.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.
+U\-Z\- == needs to check the 2 all\-zero chunks\(aq existence in the repo.
+U\-R\- == needs to check existence of a lot of different chunks in the repo.
+.TP
+.B D\- == borg delete archive (delete last remaining archive, measure deletion + compaction)
+D\-Z\- == few chunks to delete / few segments to compact/remove.
+D\-R\- == many chunks to delete / many segments to compact/remove.
+.UNINDENT
+.sp
+Please note that there might be quite some variance in these measurements.
+Try multiple measurements and having a otherwise idle machine (and network, if you use it).
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B REPO
+repo to use for benchmark (must exist)
+.TP
+.B PATH
+path were to create benchmark input data
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.
diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1
new file mode 100644
index 000000000..0f46eb8a6
--- /dev/null
+++ b/docs/man/borg-benchmark.1
@@ -0,0 +1,47 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-BENCHMARK 1 "2017-05-17" "" "borg backup tool"
+.SH NAME
+borg-benchmark \- benchmark command
+.
+.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 [common options] benchmark crud ...
+.fi
+.sp
+.SH DESCRIPTION
+.sp
+These commands do various benchmarks.
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP, \fIborg\-benchmark\-crud(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.
diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1
index c83b2d6d4..a7275b0c0 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-04-29" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg break\-lock <options> REPOSITORY
+borg [common options] break\-lock <options> REPOSITORY
 .SH DESCRIPTION
 .sp
 This command breaks the repository and cache locks.
diff --git a/docs/man/borg-change-passphrase.1 b/docs/man/borg-change-passphrase.1
index 1a73f339c..a4649a71e 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-04-29" "" "borg backup tool"
+.TH BORG-CHANGE-PASSPHRASE 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-change-passphrase \- Change repository key file passphrase
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg change\-passphrase <options> REPOSITORY
+borg [common options] change\-passphrase <options> REPOSITORY
 .SH DESCRIPTION
 .sp
 The key files used for repository encryption are optionally passphrase
diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1
index ea4ef558a..cb694cac1 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-04-29" "" "borg backup tool"
+.TH BORG-CHECK 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg check <options> REPOSITORY_OR_ARCHIVE
+borg [common options] check <options> REPOSITORY_OR_ARCHIVE
 .SH DESCRIPTION
 .sp
 The check command verifies the consistency of a repository and the corresponding archives.
@@ -120,9 +120,6 @@ attempt to repair any inconsistencies found
 .TP
 .B \-\-save\-space
 work slower, but using less space
-.TP
-.B \-p\fP,\fB  \-\-progress
-show progress display while checking
 .UNINDENT
 .SS filters
 .INDENT 0.0
diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1
index 3ca2d1f9c..223fd33a7 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-04-29" "" "borg backup tool"
+.TH BORG-COMMON 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .
@@ -54,6 +54,9 @@ enable debug output, work on log level DEBUG
 .BI \-\-debug\-topic \ TOPIC
 enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
 .TP
+.B \-p\fP,\fB  \-\-progress
+show progress information
+.TP
 .B \-\-log\-json
 Output one JSON object per log line instead of formatted text.
 .TP
@@ -80,6 +83,9 @@ set remote network upload rate limit in kiByte/s (default: 0=unlimited)
 .TP
 .B \-\-consider\-part\-files
 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".
 .UNINDENT
 .SH SEE ALSO
 .sp
diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1
index da3c8487d..9e176f224 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-04-29" "" "borg backup tool"
+.TH BORG-COMPRESSION 1 "2017-05-17" "" "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 8196befaf..0cae7ca0c 100644
--- a/docs/man/borg-create.1
+++ b/docs/man/borg-create.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CREATE 1 "2017-04-29" "" "borg backup tool"
+.TH BORG-CREATE 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg create <options> ARCHIVE PATH
+borg [common options] create <options> ARCHIVE PATH
 .SH DESCRIPTION
 .sp
 This command creates a backup archive containing all files found while recursively
@@ -63,6 +63,10 @@ creation of a new archive to ensure fast operation. This is because the file cac
 is used to determine changed files quickly uses absolute filenames.
 If this is not possible, consider creating a bind mount to a stable location.
 .sp
+The \-\-progress option shows (from left to right) Original, Compressed and Deduplicated
+(O, C and D, respectively), then the Number of files (N) processed so far, followed by
+the currently processed path.
+.sp
 See the output of the "borg help patterns" command for more help on exclude patterns.
 See the output of the "borg help placeholders" command for more help on placeholders.
 .SH OPTIONS
@@ -86,9 +90,6 @@ do not create a backup archive
 .B \-s\fP,\fB  \-\-stats
 print statistics for the created archive
 .TP
-.B \-p\fP,\fB  \-\-progress
-show progress display while creating the archive, showing Original, Compressed and Deduplicated sizes, followed by the Number of files seen and the path being processed, default: False
-.TP
 .B \-\-list
 output verbose list of items (files, dirs, ...)
 .TP
diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1
index c911ec823..c7c96aa15 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-04-29" "" "borg backup tool"
+.TH BORG-DELETE 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg delete <options> TARGET
+borg [common options] delete <options> TARGET
 .SH DESCRIPTION
 .sp
 This command deletes an archive from the repository or the complete repository.
@@ -50,9 +50,6 @@ archive or repository to delete
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-p\fP,\fB  \-\-progress
-show progress display while deleting a single archive
-.TP
 .B \-s\fP,\fB  \-\-stats
 print statistics for the deleted archive
 .TP
diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1
index c01f70f4c..b69a792be 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-04-29" "" "borg backup tool"
+.TH BORG-DIFF 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg 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.
diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1
index ecbefc142..73cd98150 100644
--- a/docs/man/borg-export-tar.1
+++ b/docs/man/borg-export-tar.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXPORT-TAR 1 "2017-05-16" "" "borg backup tool"
+.TH BORG-EXPORT-TAR 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg export\-tar <options> ARCHIVE FILE PATH
+borg [common options] export\-tar <options> ARCHIVE FILE PATH
 .SH DESCRIPTION
 .sp
 This command creates a tarball from an archive.
diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1
index 9e8d113d3..dbe9c3537 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-04-29" "" "borg backup tool"
+.TH BORG-EXTRACT 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg extract <options> ARCHIVE PATH
+borg [common options] extract <options> ARCHIVE PATH
 .SH DESCRIPTION
 .sp
 This command extracts the contents of an archive. By default the entire
@@ -45,6 +45,9 @@ See the output of the "borg help patterns" command for more help on exclude patt
 By using \fB\-\-dry\-run\fP, you can do all extraction steps except actually writing the
 output data: reading metadata and data chunks from the repo, checking the hash/hmac,
 decrypting, decompressing.
+.sp
+\fB\-\-progress\fP can be slower than no progress display, since it makes one additional
+pass over the archive metadata.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -60,9 +63,6 @@ paths to extract; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-p\fP,\fB  \-\-progress
-show progress while extracting (may be slower)
-.TP
 .B \-\-list
 output verbose list of items (files, dirs, ...)
 .TP
diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1
index cc165d6d4..f235a866c 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-04-29" "" "borg backup tool"
+.TH BORG-INFO 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg info <options> REPOSITORY_OR_ARCHIVE
+borg [common options] info <options> REPOSITORY_OR_ARCHIVE
 .SH DESCRIPTION
 .sp
 This command displays detailed information about the specified archive or repository.
diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1
index c5eb14dc6..d0e1f5ed7 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-04-29" "" "borg backup tool"
+.TH BORG-INIT 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .
@@ -32,13 +32,13 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg init <options> REPOSITORY
+borg [common options] init <options> REPOSITORY
 .SH DESCRIPTION
 .sp
 This command initializes an empty repository. A repository is a filesystem
 directory containing the deduplicated data from zero or more archives.
 .sp
-Encryption can be enabled at repository init time.
+Encryption can be enabled at repository init time. It cannot be changed later.
 .sp
 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.
@@ -94,8 +94,8 @@ These modes are new and \fInot\fP compatible with borg 1.0.x.
 .sp
 \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.
+as the chunk ID hash). The key is stored like repokey.
+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
@@ -123,7 +123,7 @@ repository to create
 .INDENT 0.0
 .TP
 .B \-e\fP,\fB  \-\-encryption
-select encryption key mode
+select encryption key mode \fB(required)\fP
 .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 6903cf4a1..6457d3a7f 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-04-29" "" "borg backup tool"
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-key-change-passphrase \- Change repository key file passphrase
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg key change\-passphrase <options> REPOSITORY
+borg [common options] key change\-passphrase <options> REPOSITORY
 .SH DESCRIPTION
 .sp
 The key files used for repository encryption are optionally passphrase
diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1
index 6210505f8..9736bba3e 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-04-29" "" "borg backup tool"
+.TH BORG-KEY-EXPORT 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg key export <options> REPOSITORY PATH
+borg [common options] key export <options> REPOSITORY PATH
 .SH DESCRIPTION
 .sp
 If repository encryption is used, the repository is inaccessible
diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1
index a6c0abef1..2ab5af4c2 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-04-29" "" "borg backup tool"
+.TH BORG-KEY-IMPORT 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg key import <options> REPOSITORY PATH
+borg [common options] key import <options> REPOSITORY PATH
 .SH DESCRIPTION
 .sp
 This command allows to restore a key previously backed up with the
diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1
index ea3eed034..178429792 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-04-29" "" "borg backup tool"
+.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg key migrate\-to\-repokey <options> REPOSITORY
+borg [common options] key migrate\-to\-repokey <options> REPOSITORY
 .SH DESCRIPTION
 .sp
 This command migrates a repository from passphrase mode (removed in Borg 1.0)
diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1
index b05452e2e..e61f8e30a 100644
--- a/docs/man/borg-key.1
+++ b/docs/man/borg-key.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY 1 "2017-04-29" "" "borg backup tool"
+.TH BORG-KEY 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-key \- Manage a keyfile or repokey of a repository
 .
@@ -32,10 +32,10 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .nf
-borg key export ...
-borg key import ...
-borg key change\-passphrase ...
-borg key migrate\-to\-repokey ...
+borg [common options] key export ...
+borg [common options] key import ...
+borg [common options] key change\-passphrase ...
+borg [common options] key migrate\-to\-repokey ...
 .fi
 .sp
 .SH SEE ALSO
diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1
index de919db38..66bcf1c17 100644
--- a/docs/man/borg-list.1
+++ b/docs/man/borg-list.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-LIST 1 "2017-04-29" "" "borg backup tool"
+.TH BORG-LIST 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg list <options> REPOSITORY_OR_ARCHIVE PATH
+borg [common options] list <options> REPOSITORY_OR_ARCHIVE PATH
 .SH DESCRIPTION
 .sp
 This command lists the contents of a repository or an archive.
@@ -61,7 +61,10 @@ specify format for file listing
 (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
 .TP
 .B \-\-json
-format output as JSON. The form of \-\-format is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
+Only valid for listing repository contents. Format output as JSON. The form of \-\-format is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
+.TP
+.B \-\-json\-lines
+Only valid for listing archive contents. Format output as JSON Lines. The form of \-\-format is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
 .UNINDENT
 .SS filters
 .INDENT 0.0
diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1
index 89a3ee241..298967af1 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-04-29" "" "borg backup tool"
+.TH BORG-MOUNT 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg mount <options> REPOSITORY_OR_ARCHIVE MOUNTPOINT
+borg [common options] mount <options> REPOSITORY_OR_ARCHIVE MOUNTPOINT
 .SH DESCRIPTION
 .sp
 This command mounts an archive as a FUSE filesystem. This can be useful for
diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1
index e2d12055e..0c329d0d7 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-04-29" "" "borg backup tool"
+.TH BORG-PATTERNS 1 "2017-05-17" "" "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 c906f8dc2..72ae10462 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-04-29" "" "borg backup tool"
+.TH BORG-PLACEHOLDERS 1 "2017-05-17" "" "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 550312281..dcb817a6e 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-04-29" "" "borg backup tool"
+.TH BORG-PRUNE 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg prune <options> REPOSITORY
+borg [common options] prune <options> REPOSITORY
 .SH DESCRIPTION
 .sp
 The prune command prunes a repository by deleting all archives not matching
@@ -91,9 +91,6 @@ do not change repository
 .B \-\-force
 force pruning of corrupted archives
 .TP
-.B \-p\fP,\fB  \-\-progress
-show progress display while deleting archives
-.TP
 .B \-s\fP,\fB  \-\-stats
 print statistics for the deleted archive
 .TP
diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1
index 8f2bf554e..0e22a3207 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-04-29" "" "borg backup tool"
+.TH BORG-RECREATE 1 "2017-05-17" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg recreate <options> REPOSITORY_OR_ARCHIVE PATH
+borg [common options] recreate <options> REPOSITORY_OR_ARCHIVE PATH