build_man (master)

also: git add borgfs.1

32 files changed, 732 insertions, 225 deletions

diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1
index c763aae31..06c1b21a0 100644
--- a/docs/man/borg-benchmark-crud.1
+++ b/docs/man/borg-benchmark-crud.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK-CRUD 1 "2017-06-18" "" "borg backup tool"
+.TH BORG-BENCHMARK-CRUD 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg [common options] benchmark crud <options> REPO PATH
+borg [common options] benchmark crud [options] REPO PATH
 .SH DESCRIPTION
 .sp
 This command benchmarks borg CRUD (create, read, update, delete) operations.
diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1
index 79e356ac1..c6d44204f 100644
--- a/docs/man/borg-benchmark.1
+++ b/docs/man/borg-benchmark.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK 1 "2017-06-18" "" "borg backup tool"
+.TH BORG-BENCHMARK 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-benchmark \- benchmark command
 .
diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1
index 7b4291cd5..a6c93a2ca 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-06-18" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2017-11-25" "" "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 [common options] 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 d5b3edbfa..c56f773a8 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-06-18" "" "borg backup tool"
+.TH BORG-CHANGE-PASSPHRASE 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-change-passphrase \- Change repository key file passphrase
 .
@@ -32,11 +32,16 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg [common options] change\-passphrase <options> REPOSITORY
+borg [common options] change\-passphrase [options] [REPOSITORY]
 .SH DESCRIPTION
 .sp
 The key files used for repository encryption are optionally passphrase
 protected. This command can be used to change this passphrase.
+.sp
+Please note that this command only changes the passphrase, but not any
+secret protected by it (like e.g. encryption/MAC keys or chunker seed).
+Thus, changing the passphrase after passphrase and borg key got compromised
+does not protect future (nor past) backups to the same repository.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1
index cf2996a2a..5a8660a27 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-06-18" "" "borg backup tool"
+.TH BORG-CHECK 1 "2017-11-25" "" "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 [common options] 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.
@@ -121,16 +121,16 @@ attempt to repair any inconsistencies found
 .B \-\-save\-space
 work slower, but using less space
 .UNINDENT
-.SS filters
+.SS Archive filters
 .INDENT 0.0
 .TP
-.B \-P\fP,\fB  \-\-prefix
+.BI \-P \ PREFIX\fP,\fB \ \-\-prefix \ PREFIX
 only consider archive names starting with this prefix.
 .TP
-.B \-a\fP,\fB  \-\-glob\-archives
+.BI \-a \ GLOB\fP,\fB \ \-\-glob\-archives \ GLOB
 only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
 .TP
-.B \-\-sort\-by
+.BI \-\-sort\-by \ KEYS
 Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
 .TP
 .BI \-\-first \ N
diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1
index f48ccb6c1..229901608 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-06-18" "" "borg backup tool"
+.TH BORG-COMMON 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .
@@ -60,8 +60,8 @@ show progress information
 .B \-\-log\-json
 Output one JSON object per log line instead of formatted text.
 .TP
-.BI \-\-lock\-wait \ N
-wait for the lock, but max. N seconds (default: 1).
+.BI \-\-lock\-wait \ SECONDS
+wait at most SECONDS for acquiring a repository/cache lock (default: 1).
 .TP
 .B \-\-show\-version
 show/log the borg version
@@ -69,16 +69,13 @@ show/log the borg version
 .B \-\-show\-rc
 show/log the return code (rc)
 .TP
-.B \-\-no\-files\-cache
-do not load/update the file metadata cache used to detect unchanged files
-.TP
 .BI \-\-umask \ M
 set umask to M (local and remote, default: 0077)
 .TP
 .BI \-\-remote\-path \ PATH
 use PATH as borg executable on the remote (default: "borg")
 .TP
-.BI \-\-remote\-ratelimit \ rate
+.BI \-\-remote\-ratelimit \ RATE
 set remote network upload rate limit in kiByte/s (default: 0=unlimited)
 .TP
 .B \-\-consider\-part\-files
diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1
index 3347a6582..f4ee1bf8e 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-06-18" "" "borg backup tool"
+.TH BORG-COMPRESSION 1 "2017-11-25" "" "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 ec8d7b525..71b766aed 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-06-18" "" "borg backup tool"
+.TH BORG-CREATE 1 "2017-11-25" "" "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 [common options] 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
@@ -53,10 +53,51 @@ checkpoints and treated in special ways.
 In the archive name, you may use the following placeholders:
 {now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.
 .sp
-To speed up pulling backups over sshfs and similar network file systems which do
-not provide correct inode information the \fB\-\-ignore\-inode\fP flag can be used. This
-potentially decreases reliability of change detection, while avoiding always reading
-all files on these file systems.
+Backup speed is increased by not reprocessing files that are already part of
+existing archives and weren\(aqt modified. The detection of unmodified files is
+done by comparing multiple file metadata values with previous values kept in
+the files cache.
+.sp
+This comparison can operate in different modes as given by \fB\-\-files\-cache\fP:
+.INDENT 0.0
+.IP \(bu 2
+ctime,size,inode (default)
+.IP \(bu 2
+mtime,size,inode (default behaviour of borg versions older than 1.1.0rc4)
+.IP \(bu 2
+ctime,size (ignore the inode number)
+.IP \(bu 2
+mtime,size (ignore the inode number)
+.IP \(bu 2
+rechunk,ctime (all files are considered modified \- rechunk, cache ctime)
+.IP \(bu 2
+rechunk,mtime (all files are considered modified \- rechunk, cache mtime)
+.IP \(bu 2
+disabled (disable the files cache, all files considered modified \- rechunk)
+.UNINDENT
+.sp
+inode number: better safety, but often unstable on network filesystems
+.sp
+Normally, detecting file modifications will take inode information into
+consideration to improve the reliability of file change detection.
+This is problematic for files located on sshfs and similar network file
+systems which do not provide stable inode numbers, such files will always
+be considered modified. You can use modes without \fIinode\fP in this case to
+improve performance, but reliability of change detection might be reduced.
+.sp
+ctime vs. mtime: safety vs. speed
+.INDENT 0.0
+.IP \(bu 2
+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).
+.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
+it had before a content change happened. This can be used maliciously as well as
+well\-meant, but in both cases mtime based cache modes can be problematic.
+.UNINDENT
 .sp
 The mount points of filesystems or filesystem snapshots should be the same for every
 creation of a new archive to ensure fast operation. This is because the file cache that
@@ -67,6 +108,12 @@ The \fB\-\-progress\fP option shows (from left to right) Original, Compressed an
 (O, C and D, respectively), then the Number of files (N) processed so far, followed by
 the currently processed path.
 .sp
+When using \fB\-\-stats\fP, you will get some statistics about how much data was
+added \- the "This Archive" deduplicated size there is most interesting as that is
+how much your repository will grow. Please note that the "All archives" stats refer to
+the state after creation. Also, the \fB\-\-stats\fP and \fB\-\-dry\-run\fP options are mutually
+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.
 See the output of the "borg help placeholders" command for more help on placeholders.
 .SH OPTIONS
@@ -94,13 +141,16 @@ print statistics for the created archive
 output verbose list of items (files, dirs, ...)
 .TP
 .BI \-\-filter \ STATUSCHARS
-only display items with the given status characters
+only display items with the given status characters (see description)
 .TP
 .B \-\-json
-output stats as JSON (implies \-\-stats)
+output stats as JSON. Implies \fB\-\-stats\fP\&.
 .TP
 .B \-\-no\-cache\-sync
-experimental: do not synchronize the cache. Implies \-\-no\-files\-cache.
+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
 .UNINDENT
 .SS Exclusion options
 .INDENT 0.0
@@ -111,6 +161,12 @@ exclude paths matching PATTERN
 .BI \-\-exclude\-from \ EXCLUDEFILE
 read exclude patterns from EXCLUDEFILE, one per line
 .TP
+.BI \-\-pattern \ PATTERN
+experimental: include/exclude paths matching PATTERN
+.TP
+.BI \-\-patterns\-from \ PATTERNFILE
+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)
 .TP
@@ -118,13 +174,10 @@ exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosauru
 exclude directories that are tagged by containing a filesystem object with the given NAME
 .TP
 .B \-\-keep\-exclude\-tags\fP,\fB  \-\-keep\-tag\-files
-if tag objects are specified with \-\-exclude\-if\-present, don\(aqt omit the tag objects themselves from the backup archive
-.TP
-.BI \-\-pattern \ PATTERN
-experimental: include/exclude paths matching PATTERN
+if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive
 .TP
-.BI \-\-patterns\-from \ PATTERNFILE
-experimental: read include/exclude patterns from PATTERNFILE, one per line
+.B \-\-exclude\-nodump
+exclude files flagged NODUMP
 .UNINDENT
 .SS Filesystem options
 .INDENT 0.0
@@ -141,9 +194,18 @@ do not store atime into archive
 .B \-\-noctime
 do not store ctime into archive
 .TP
+.B \-\-nobirthtime
+do not store birthtime (creation date) into archive
+.TP
+.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
 .B \-\-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.
 .UNINDENT
@@ -154,7 +216,7 @@ open and read block and char device files as well as FIFOs as if they were regul
 add a comment text to the archive
 .TP
 .BI \-\-timestamp \ TIMESTAMP
-manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss format). alternatively, give a reference file/directory.
+manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss format). Alternatively, give a reference file/directory.
 .TP
 .BI \-c \ SECONDS\fP,\fB \ \-\-checkpoint\-interval \ SECONDS
 write checkpoint every SECONDS seconds (Default: 1800)
@@ -208,18 +270,21 @@ $ borg create \-\-chunker\-params 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 \-
 
-# No compression (default)
-$ borg create /path/to/repo::arch ~
+# No compression (none)
+$ borg create \-\-compression none /path/to/repo::arch ~
 
-# Super fast, low compression
-$ borg create \-\-compression lz4 /path/to/repo::arch ~
+# Super fast, low compression (lz4, default)
+$ borg create /path/to/repo::arch ~
 
-# Less fast, higher compression (N = 0..9)
+# Less fast, higher compression (zlib, N = 0..9)
 $ borg create \-\-compression zlib,N /path/to/repo::arch ~
 
-# Even slower, even higher compression (N = 0..9)
+# Even slower, even higher compression (lzma, N = 0..9)
 $ borg create \-\-compression lzma,N /path/to/repo::arch ~
 
+# Only compress compressible data with lzma,N (N = 0..9)
+$ borg create \-\-compression auto,lzma,N /path/to/repo::arch ~
+
 # Use short hostname, user name and current time in archive name
 $ borg create /path/to/repo::{hostname}\-{user}\-{now} ~
 # Similar, use the same datetime format as borg 1.1 will have as default
diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1
index 2e8891532..2b0e16fc7 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-06-18" "" "borg backup tool"
+.TH BORG-DELETE 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .
@@ -32,12 +32,17 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg [common options] delete <options> TARGET
+borg [common options] delete [options] [TARGET] [ARCHIVE...]
 .SH DESCRIPTION
 .sp
 This command deletes an archive from the repository or the complete repository.
 Disk space is reclaimed accordingly. If you delete the complete repository, the
 local cache for it (if any) is also deleted.
+.sp
+When using \fB\-\-stats\fP, you will get some statistics about how much data was
+deleted \- the "Deleted data" deduplicated size there is most interesting as
+that is how much your repository will shrink.
+Please note that the "All archives" stats refer to the state after deletion.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -46,6 +51,9 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .TP
 .B TARGET
 archive or repository to delete
+.TP
+.B ARCHIVE
+archives to delete
 .UNINDENT
 .SS optional arguments
 .INDENT 0.0
@@ -53,25 +61,25 @@ archive or repository to delete
 .B \-s\fP,\fB  \-\-stats
 print statistics for the deleted archive
 .TP
-.B \-c\fP,\fB  \-\-cache\-only
+.B \-\-cache\-only
 delete only the local cache for the given repository
 .TP
 .B \-\-force
-force deletion of corrupted archives, use \-\-force \-\-force in case \-\-force does not work.
+force deletion of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work.
 .TP
 .B \-\-save\-space
 work slower, but using less space
 .UNINDENT
-.SS filters
+.SS Archive filters
 .INDENT 0.0
 .TP
-.B \-P\fP,\fB  \-\-prefix
+.BI \-P \ PREFIX\fP,\fB \ \-\-prefix \ PREFIX
 only consider archive names starting with this prefix.
 .TP
-.B \-a\fP,\fB  \-\-glob\-archives
+.BI \-a \ GLOB\fP,\fB \ \-\-glob\-archives \ GLOB
 only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
 .TP
-.B \-\-sort\-by
+.BI \-\-sort\-by \ KEYS
 Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
 .TP
 .BI \-\-first \ N
diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1
index ad030a672..77697f190 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-06-18" "" "borg backup tool"
+.TH BORG-DIFF 1 "2017-11-25" "" "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 [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.
@@ -87,15 +87,6 @@ exclude paths matching PATTERN
 .BI \-\-exclude\-from \ EXCLUDEFILE
 read exclude patterns from EXCLUDEFILE, one per line
 .TP
-.B \-\-exclude\-caches
-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
-.TP
-.B \-\-keep\-exclude\-tags\fP,\fB  \-\-keep\-tag\-files
-if tag objects are specified with \-\-exclude\-if\-present, don\(aqt omit the tag objects themselves from the backup archive
-.TP
 .BI \-\-pattern \ PATTERN
 experimental: include/exclude paths matching PATTERN
 .TP
diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1
index 515b4d849..770d2bafe 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-06-18" "" "borg backup tool"
+.TH BORG-EXPORT-TAR 1 "2017-11-25" "" "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 [common options] 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.
@@ -95,6 +95,9 @@ filter program to pipe data through
 .TP
 .B \-\-list
 output verbose list of items (files, dirs, ...)
+.UNINDENT
+.SS Exclusion options
+.INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN
 exclude paths matching PATTERN
@@ -109,7 +112,7 @@ experimental: include/exclude paths matching PATTERN
 experimental: read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .BI \-\-strip\-components \ NUMBER
-Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
+Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0
@@ -129,6 +132,9 @@ $ borg export\-tar testrepo::linux \-\-tar\-filter="gzip \-9" Monday.tar.gz
 # export a gzipped 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
+
+# remote extraction via "tarpipe"
+$ borg export\-tar /path/to/repo::Monday \- | ssh somewhere "cd extracted; tar x"
 .ft P
 .fi
 .UNINDENT
diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1
index 13a71ab72..b11d737b3 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-06-18" "" "borg backup tool"
+.TH BORG-EXTRACT 1 "2017-11-25" "" "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 [common options] 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
@@ -48,6 +48,14 @@ decrypting, decompressing.
 .sp
 \fB\-\-progress\fP can be slower than no progress display, since it makes one additional
 pass over the archive metadata.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Currently, extract always writes into the current working directory ("."),
+so make sure you \fBcd\fP to the right place before calling \fBborg extract\fP\&.
+.UNINDENT
+.UNINDENT
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -69,6 +77,21 @@ output verbose list of items (files, dirs, ...)
 .B \-n\fP,\fB  \-\-dry\-run
 do not actually change any files
 .TP
+.B \-\-numeric\-owner
+only obey numeric user and group identifiers
+.TP
+.B \-\-nobsdflags
+do not extract/set bsdflags (e.g. NODUMP, IMMUTABLE)
+.TP
+.B \-\-stdout
+write all extracted data to stdout
+.TP
+.B \-\-sparse
+create holes in output sparse file from all\-zero chunks
+.UNINDENT
+.SS Exclusion options
+.INDENT 0.0
+.TP
 .BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN
 exclude paths matching PATTERN
 .TP
@@ -81,17 +104,8 @@ experimental: include/exclude paths matching PATTERN
 .BI \-\-patterns\-from \ PATTERNFILE
 experimental: read include/exclude patterns from PATTERNFILE, one per line
 .TP
-.B \-\-numeric\-owner
-only obey numeric user and group identifiers
-.TP
 .BI \-\-strip\-components \ NUMBER
-Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
-.TP
-.B \-\-stdout
-write all extracted data to stdout
-.TP
-.B \-\-sparse
-create holes in output sparse file from all\-zero chunks
+Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0
@@ -120,14 +134,6 @@ $ borg extract \-\-stdout /path/to/repo::my\-sdx | dd of=/dev/sdx bs=10M
 .fi
 .UNINDENT
 .UNINDENT
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-Currently, extract always writes into the current working directory ("."),
-so make sure you \fBcd\fP to the right place before calling \fBborg extract\fP\&.
-.UNINDENT
-.UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-mount(1)\fP
diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1
index 338d3ca60..726fed826 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-06-18" "" "borg backup tool"
+.TH BORG-INFO 1 "2017-11-25" "" "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 [common options] 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.
@@ -40,14 +40,16 @@ This command displays detailed information about the specified archive or reposi
 Please note that the deduplicated sizes of the individual archives do not add
 up to the deduplicated size of the repository ("all archives"), because the two
 are meaning different things:
-.INDENT 0.0
-.TP
-.B This archive / deduplicated size = amount of data stored ONLY for this archive
+.sp
+This archive / deduplicated size = amount of data stored ONLY for this archive
 = unique chunks of this archive.
-.TP
-.B All archives / deduplicated size = amount of data stored in the repo
+All archives / deduplicated size = amount of data stored in the repo
 = all chunks in the repository.
-.UNINDENT
+.sp
+Borg archives can only contain a limited amount of file metadata.
+The size of an archive relative to this limit depends on a number of factors,
+mainly the number of files, the lengths of paths and other metadata stored for files.
+This is shown as \fIutilization of maximum supported archive size\fP\&.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -63,16 +65,16 @@ archive or repository to display information about
 .B \-\-json
 format output as JSON
 .UNINDENT
-.SS filters
+.SS Archive filters
 .INDENT 0.0
 .TP
-.B \-P\fP,\fB  \-\-prefix
+.BI \-P \ PREFIX\fP,\fB \ \-\-prefix \ PREFIX
 only consider archive names starting with this prefix.
 .TP
-.B \-a\fP,\fB  \-\-glob\-archives
+.BI \-a \ GLOB\fP,\fB \ \-\-glob\-archives \ GLOB
 only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
 .TP
-.B \-\-sort\-by
+.BI \-\-sort\-by \ KEYS
 Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
 .TP
 .BI \-\-first \ N
@@ -87,22 +89,58 @@ consider last N archives after other filters were applied
 .sp
 .nf
 .ft C
-$ borg info /path/to/repo::root\-2016\-02\-15
-Name: root\-2016\-02\-15
-Fingerprint: 57c827621f21b000a8d363c1e163cc55983822b3afff3a96df595077a660be50
+$ borg info /path/to/repo::2017\-06\-29T11:00\-srv
+Archive name: 2017\-06\-29T11:00\-srv
+Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
+Comment:
 Hostname: myhostname
 Username: root
-Time (start): Mon, 2016\-02\-15 19:36:29
-Time (end):   Mon, 2016\-02\-15 19:39:26
-Command line: /usr/local/bin/borg create \-\-list \-C zlib,6 /path/to/repo::root\-2016\-02\-15 / \-\-one\-file\-system
-Number of files: 38100
+Time (start): Thu, 2017\-06\-29 11:03:07
+Time (end): Thu, 2017\-06\-29 11:03:13
+Duration: 5.66 seconds
+Number of files: 17037
+Command line: /usr/sbin/borg create /path/to/repo::2017\-06\-29T11:00\-srv /srv
+Utilization of max. archive size: 0%
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+                       Original size      Compressed size    Deduplicated size
+This archive:               12.53 GB             12.49 GB              1.62 kB
+All archives:              121.82 TB            112.41 TB            215.42 GB
+
+                       Unique chunks         Total chunks
+Chunk index:                 1015213            626934122
+
+$ borg info /path/to/repo \-\-last 1
+Archive name: 2017\-06\-29T11:00\-srv
+Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
+Comment:
+Hostname: myhostname
+Username: root
+Time (