python setup.py build_man

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-08-27" "" "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.

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-08-27" "" "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 "2017-06-18" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2017-08-27" "" "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.

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-08-27" "" "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 [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

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-08-27" "" "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

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-08-27" "" "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
@@ -78,7 +78,7 @@ set umask to M (local and remote, default: 0077)
 .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

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-08-27" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .

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-08-27" "" "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,14 @@ 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. Normally, detecting file modifications
+will take inode information into consideration. 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. The
+\fB\-\-ignore\-inode\fP flag can be used to prevent this and improve performance.
+This flag will reduce reliability of change detection however, with files
+considered unmodified as long as their size and modification time are unchanged.
 .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
@@ -94,13 +98,13 @@ 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 \fB\-\-no\-files\-cache\fP\&.
 .UNINDENT
 .SS Exclusion options
 .INDENT 0.0
@@ -111,20 +115,20 @@ 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
 .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
-.BI \-\-patterns\-from \ PATTERNFILE
-experimental: read include/exclude patterns from PATTERNFILE, one per line
+if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive
 .UNINDENT
 .SS Filesystem options
 .INDENT 0.0
@@ -154,7 +158,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)
@@ -250,6 +254,9 @@ all of its contents will be omitted from the backup.  If, however, you wish to
 only include the objects specified by \fB\-\-exclude\-if\-present\fP in your backup,
 and not include any other contents of the containing folder, this can be enabled
 through using the \fB\-\-keep\-exclude\-tags\fP option.
+.sp
+Borg respects the nodump flag. Files flagged nodump will be marked as excluded (x)
+in \fB\-\-list\fP output.
 .SS Item flags
 .sp
 \fB\-\-list\fP outputs a list of all files, directories and other

docs/man/borg-delete.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DELETE 1 "2017-06-18" "" "borg backup tool"
+.TH BORG-DELETE 1 "2017-08-27" "" "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 [common options] delete <options> TARGET
+borg [common options] delete [options] [TARGET]
 .SH DESCRIPTION
 .sp
 This command deletes an archive from the repository or the complete repository.
@@ -53,25 +53,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

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-08-27" "" "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,20 +87,20 @@ 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
 .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
-.BI \-\-patterns\-from \ PATTERNFILE
-experimental: read include/exclude patterns from PATTERNFILE, one per line
+if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0

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-08-27" "" "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