Merge pull request #2127 from enkore/f/manpages

Man pages

docs/man/borg-break-lock.1

@@ -0,0 +1,56 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-BREAK-LOCK 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
+.
+.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 break\-lock <options> REPOSITORY
+.SH DESCRIPTION
+.sp
+This command breaks the repository and cache locks.
+Please use carefully and only while no borg process (on any machine) is
+trying to access the Cache or the Repository.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B REPOSITORY
+repository for which to break the locks
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-change-passphrase.1

@@ -0,0 +1,52 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-CHANGE-PASSPHRASE 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-change-passphrase \- Change repository key file passphrase
+.
+.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 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.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.sp
+REPOSITORY
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-check.1

@@ -0,0 +1,148 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-CHECK 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-check \- Check repository consistency
+.
+.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 check <options> REPOSITORY_OR_ARCHIVE
+.SH DESCRIPTION
+.sp
+The check command verifies the consistency of a repository and the corresponding archives.
+.sp
+First, the underlying repository data files are checked:
+.INDENT 0.0
+.IP \(bu 2
+For all segments the segment magic (header) is checked
+.IP \(bu 2
+For all objects stored in the segments, all metadata (e.g. crc and size) and
+all data is read. The read data is checked by size and CRC. Bit rot and other
+types of accidental damage can be detected this way.
+.IP \(bu 2
+If we are in repair mode and a integrity error is detected for a segment,
+we try to recover as many objects from the segment as possible.
+.IP \(bu 2
+In repair mode, it makes sure that the index is consistent with the data
+stored in the segments.
+.IP \(bu 2
+If you use a remote repo server via ssh:, the repo check is executed on the
+repo server without causing significant network traffic.
+.IP \(bu 2
+The repository check can be skipped using the \-\-archives\-only option.
+.UNINDENT
+.sp
+Second, the consistency and correctness of the archive metadata is verified:
+.INDENT 0.0
+.IP \(bu 2
+Is the repo manifest present? If not, it is rebuilt from archive metadata
+chunks (this requires reading and decrypting of all metadata and data).
+.IP \(bu 2
+Check if archive metadata chunk is present. if not, remove archive from
+manifest.
+.IP \(bu 2
+For all files (items) in the archive, for all chunks referenced by these
+files, check if chunk is present.
+If a chunk is not present and we are in repair mode, replace it with a same\-size
+replacement chunk of zeros.
+If a previously lost chunk reappears (e.g. via a later backup) and we are in
+repair mode, the all\-zero replacement chunk will be replaced by the correct chunk.
+This requires reading of archive and file metadata, but not data.
+.IP \(bu 2
+If we are in repair mode and we checked all the archives: delete orphaned
+chunks from the repo.
+.IP \(bu 2
+if you use a remote repo server via ssh:, the archive check is executed on
+the client machine (because if encryption is enabled, the checks will require
+decryption and this is always done client\-side, because key access will be
+required).
+.IP \(bu 2
+The archive checks can be time consuming, they can be skipped using the
+\-\-repository\-only option.
+.UNINDENT
+.sp
+The \-\-verify\-data option will perform a full integrity verification (as opposed to
+checking the CRC32 of the segment) of data, which means reading the data from the
+repository, decrypting and decompressing it. This is a cryptographic verification,
+which will detect (accidental) corruption. For encrypted repositories it is
+tamper\-resistant as well, unless the attacker has access to the keys.
+.sp
+It is also very slow.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B REPOSITORY_OR_ARCHIVE
+repository or archive to check consistency of
+.UNINDENT
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B \-\-repository\-only
+only perform repository checks
+.TP
+.B \-\-archives\-only
+only perform archives checks
+.TP
+.B \-\-verify\-data
+perform cryptographic archive data integrity verification (conflicts with \-\-repository\-only)
+.TP
+.B \-\-repair
+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
+.TP
+.B \-P\fP,\fB  \-\-prefix
+only consider archive names starting with this prefix
+.TP
+.B \-\-sort\-by
+Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+.TP
+.BI \-\-first \ N
+consider first N archives after other filters were applied
+.TP
+.BI \-\-last \ N
+consider last N archives after other filters were applied
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-common.1

@@ -0,0 +1,87 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-COMMON 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-common \- Common options of Borg commands
+.
+.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
+.INDENT 0.0
+.TP
+.B \-h\fP,\fB  \-\-help
+show this help message and exit
+.TP
+.B \-\-critical
+work on log level CRITICAL
+.TP
+.B \-\-error
+work on log level ERROR
+.TP
+.B \-\-warning
+work on log level WARNING (default)
+.TP
+.B \-\-info\fP,\fB  \-v\fP,\fB  \-\-verbose
+work on log level INFO
+.TP
+.B \-\-debug
+enable debug output, work on log level DEBUG
+.TP
+.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
+.BI \-\-lock\-wait \ N
+wait for the lock, but max. N seconds (default: 1).
+.TP
+.B \-\-show\-version
+show/log the borg version
+.TP
+.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
+set remote path to executable (default: "borg")
+.TP
+.BI \-\-remote\-ratelimit \ rate
+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)
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-compression.1

@@ -0,0 +1,156 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-COMPRESSION 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-compression \- Details regarding compression
+.
+.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 DESCRIPTION
+.sp
+Compression is off by default, if you want some, you have to specify what you want.
+.sp
+Valid compression specifiers are:
+.sp
+none
+.INDENT 0.0
+.INDENT 3.5
+Do not compress. (default)
+.UNINDENT
+.UNINDENT
+.sp
+lz4
+.INDENT 0.0
+.INDENT 3.5
+Use lz4 compression. High speed, low compression.
+.UNINDENT
+.UNINDENT
+.sp
+zlib[,L]
+.INDENT 0.0
+.INDENT 3.5
+Use zlib ("gz") compression. Medium speed, medium compression.
+If you do not explicitely give the compression level L (ranging from 0
+to 9), it will use level 6.
+Giving level 0 (means "no compression", but still has zlib protocol
+overhead) is usually pointless, you better use "none" compression.
+.UNINDENT
+.UNINDENT
+.sp
+lzma[,L]
+.INDENT 0.0
+.INDENT 3.5
+Use lzma ("xz") compression. Low speed, high compression.
+If you do not explicitely give the compression level L (ranging from 0
+to 9), it will use level 6.
+Giving levels above 6 is pointless and counterproductive because it does
+not compress better due to the buffer size used by borg \- but it wastes
+lots of CPU cycles and RAM.
+.UNINDENT
+.UNINDENT
+.sp
+auto,C[,L]
+.INDENT 0.0
+.INDENT 3.5
+Use a built\-in heuristic to decide per chunk whether to compress or not.
+The heuristic tries with lz4 whether the data is compressible.
+For incompressible data, it will not use compression (uses "none").
+For compressible data, it uses the given C[,L] compression \- with C[,L]
+being any valid compression specifier.
+.UNINDENT
+.UNINDENT
+.sp
+The decision about which compression to use is done by borg like this:
+.INDENT 0.0
+.IP 1. 3
+find a compression specifier (per file):
+match the path/filename against all patterns in all \-\-compression\-from
+files (if any). If a pattern matches, use the compression spec given for
+that pattern. If no pattern matches (and also if you do not give any
+\-\-compression\-from option), default to the compression spec given by
+\-\-compression. See docs/misc/compression.conf for an example config.
+.IP 2. 3
+if the found compression spec is not "auto", the decision is taken:
+use the found compression spec.
+.IP 3. 3
+if the found compression spec is "auto", test compressibility of each
+chunk using lz4.
+If it is compressible, use the C,[L] compression spec given within the
+"auto" specifier. If it is not compressible, use no compression.
+.UNINDENT
+.sp
+Examples:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+borg create \-\-compression lz4 REPO::ARCHIVE data
+borg create \-\-compression zlib REPO::ARCHIVE data
+borg create \-\-compression zlib,1 REPO::ARCHIVE data
+borg create \-\-compression auto,lzma,6 REPO::ARCHIVE data
+borg create \-\-compression\-from compression.conf \-\-compression auto,lzma ...
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+compression.conf has entries like:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# example config file for \-\-compression\-from option
+#
+# Format of non\-comment / non\-empty lines:
+# <compression\-spec>:<path/filename pattern>
+# compression\-spec is same format as for \-\-compression option
+# path/filename pattern is same format as for \-\-exclude option
+none:*.gz
+none:*.zip
+none:*.mp3
+none:*.ogg
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+General remarks:
+.sp
+It is no problem to mix different compression methods in one repo,
+deduplication is done on the source data chunks (not on the compressed
+or encrypted data).
+.sp
+If some specific chunk was once compressed and stored into the repo, creating
+another backup that also uses this chunk will not change the stored chunk.
+So if you use different compression specs for the backups, whichever stores a
+chunk first determines its compression. See also borg recreate.
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-create.1

@@ -0,0 +1,233 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-CREATE 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-create \- Create new archive
+.
+.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 create <options> ARCHIVE PATH
+.SH DESCRIPTION
+.sp
+This command creates a backup archive containing all files found while recursively
+traversing all paths specified. When giving \(aq\-\(aq as path, borg will read data
+from standard input and create a file \(aqstdin\(aq in the created archive from that
+data.
+.sp
+The archive will consume almost no disk space for files or parts of files that
+have already been stored in other archives.
+.sp
+The archive name needs to be unique. It must not end in \(aq.checkpoint\(aq or
+\(aq.checkpoint.N\(aq (with N being a number), because these names are used for
+checkpoints and treated in special ways.
+.sp
+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 \-\-ignore\-inode flag can be used. This
+potentially decreases reliability of change detection, while avoiding always reading
+all files on these file systems.
+.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
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B ARCHIVE
+name of archive to create (must be also a valid directory name)
+.TP
+.B PATH
+paths to archive
+.UNINDENT
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B \-n\fP,\fB  \-\-dry\-run
+do not create a backup archive
+.TP
+.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
+.BI \-\-filter \ STATUSCHARS
+only display items with the given status characters
+.UNINDENT
+.SS Exclusion options
+.INDENT 0.0
+.TP
+.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN
+exclude paths matching PATTERN
+.TP
+.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
+keep tag objects (i.e.: arguments to \-\-exclude\-if\-present) in otherwise                                          excluded caches/directories
+.UNINDENT
+.SS Filesystem options
+.INDENT 0.0
+.TP
+.B \-x\fP,\fB  \-\-one\-file\-system
+stay in same file system, do not cross mount points
+.TP
+.B \-\-numeric\-owner
+only store numeric user and group identifiers
+.TP
+.B \-\-noatime
+do not store atime into archive
+.TP
+.B \-\-noctime
+do not store ctime into archive
+.TP
+.B \-\-ignore\-inode
+ignore inode data in the file metadata cache used to detect unchanged files.
+.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
+.SS Archive options
+.INDENT 0.0
+.TP
+.BI \-\-comment \ COMMENT
+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.
+.TP
+.BI \-c \ SECONDS\fP,\fB \ \-\-checkpoint\-interval \ SECONDS
+write checkpoint every SECONDS seconds (Default: 1800)
+.TP
+.BI \-\-chunker\-params \ PARAMS
+specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
+.TP
+.BI \-C \ COMPRESSION\fP,\fB \ \-\-compression \ COMPRESSION
+select compression algorithm, see the output of the "borg help compression" command for details.
+.TP
+.BI \-\-compression\-from \ COMPRESSIONCONFIG
+read compression patterns from COMPRESSIONCONFIG, see the output of the "borg help compression" command for details.
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Backup ~/Documents into an archive named "my\-documents"
+$ borg create /path/to/repo::my\-documents ~/Documents
+
+# same, but list all files as we process them
+$ borg create \-\-list /path/to/repo::my\-documents ~/Documents
+
+# Backup ~/Documents and ~/src but exclude pyc files
+$ borg create /path/to/repo::my\-files \e
+    ~/Documents                       \e
+    ~/src                             \e
+    \-\-exclude \(aq*.pyc\(aq
+
+# Backup home directories excluding image thumbnails (i.e. only
+# /home/*/.thumbnails is excluded, not /home/*/*/.thumbnails)
+$ borg create /path/to/repo::my\-files /home \e
+    \-\-exclude \(aqre:^/home/[^/]+/\e.thumbnails/\(aq
+
+# Do the same using a shell\-style pattern
+$ borg create /path/to/repo::my\-files /home \e
+    \-\-exclude \(aqsh:/home/*/.thumbnails\(aq
+
+# Backup the root filesystem into an archive named "root\-YYYY\-MM\-DD"
+# use zlib compression (good, but slow) \- default is no compression
+$ borg create \-C zlib,6 /path/to/repo::root\-{now:%Y\-%m\-%d} / \-\-one\-file\-system
+
+# Backup a remote host locally ("pull" style) using sshfs
+$ mkdir sshfs\-mount
+$ sshfs root@example.com:/ sshfs\-mount
+$ cd sshfs\-mount
+$ borg create /path/to/repo::example.com\-root\-{now:%Y\-%m\-%d} .
+$ cd ..
+$ fusermount \-u sshfs\-mount
+
+# Make a big effort in fine granular deduplication (big chunk management
+# overhead, needs a lot of RAM and disk space, see formula in internals
+# docs \- same parameters as borg < 1.0 or attic):
+$ 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 ~
+
+# Super fast, low compression
+$ borg create \-\-compression lz4 /path/to/repo::arch ~
+
+# Less fast, higher compression (N = 0..9)
+$ borg create \-\-compression zlib,N /path/to/repo::arch ~
+
+# Even slower, even higher compression (N = 0..9)
+$ borg create \-\-compression 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
+$ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S} ~
+# As above, but add nanoseconds
+$ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f} ~
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Notes
+.INDENT 0.0
+.IP \(bu 2
+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 SEE ALSO
+.sp
+\fIborg\-common(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-check(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-delete.1

@@ -0,0 +1,109 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-DELETE 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-delete \- Delete an existing repository or 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 delete <options> TARGET
+.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.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B TARGET
+archive or repository to delete
+.UNINDENT
+.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
+.B \-c\fP,\fB  \-\-cache\-only
+delete only the local cache for the given repository
+.TP
+.B \-\-force
+force deletion of corrupted archives
+.TP
+.B \-\-save\-space
+work slower, but using less space
+.UNINDENT
+.SS filters
+.INDENT 0.0
+.TP
+.B \-P\fP,\fB  \-\-prefix
+only consider archive names starting with this prefix
+.TP
+.B \-\-sort\-by
+Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+.TP
+.BI \-\-first \ N
+consider first N archives after other filters were applied
+.TP
+.BI \-\-last \ N
+consider last N archives after other filters were applied
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# delete a single backup archive:
+$ borg delete /path/to/repo::Monday
+
+# delete the whole repository and the related local cache:
+$ borg delete /path/to/repo
+You requested to completely DELETE the repository *including* all archives it contains:
+repo                                 Mon, 2016\-02\-15 19:26:54
+root\-2016\-02\-15                      Mon, 2016\-02\-15 19:36:29
+newname                              Mon, 2016\-02\-15 19:50:19
+Type \(aqYES\(aq if you understand this and want to continue: YES
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-diff.1

@@ -0,0 +1,133 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-DIFF 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-diff \- Diff contents of two 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 diff <options> REPO_ARCHIVE1 ARCHIVE2 PATH
+.SH DESCRIPTION
+.sp
+This command finds differences (file contents, user/group/mode) between archives.
+.sp
+A repository location and an archive name must be specified for REPO_ARCHIVE1.
+ARCHIVE2 is just another archive name in same repository (no repository location
+allowed).
+.sp
+For archives created with Borg 1.1 or newer diff automatically detects whether
+the archives are created with the same chunker params. If so, only chunk IDs
+are compared, which is very fast.
+.sp
+For archives prior to Borg 1.1 chunk contents are compared by default.
+If you did not create the archives with different chunker params,
+pass \-\-same\-chunker\-params.
+Note that the chunker params changed from Borg 0.xx to 1.0.
+.sp
+See the output of the "borg help patterns" command for more help on exclude patterns.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B REPO_ARCHIVE1
+repository location and ARCHIVE1 name
+.TP
+.B ARCHIVE2
+ARCHIVE2 name (no repository location allowed)
+.TP
+.B PATH
+paths of items inside the archives to compare; patterns are supported
+.UNINDENT
+.SS optional arguments
+.INDENT 0.0
+.TP
+.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN
+exclude paths matching PATTERN
+.TP
+.BI \-\-exclude\-from \ EXCLUDEFILE
+read exclude patterns from EXCLUDEFILE, one per line
+.TP
+.B \-\-numeric\-owner
+only consider numeric user and group identifiers
+.TP
+.B \-\-same\-chunker\-params
+Override check of chunker parameters.
+.TP
+.B \-\-sort
+Sort the output lines by file path.
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg init \-e=none testrepo
+$ mkdir testdir
+$ cd testdir
+$ echo asdf > file1
+$ dd if=/dev/urandom bs=1M count=4 > file2
+$ touch file3
+$ borg create ../testrepo::archive1 .
+
+$ chmod a+x file1
+$ echo "something" >> file2
+$ borg create ../testrepo::archive2 .
+
+$ rm file3
+$ touch file4
+$ borg create ../testrepo::archive3 .
+
+$ cd ..
+$ borg diff testrepo::archive1 archive2
+[\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1
+   +135 B    \-252 B file2
+
+$ borg diff testrepo::archive2 archive3
+added           0 B file4
+removed         0 B file3
+
+$ borg diff testrepo::archive1 archive3
+[\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1
+   +135 B    \-252 B file2
+added           0 B file4
+removed         0 B file3
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-extract.1

@@ -0,0 +1,131 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-EXTRACT 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-extract \- Extract archive contents
+.
+.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 extract <options> ARCHIVE PATH
+.SH DESCRIPTION
+.sp
+This command extracts the contents of an archive. By default the entire
+archive is extracted but a subset of files and directories can be selected
+by passing a list of \fBPATHs\fP as arguments. The file selection can further
+be restricted by using the \fB\-\-exclude\fP option.
+.sp
+See the output of the "borg help patterns" command for more help on exclude patterns.
+.sp
+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.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B ARCHIVE
+archive to extract
+.TP
+.B PATH
+paths to extract; patterns are supported
+.UNINDENT
+.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
+.B \-n\fP,\fB  \-\-dry\-run
+do not actually change any files
+.TP
+.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN
+exclude paths matching PATTERN
+.TP
+.BI \-\-exclude\-from \ EXCLUDEFILE
+read exclude patterns from EXCLUDEFILE, 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
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Extract entire archive
+$ borg extract /path/to/repo::my\-files
+
+# Extract entire archive and list files while processing
+$ borg extract \-\-list /path/to/repo::my\-files
+
+# Verify whether an archive could be successfully extracted, but do not write files to disk
+$ borg extract \-\-dry\-run /path/to/repo::my\-files
+
+# Extract the "src" directory
+$ borg extract /path/to/repo::my\-files home/USERNAME/src
+
+# Extract the "src" directory but exclude object files
+$ borg extract /path/to/repo::my\-files home/USERNAME/src \-\-exclude \(aq*.o\(aq
+
+# Restore a raw device (must not be active/in use/mounted at that time)
+$ borg extract \-\-stdout /path/to/repo::my\-sdx | dd of=/dev/sdx bs=10M
+.ft P
+.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
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-info.1

@@ -0,0 +1,107 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-INFO 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-info \- Show archive details such as disk space used
+.
+.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 info <options> REPOSITORY_OR_ARCHIVE
+.SH DESCRIPTION
+.sp
+This command displays detailed information about the specified archive or repository.
+.sp
+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
+= unique chunks of this archive.
+.TP
+.B All archives / deduplicated size = amount of data stored in the repo
+= all chunks in the repository.
+.UNINDENT
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B REPOSITORY_OR_ARCHIVE
+archive or repository to display information about
+.UNINDENT
+.SS filters
+.INDENT 0.0
+.TP
+.B \-P\fP,\fB  \-\-prefix
+only consider archive names starting with this prefix
+.TP
+.B \-\-sort\-by
+Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+.TP
+.BI \-\-first \ N
+consider first N archives after other filters were applied
+.TP
+.BI \-\-last \ N
+consider last N archives after other filters were applied
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg info /path/to/repo::root\-2016\-02\-15
+Name: root\-2016\-02\-15
+Fingerprint: 57c827621f21b000a8d363c1e163cc55983822b3afff3a96df595077a660be50
+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
+
+                       Original size      Compressed size    Deduplicated size
+This archive:                1.33 GB            613.25 MB            571.64 MB
+All archives:                1.63 GB            853.66 MB            584.12 MB
+
+                       Unique chunks         Total chunks
+Chunk index:                   36858                48844
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP, \fIborg\-list(1)\fP, \fIborg\-diff(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-init.1

@@ -0,0 +1,157 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-INIT 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-init \- Initialize an empty 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
+.sp
+borg 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.
+.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.
+.sp
+But be careful with the key / the passphrase:
+.sp
+If you want "passphrase\-only" security, use one of the repokey modes. The
+key will be stored inside the repository (in its "config" file). In above
+mentioned attack scenario, the attacker will have the key (but not the
+passphrase).
+.sp
+If you want "passphrase and having\-the\-key" security, use one of the keyfile
+modes. The key will be stored in your home directory (in .config/borg/keys).
+In the attack scenario, the attacker who has just access to your repo won\(aqt
+have the key (and also not the passphrase).
+.sp
+Make a backup copy of the key file (keyfile mode) or repo config file
+(repokey mode) and keep it at a safe place, so you still have the key in
+case it gets corrupted or lost. Also keep the passphrase at a safe place.
+The backup that is encrypted with that key won\(aqt help you with that, of course.
+.sp
+Make sure you use a good passphrase. Not too short, not too simple. The real
+encryption / decryption key is encrypted with / locked by your passphrase.
+If an attacker gets your key, he can\(aqt unlock and use it without knowing the
+passphrase.
+.sp
+Be careful with special or non\-ascii characters in your passphrase:
+.INDENT 0.0
+.IP \(bu 2
+Borg processes the passphrase as unicode (and encodes it as utf\-8),
+so it does not have problems dealing with even the strangest characters.
+.IP \(bu 2
+BUT: that does not necessarily apply to your OS / VM / keyboard configuration.
+.UNINDENT
+.sp
+So better use a long passphrase made from simple ascii chars than one that
+includes non\-ascii stuff or characters that are hard/impossible to enter on
+a different keyboard layout.
+.sp
+You can change your passphrase for existing repos at any time, it won\(aqt affect
+the encryption/decryption key or other secrets.
+.SS Encryption modes
+.sp
+repokey and keyfile 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,
+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.
+.sp
+"authenticated" 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
+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.
+.sp
+On modern ARM CPUs, NEON provides hw acceleration for sha256 making it faster
+than BLAKE2b\-256 there.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B REPOSITORY
+repository to create
+.UNINDENT
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B \-e\fP,\fB  \-\-encryption
+select encryption key mode (default: "None")
+.TP
+.B \-a\fP,\fB  \-\-append\-only
+create an append\-only mode repository
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Local repository, repokey encryption, BLAKE2b (often faster, since Borg 1.1)
+$ borg init \-\-encryption=repokey\-blake2 /path/to/repo
+
+# Local repository (no encryption)
+$ borg init \-\-encryption=none /path/to/repo
+
+# Remote repository (accesses a remote borg via ssh)
+$ borg init \-\-encryption=repokey\-blake2 user@hostname:backup
+
+# Remote repository (store the key your home dir)
+$ borg init \-\-encryption=keyfile user@hostname:backup
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP, \fIborg\-create(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-check(1)\fP, \fIborg\-list(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

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

@@ -0,0 +1,52 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-key-change-passphrase \- Change repository key file passphrase
+.
+.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 key 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.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.sp
+REPOSITORY
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-key-export.1

@@ -0,0 +1,78 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-KEY-EXPORT 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-key-export \- Export the repository key for backup
+.
+.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 key export <options> REPOSITORY PATH
+.SH DESCRIPTION
+.sp
+If repository encryption is used, the repository is inaccessible
+without the key. This command allows to backup this essential key.
+.sp
+There are two backup formats. The normal backup format is suitable for
+digital storage as a file. The \fB\-\-paper\fP backup format is optimized
+for printing and typing in while importing, with per line checks to
+reduce problems with manual input.
+.sp
+For repositories using keyfile encryption the key is saved locally
+on the system that is capable of doing backups. To guard against loss
+of this key, the key needs to be backed up independently of the main
+data backup.
+.sp
+For repositories using the repokey encryption the key is saved in the
+repository in the config file. A backup is thus not strictly needed,
+but guards against the repository becoming inaccessible if the file
+is damaged for some reason.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.sp
+REPOSITORY
+.INDENT 0.0
+.TP
+.B PATH
+where to store the backup
+.UNINDENT
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B \-\-paper
+Create an export suitable for printing and later type\-in
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP, \fIborg\-key\-import(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-key-import.1

@@ -0,0 +1,67 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-KEY-IMPORT 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-key-import \- Import the repository key from backup
+.
+.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 key import <options> REPOSITORY PATH
+.SH DESCRIPTION
+.sp
+This command allows to restore a key previously backed up with the
+export command.
+.sp
+If the \fB\-\-paper\fP option is given, the import will be an interactive
+process in which each line is checked for plausibility before
+proceeding to the next line. For this format PATH must not be given.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.sp
+REPOSITORY
+.INDENT 0.0
+.TP
+.B PATH
+path to the backup
+.UNINDENT
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B \-\-paper
+interactively import from a backup done with \-\-paper
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP, \fIborg\-key\-export(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-key-migrate-to-repokey.1

@@ -0,0 +1,66 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
+.
+.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 key migrate\-to\-repokey <options> REPOSITORY
+.SH DESCRIPTION
+.sp
+This command migrates a repository from passphrase mode (removed in Borg 1.0)
+to repokey mode.
+.sp
+You will be first asked for the repository passphrase (to open it in passphrase
+mode). This is the same passphrase as you used to use for this repo before 1.0.
+.sp
+It will then derive the different secrets from this passphrase.
+.sp
+Then you will be asked for a new passphrase (twice, for safety). This
+passphrase will be used to protect the repokey (which contains these same
+secrets in encrypted form). You may use the same passphrase as you used to
+use, but you may also use a different one.
+.sp
+After migrating to repokey mode, you can change the passphrase at any time.
+But please note: the secrets will always stay the same and they could always
+be derived from your (old) passphrase\-mode passphrase.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.sp
+REPOSITORY
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-list.1

@@ -0,0 +1,245 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-LIST 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-list \- List archive or repository contents
+.
+.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 list <options> REPOSITORY_OR_ARCHIVE PATH
+.SH DESCRIPTION
+.sp
+This command lists the contents of a repository or an archive.
+.sp
+See the "borg help patterns" command for more help on exclude patterns.
+.sp
+The following keys are available for \-\-format:
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+NEWLINE: OS dependent line separator
+.IP \(bu 2
+NL: alias of NEWLINE
+.IP \(bu 2
+NUL: NUL character for creating print0 / xargs \-0 like output, see barchive/bpath
+.IP \(bu 2
+SPACE
+.IP \(bu 2
+TAB
+.IP \(bu 2
+CR
+.IP \(bu 2
+LF
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
+Keys for listing repository archives:
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+archive: archive name interpreted as text (might be missing non\-text characters, see barchive)
+.IP \(bu 2
+barchive: verbatim archive name, can contain any character except NUL
+.IP \(bu 2
+time: time of creation of the archive
+.IP \(bu 2
+id: internal ID of the archive
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
+Keys for listing archive files:
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+type
+.IP \(bu 2
+mode
+.IP \(bu 2
+uid
+.IP \(bu 2
+gid
+.IP \(bu 2
+user
+.IP \(bu 2
+group
+.IP \(bu 2
+path: path interpreted as text (might be missing non\-text characters, see bpath)
+.IP \(bu 2
+bpath: verbatim POSIX path, can contain any character except NUL
+.IP \(bu 2
+source: link target for links (identical to linktarget)
+.IP \(bu 2
+linktarget
+.IP \(bu 2
+flags
+.IP \(bu 2
+size
+.IP \(bu 2
+csize: compressed size
+.IP \(bu 2
+num_chunks: number of chunks in this file
+.IP \(bu 2
+unique_chunks: number of unique chunks in this file
+.IP \(bu 2
+mtime
+.IP \(bu 2
+ctime
+.IP \(bu 2
+atime
+.IP \(bu 2
+isomtime
+.IP \(bu 2
+isoctime
+.IP \(bu 2
+isoatime
+.IP \(bu 2
+blake2b
+.IP \(bu 2
+blake2s
+.IP \(bu 2
+md5
+.IP \(bu 2
+sha1
+.IP \(bu 2
+sha224
+.IP \(bu 2
+sha256
+.IP \(bu 2
+sha384
+.IP \(bu 2
+sha3_224
+.IP \(bu 2
+sha3_256
+.IP \(bu 2
+sha3_384
+.IP \(bu 2
+sha3_512
+.IP \(bu 2
+sha512
+.IP \(bu 2
+shake_128
+.IP \(bu 2
+shake_256
+.IP \(bu 2
+archiveid
+.IP \(bu 2
+archivename
+.IP \(bu 2
+extra: prepends {source} with " \-> " for soft links and " link to " for hard links
+.IP \(bu 2
+health: either "healthy" (file ok) or "broken" (if file has all\-zero replacement chunks)
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B REPOSITORY_OR_ARCHIVE
+repository/archive to list contents of
+.TP
+.B PATH
+paths to list; patterns are supported
+.UNINDENT
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B \-\-short
+only print file/directory names, nothing else
+.TP
+.B \-\-format\fP,\fB  \-\-list\-format
+specify format for file listing
+(default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
+.TP
+.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN
+exclude paths matching PATTERN
+.TP
+.BI \-\-exclude\-from \ EXCLUDEFILE
+read exclude patterns from EXCLUDEFILE, one per line
+.UNINDENT
+.SS filters
+.INDENT 0.0
+.TP
+.B \-P\fP,\fB  \-\-prefix
+only consider archive names starting with this prefix
+.TP
+.B \-\-sort\-by
+Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+.TP
+.BI \-\-first \ N
+consider first N archives after other filters were applied
+.TP
+.BI \-\-last \ N
+consider last N archives after other filters were applied
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg list /path/to/repo
+Monday                               Mon, 2016\-02\-15 19:15:11
+repo                                 Mon, 2016\-02\-15 19:26:54
+root\-2016\-02\-15                      Mon, 2016\-02\-15 19:36:29
+newname                              Mon, 2016\-02\-15 19:50:19
+\&...
+
+$ borg list /path/to/repo::root\-2016\-02\-15
+drwxr\-xr\-x root   root          0 Mon, 2016\-02\-15 17:44:27 .
+drwxrwxr\-x root   root          0 Mon, 2016\-02\-15 19:04:49 bin
+\-rwxr\-xr\-x root   root    1029624 Thu, 2014\-11\-13 00:08:51 bin/bash
+lrwxrwxrwx root   root          0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff
+\-rwxr\-xr\-x root   root       2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
+\&...
+
+$ borg list /path/to/repo::archiveA \-\-list\-format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
+drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 .
+drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code
+drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code/myproject
+\-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
+\&...
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP, \fIborg\-info(1)\fP, \fIborg\-diff(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-patterns(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-mount.1

@@ -0,0 +1,115 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-MOUNT 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-mount \- Mount archive or an entire repository as a FUSE filesystem
+.
+.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 mount <options> REPOSITORY_OR_ARCHIVE MOUNTPOINT
+.SH DESCRIPTION
+.sp
+This command mounts an archive as a FUSE filesystem. This can be useful for
+browsing an archive or restoring individual files. Unless the \fB\-\-foreground\fP
+option is given the command will run in the background until the filesystem
+is \fBumounted\fP\&.
+.sp
+The command \fBborgfs\fP provides a wrapper for \fBborg mount\fP\&. This can also be
+used in fstab entries:
+\fB/path/to/repo /mnt/point fuse.borgfs defaults,noauto 0 0\fP
+.sp
+To allow a regular user to use fstab entries, add the \fBuser\fP option:
+\fB/path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0\fP
+.sp
+For mount options, see the fuse(8) manual page. Additional mount options
+supported by borg:
+.INDENT 0.0
+.IP \(bu 2
+versions: when used with a repository mount, this gives a merged, versioned
+view of the files in the archives. EXPERIMENTAL, layout may change in future.
+.IP \(bu 2
+allow_damaged_files: by default damaged files (where missing chunks were
+replaced with runs of zeros by borg check \-\-repair) are not readable and
+return EIO (I/O error). Set this option to read such files.
+.UNINDENT
+.sp
+The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users
+to tweak the performance. It sets the number of cached data chunks; additional
+memory usage can be up to ~8 MiB times this number. The default is the number
+of CPU cores.
+.sp
+When the daemonized process receives a signal or crashes, it does not unmount.
+Unmounting in these cases could cause an active rsync or similar process
+to unintentionally delete data.
+.sp
+When running in the foreground ^C/SIGINT unmounts cleanly, but other
+signals or crashes do not.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B REPOSITORY_OR_ARCHIVE
+repository/archive to mount
+.TP
+.B MOUNTPOINT
+where to mount filesystem
+.UNINDENT
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B \-f\fP,\fB  \-\-foreground
+stay in foreground, do not daemonize
+.TP
+.B \-o
+Extra mount options
+.UNINDENT
+.SS filters
+.INDENT 0.0
+.TP
+.B \-P\fP,\fB  \-\-prefix
+only consider archive names starting with this prefix
+.TP
+.B \-\-sort\-by
+Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+.TP
+.BI \-\-first \ N
+consider first N archives after other filters were applied
+.TP
+.BI \-\-last \ N
+consider last N archives after other filters were applied
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP, \fIborg\-umount(1)\fP, \fIborg\-extract(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-patterns.1

@@ -0,0 +1,144 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-PATTERNS 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-patterns \- Details regarding patterns
+.
+.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 DESCRIPTION
+.sp
+Exclusion patterns support four separate styles, fnmatch, shell, regular
+expressions and path prefixes. By default, fnmatch is used. If followed
+by a colon (\(aq:\(aq) the first two characters of a pattern are used as a
+style selector. Explicit style selection is necessary when a
+non\-default style is desired or when the desired pattern starts with
+two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP).
+.sp
+\fI\%Fnmatch\fP, selector \fIfm:\fP
+.INDENT 0.0
+.INDENT 3.5
+This is the default style.  These patterns use a variant of shell
+pattern syntax, with \(aq*\(aq matching any number of characters, \(aq?\(aq
+matching any single character, \(aq[...]\(aq matching any single
+character specified, including ranges, and \(aq[!...]\(aq matching any
+character not specified. For the purpose of these patterns, the
+path separator (\(aq\(aq for Windows and \(aq/\(aq on other systems) is not
+treated specially. Wrap meta\-characters in brackets for a literal
+match (i.e. \fI[?]\fP to match the literal character \fI?\fP). For a path
+to match a pattern, it must completely match from start to end, or
+must match from the start to just before a path separator. Except
+for the root path, paths will never end in the path separator when
+matching is attempted.  Thus, if a given pattern ends in a path
+separator, a \(aq*\(aq is appended before matching is attempted.
+.UNINDENT
+.UNINDENT
+.sp
+Shell\-style patterns, selector \fIsh:\fP
+.INDENT 0.0
+.INDENT 3.5
+Like fnmatch patterns these are similar to shell patterns. The difference
+is that the pattern may include \fI**/\fP for matching zero or more directory
+levels, \fI*\fP for matching zero or more arbitrary characters with the
+exception of any path separator.
+.UNINDENT
+.UNINDENT
+.sp
+Regular expressions, selector \fIre:\fP
+.INDENT 0.0
+.INDENT 3.5
+Regular expressions similar to those found in Perl are supported. Unlike
+shell patterns regular expressions are not required to match the complete
+path and any substring match is sufficient. It is strongly recommended to
+anchor patterns to the start (\(aq^\(aq), to the end (\(aq$\(aq) or both. Path
+separators (\(aq\(aq for Windows and \(aq/\(aq on other systems) in paths are
+always normalized to a forward slash (\(aq/\(aq) before applying a pattern. The
+regular expression syntax is described in the \fI\%Python documentation for
+the re module\fP\&.
+.UNINDENT
+.UNINDENT
+.sp
+Prefix path, selector \fIpp:\fP
+.INDENT 0.0
+.INDENT 3.5
+This pattern style is useful to match whole sub\-directories. The pattern
+\fIpp:/data/bar\fP matches \fI/data/bar\fP and everything therein.
+.UNINDENT
+.UNINDENT
+.sp
+Exclusions can be passed via the command line option \fI\-\-exclude\fP\&. When used
+from within a shell the patterns should be quoted to protect them from
+expansion.
+.sp
+The \fI\-\-exclude\-from\fP option permits loading exclusion patterns from a text
+file with one pattern per line. Lines empty or starting with the number sign
+(\(aq#\(aq) after removing whitespace on both ends are ignored. The optional style
+selector prefix is also supported for patterns loaded from a file. Due to
+whitespace removal paths with whitespace at the beginning or end can only be
+excluded using regular expressions.
+.sp
+Examples:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Exclude \(aq/home/user/file.o\(aq but not \(aq/home/user/file.odt\(aq:
+$ borg create \-e \(aq*.o\(aq backup /
+
+# Exclude \(aq/home/user/junk\(aq and \(aq/home/user/subdir/junk\(aq but
+# not \(aq/home/user/importantjunk\(aq or \(aq/etc/junk\(aq:
+$ borg create \-e \(aq/home/*/junk\(aq backup /
+
+# Exclude the contents of \(aq/home/user/cache\(aq but not the directory itself:
+$ borg create \-e /home/user/cache/ backup /
+
+# The file \(aq/home/user/cache/important\(aq is *not* backed up:
+$ borg create \-e /home/user/cache/ backup / /home/user/cache/important
+
+# The contents of directories in \(aq/home\(aq are not backed up when their name
+# ends in \(aq.tmp\(aq
+$ borg create \-\-exclude \(aqre:^/home/[^/]+\e.tmp/\(aq backup /
+
+# Load exclusions from file
+$ cat >exclude.txt <<EOF
+# Comment line
+/home/*/junk
+*.tmp
+fm:aa:something/*
+re:^/home/[^/]\e.tmp/
+sh:/home/*/.thumbnails
+EOF
+$ borg create \-\-exclude\-from exclude.txt backup /
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-placeholders.1

@@ -0,0 +1,126 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-PLACEHOLDERS 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-placeholders \- Details regarding placeholders
+.
+.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 DESCRIPTION
+.sp
+Repository (or Archive) URLs, \-\-prefix and \-\-remote\-path values support these
+placeholders:
+.sp
+{hostname}
+.INDENT 0.0
+.INDENT 3.5
+The (short) hostname of the machine.
+.UNINDENT
+.UNINDENT
+.sp
+{fqdn}
+.INDENT 0.0
+.INDENT 3.5
+The full name of the machine.
+.UNINDENT
+.UNINDENT
+.sp
+{now}
+.INDENT 0.0
+.INDENT 3.5
+The current local date and time, by default in ISO\-8601 format.
+You can also supply your own \fI\%format string\fP, e.g. {now:%Y\-%m\-%d_%H:%M:%S}
+.UNINDENT
+.UNINDENT
+.sp
+{utcnow}
+.INDENT 0.0
+.INDENT 3.5
+The current UTC date and time, by default in ISO\-8601 format.
+You can also supply your own \fI\%format string\fP, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S}
+.UNINDENT
+.UNINDENT
+.sp
+{user}
+.INDENT 0.0
+.INDENT 3.5
+The user name (or UID, if no name is available) of the user running borg.
+.UNINDENT
+.UNINDENT
+.sp
+{pid}
+.INDENT 0.0
+.INDENT 3.5
+The current process ID.
+.UNINDENT
+.UNINDENT
+.sp
+{borgversion}
+.INDENT 0.0
+.INDENT 3.5
+The version of borg, e.g.: 1.0.8rc1
+.UNINDENT
+.UNINDENT
+.sp
+{borgmajor}
+.INDENT 0.0
+.INDENT 3.5
+The version of borg, only the major version, e.g.: 1
+.UNINDENT
+.UNINDENT
+.sp
+{borgminor}
+.INDENT 0.0
+.INDENT 3.5
+The version of borg, only major and minor version, e.g.: 1.0
+.UNINDENT
+.UNINDENT
+.sp
+{borgpatch}
+.INDENT 0.0
+.INDENT 3.5
+The version of borg, only major, minor and patch version, e.g.: 1.0.8
+.UNINDENT
+.UNINDENT
+.sp
+Examples:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+borg create /path/to/repo::{hostname}\-{user}\-{utcnow} ...
+borg create /path/to/repo::{hostname}\-{now:%Y\-%m\-%d_%H:%M:%S} ...
+borg prune \-\-prefix \(aq{hostname}\-\(aq ...
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-prune.1

@@ -0,0 +1,177 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-PRUNE 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-prune \- Prune repository archives according to specified rules
+.
+.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 prune <options> REPOSITORY
+.SH DESCRIPTION
+.sp
+The prune command prunes a repository by deleting all archives not matching
+any of the specified retention options. This command is normally used by
+automated backup scripts wanting to keep a certain number of historic backups.
+.sp
+Also, prune automatically removes checkpoint archives (incomplete archives left
+behind by interrupted backup runs) except if the checkpoint is the latest
+archive (and thus still needed). Checkpoint archives are not considered when
+comparing archive counts against the retention limits (\-\-keep\-X).
+.sp
+If a prefix is set with \-P, then only archives that start with the prefix are
+considered for deletion and only those archives count towards the totals
+specified by the rules.
+Otherwise, \fIall\fP archives in the repository are candidates for deletion!
+There is no automatic distinction between archives representing different
+contents. These need to be distinguished by specifying matching prefixes.
+.sp
+If you have multiple sequences of archives with different data sets (e.g.
+from different machines) in one shared repository, use one prune call per
+data set that matches only the respective archives using the \-P option.
+.sp
+The "\-\-keep\-within" option takes an argument of the form "<int><char>",
+where char is "H", "d", "w", "m", "y". For example, "\-\-keep\-within 2d" means
+to keep all archives that were created within the past 48 hours.
+"1m" is taken to mean "31d". The archives kept with this option do not
+count towards the totals specified by any other options.
+.sp
+A good procedure is to thin out more and more the older your backups get.
+As an example, "\-\-keep\-daily 7" means to keep the latest backup on each day,
+up to 7 most recent days with backups (days without backups do not count).
+The rules are applied from secondly to yearly, and backups selected by previous
+rules do not count towards those of later rules. The time that each backup
+starts is used for pruning purposes. Dates and times are interpreted in
+the local timezone, and weeks go from Monday to Sunday. Specifying a
+negative number of archives to keep means that there is no limit.
+.sp
+The "\-\-keep\-last N" option is doing the same as "\-\-keep\-secondly N" (and it will
+keep the last N archives under the assumption that you do not create more than one
+backup archive in the same second).
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B REPOSITORY
+repository to prune
+.UNINDENT
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B \-n\fP,\fB  \-\-dry\-run
+do not change repository
+.TP
+.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
+.B \-\-list
+output verbose list of archives it keeps/prunes
+.TP
+.BI \-\-keep\-within \ WITHIN
+keep all archives within this time interval
+.TP
+.B \-\-keep\-last\fP,\fB  \-\-keep\-secondly
+number of secondly archives to keep
+.TP
+.B \-\-keep\-minutely
+number of minutely archives to keep
+.TP
+.B \-H\fP,\fB  \-\-keep\-hourly
+number of hourly archives to keep
+.TP
+.B \-d\fP,\fB  \-\-keep\-daily
+number of daily archives to keep
+.TP
+.B \-w\fP,\fB  \-\-keep\-weekly
+number of weekly archives to keep
+.TP
+.B \-m\fP,\fB  \-\-keep\-monthly
+number of monthly archives to keep
+.TP
+.B \-y\fP,\fB  \-\-keep\-yearly
+number of yearly archives to keep
+.TP
+.B \-P\fP,\fB  \-\-prefix
+only consider archive names starting with this prefix
+.TP
+.B \-\-save\-space
+work slower, but using less space
+.UNINDENT
+.SH EXAMPLES
+.sp
+Be careful, prune is a potentially dangerous command, it will remove backup
+archives.
+.sp
+The default of prune is to apply to \fBall archives in the repository\fP unless
+you restrict its operation to a subset of the archives using \fB\-\-prefix\fP\&.
+When using \fB\-\-prefix\fP, be careful to choose a good prefix \- e.g. do not use a
+prefix "foo" if you do not also want to match "foobar".
+.sp
+It is strongly recommended to always run \fBprune \-v \-\-list \-\-dry\-run ...\fP
+first so you will see what it would do without it actually doing anything.
+.sp
+There is also a visualized prune example in \fBdocs/misc/prune\-example.txt\fP\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Keep 7 end of day and 4 additional end of week archives.
+# Do a dry\-run without actually deleting anything.
+$ borg prune \-v \-\-list \-\-dry\-run \-\-keep\-daily=7 \-\-keep\-weekly=4 /path/to/repo
+
+# Same as above but only apply to archive names starting with the hostname
+# of the machine followed by a "\-" character:
+$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-prefix=\(aq{hostname}\-\(aq /path/to/repo
+
+# Keep 7 end of day, 4 additional end of week archives,
+# and an end of month archive for every month:
+$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo
+
+# Keep all backups in the last 10 days, 4 additional end of week archives,
+# and an end of month archive for every month:
+$ borg prune \-v \-\-list \-\-keep\-within=10d \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-recreate.1

@@ -0,0 +1,192 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-RECREATE 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-recreate \- Re-create 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 recreate <options> REPOSITORY_OR_ARCHIVE PATH
+.SH DESCRIPTION
+.sp
+Recreate the contents of existing archives.
+.sp
+This is an \fIexperimental\fP feature. Do \fInot\fP use this on your only backup.
+.sp
+\-\-exclude, \-\-exclude\-from and PATH have the exact same semantics
+as in "borg create". If PATHs are specified the resulting archive
+will only contain files from these PATHs.
+.sp
+Note that all paths in an archive are relative, therefore absolute patterns/paths
+will \fInot\fP match (\-\-exclude, \-\-exclude\-from, \-\-compression\-from, PATHs).
+.sp
+\-\-compression: all chunks seen will be stored using the given method.
+Due to how Borg stores compressed size information this might display
+incorrect information for archives that were not recreated at the same time.
+There is no risk of data loss by this.
+.sp
+\-\-chunker\-params will re\-chunk all files in the archive, this can be
+used to have upgraded Borg 0.xx or Attic archives deduplicate with
+Borg 1.x archives.
+.sp
+USE WITH CAUTION.
+Depending on the PATHs and patterns given, recreate can be used to permanently
+delete files from archives.
+When in doubt, use "\-\-dry\-run \-\-verbose \-\-list" to see how patterns/PATHS are
+interpreted.
+.sp
+The archive being recreated is only removed after the operation completes. The
+archive that is built during the operation exists at the same time at
+"<ARCHIVE>.recreate". The new archive will have a different archive ID.
+.sp
+With \-\-target the original archive is not replaced, instead a new archive is created.
+.sp
+When rechunking space usage can be substantial, expect at least the entire
+deduplicated size of the archives using the previous chunker params.
+When recompressing expect approx. (throughput / checkpoint\-interval) in space usage,
+assuming all chunks are recompressed.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B REPOSITORY_OR_ARCHIVE
+repository/archive to recreate
+.TP
+.B PATH
+paths to recreate; patterns are supported
+.UNINDENT
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B \-\-list
+output verbose list of items (files, dirs, ...)
+.TP
+.BI \-\-filter \ STATUSCHARS
+only display items with the given status characters
+.TP
+.B \-p\fP,\fB  \-\-progress
+show progress display while recreating archives
+.TP
+.B \-n\fP,\fB  \-\-dry\-run
+do not change anything
+.TP
+.B \-s\fP,\fB  \-\-stats
+print statistics at end
+.UNINDENT
+.SS Exclusion options
+.INDENT 0.0
+.TP
+.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN
+exclude paths matching PATTERN
+.TP
+.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
+keep tag objects (i.e.: arguments to \-\-exclude\-if\-present) in otherwise                                          excluded caches/directories
+.UNINDENT
+.SS Archive options
+.INDENT 0.0
+.TP
+.BI \-\-target \ TARGET
+create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)
+.TP
+.BI \-c \ SECONDS\fP,\fB \ \-\-checkpoint\-interval \ SECONDS
+write checkpoint every SECONDS seconds (Default: 1800)
+.TP
+.BI \-\-comment \ COMMENT
+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.
+.TP
+.BI \-C \ COMPRESSION\fP,\fB \ \-\-compression \ COMPRESSION
+select compression algorithm, see the output of the "borg help compression" command for details.
+.TP
+.B \-\-always\-recompress
+always recompress chunks, don\(aqt skip chunks already compressed with the same algorithm.
+.TP
+.BI \-\-compression\-from \ COMPRESSIONCONFIG
+read compression patterns from COMPRESSIONCONFIG, see the output of the "borg help compression" command for details.
+.TP
+.BI \-\-chunker\-params \ PARAMS
+specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or "default" to use the current defaults. default: 19,23,21,4095
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives
+# Archives created with Borg 1.1+ and the default chunker params are skipped (archive ID stays the same)
+$ borg recreate /mnt/backup \-\-chunker\-params default \-\-progress
+
+# Create a backup with little but fast compression
+$ borg create /mnt/backup::archive /some/files \-\-compression lz4
+# Then compress it \- this might take longer, but the backup has already completed, so no inconsistencies
+# from a long\-running backup job.
+$ borg recreate /mnt/backup::archive \-\-compression zlib,9
+
+# Remove unwanted files from all archives in a repository
+$ borg recreate /mnt/backup \-e /home/icke/Pictures/drunk_photos
+
+
+# Change archive comment
+$ borg create \-\-comment "This is a comment" /mnt/backup::archivename ~
+$ borg info /mnt/backup::archivename
+Name: archivename
+Fingerprint: ...
+Comment: This is a comment
+\&...
+$ borg recreate \-\-comment "This is a better comment" /mnt/backup::archivename
+$ borg info /mnt/backup::archivename
+Name: archivename
+Fingerprint: ...
+Comment: This is a better comment
+\&...
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-rename.1

@@ -0,0 +1,76 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-RENAME 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-rename \- Rename an existing archive
+.
+.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 rename <options> ARCHIVE NEWNAME
+.SH DESCRIPTION
+.sp
+This command renames an archive in the repository.
+.sp
+This results in a different archive ID.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B ARCHIVE
+archive to rename
+.TP
+.B NEWNAME
+the new archive name to use
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg create /path/to/repo::archivename ~
+$ borg list /path/to/repo
+archivename                          Mon, 2016\-02\-15 19:50:19
+
+$ borg rename /path/to/repo::archivename newname
+$ borg list /path/to/repo
+newname                              Mon, 2016\-02\-15 19:50:19
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-serve.1

@@ -0,0 +1,80 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-SERVE 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-serve \- Start in server mode. This command is usually not used manually.
+.
+.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 serve <options>
+.SH DESCRIPTION
+.sp
+This command starts a repository server process. This command is usually not used manually.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS optional arguments
+.INDENT 0.0
+.TP
+.BI \-\-restrict\-to\-path \ PATH
+restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub\-directories is granted implicitly; PATH doesn\(aqt need to directly point to a repository.
+.TP
+.B \-\-append\-only
+only allow appending to repository segment files
+.UNINDENT
+.SH EXAMPLES
+.sp
+borg serve has special support for ssh forced commands (see \fBauthorized_keys\fP
+example below): it will detect that you use such a forced command and extract
+the value of the \fB\-\-restrict\-to\-path\fP option(s).
+It will then parse the original command that came from the client, makes sure
+that it is also \fBborg serve\fP and enforce path restriction(s) as given by the
+forced command. That way, other options given by the client (like \fB\-\-info\fP or
+\fB\-\-umask\fP) are preserved (and are not fixed by the forced command).
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
+# Use key options to disable unneeded and potentially dangerous SSH functionality.
+# This will help to secure an automated remote backup system.
+$ cat ~/.ssh/authorized_keys
+command="borg serve \-\-restrict\-to\-path /path/to/repo",no\-pty,no\-agent\-forwarding,no\-port\-forwarding,no\-X11\-forwarding,no\-user\-rc ssh\-rsa AAAAB3[...]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-umount.1

@@ -0,0 +1,115 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-UMOUNT 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-umount \- un-mount the FUSE filesystem
+.
+.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 umount <options> MOUNTPOINT
+.SH DESCRIPTION
+.sp
+This command un\-mounts a FUSE filesystem that was mounted with \fBborg mount\fP\&.
+.sp
+This is a convenience wrapper that just calls the platform\-specific shell
+command \- usually this is either umount or fusermount \-u.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B MOUNTPOINT
+mountpoint of the filesystem to umount
+.UNINDENT
+.SH EXAMPLES
+.SS borg mount
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg mount /path/to/repo::root\-2016\-02\-15 /tmp/mymountpoint
+$ ls /tmp/mymountpoint
+bin  boot  etc      home  lib  lib64  lost+found  media  mnt  opt  root  sbin  srv  tmp  usr  var
+$ borg umount /tmp/mymountpoint
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg mount \-o versions /path/to/repo /tmp/mymountpoint
+$ ls \-l /tmp/mymountpoint/home/user/doc.txt/
+total 24
+\-rw\-rw\-r\-\- 1 user group 12357 Aug 26 21:19 doc.txt.cda00bc9
+\-rw\-rw\-r\-\- 1 user group 12204 Aug 26 21:04 doc.txt.fa760f28
+$ fusermount \-u /tmp/mymountpoint
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS borgfs
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ echo \(aq/mnt/backup /tmp/myrepo fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab
+$ echo \(aq/mnt/backup::root\-2016\-02\-15 /tmp/myarchive fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab
+$ mount /tmp/myrepo
+$ mount /tmp/myarchive
+$ ls /tmp/myrepo
+root\-2016\-02\-01 root\-2016\-02\-2015
+$ ls /tmp/myarchive
+bin  boot  etc      home  lib  lib64  lost+found  media  mnt  opt  root  sbin  srv  tmp  usr  var
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+\fBborgfs\fP will be automatically provided if you used a distribution
+package, \fBpip\fP or \fBsetup.py\fP to install Borg\&. Users of the
+standalone binary will have to manually create a symlink (see
+\fIpyinstaller\-binary\fP).
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP, \fIborg\-mount(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-upgrade.1

@@ -0,0 +1,170 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-UPGRADE 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-upgrade \- upgrade a repository from a previous version
+.
+.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 upgrade <options> REPOSITORY
+.SH DESCRIPTION
+.sp
+Upgrade an existing Borg repository.
+.SS Borg 1.x.y upgrades
+.sp
+Use \fBborg upgrade \-\-tam REPO\fP to require manifest authentication
+introduced with Borg 1.0.9 to address security issues. This means
+that modifying the repository after doing this with a version prior
+to 1.0.9 will raise a validation error, so only perform this upgrade
+after updating all clients using the repository to 1.0.9 or newer.
+.sp
+This upgrade should be done on each client for safety reasons.
+.sp
+If a repository is accidentally modified with a pre\-1.0.9 client after
+this upgrade, use \fBborg upgrade \-\-tam \-\-force REPO\fP to remedy it.
+.sp
+If you routinely do this you might not want to enable this upgrade
+(which will leave you exposed to the security issue). You can
+reverse the upgrade by issuing \fBborg upgrade \-\-disable\-tam REPO\fP\&.
+.sp
+See
+\fI\%https://borgbackup.readthedocs.io/en/stable/changes.html#pre\-1\-0\-9\-manifest\-spoofing\-vulnerability\fP
+for details.
+.SS Attic and Borg 0.xx to Borg 1.x
+.sp
+This currently supports converting an Attic repository to Borg and also
+helps with converting Borg 0.xx to 1.0.
+.sp
+Currently, only LOCAL repositories can be upgraded (issue #465).
+.sp
+It will change the magic strings in the repository\(aqs segments
+to match the new Borg magic strings. The keyfiles found in
+$ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and
+copied to $BORG_KEYS_DIR or ~/.config/borg/keys.
+.sp
+The cache files are converted, from $ATTIC_CACHE_DIR or
+~/.cache/attic to $BORG_CACHE_DIR or ~/.cache/borg, but the
+cache layout between Borg and Attic changed, so it is possible
+the first backup after the conversion takes longer than expected
+due to the cache resync.
+.sp
+Upgrade should be able to resume if interrupted, although it
+will still iterate over all segments. If you want to start
+from scratch, use \fIborg delete\fP over the copied repository to
+make sure the cache files are also removed:
+.INDENT 0.0
+.INDENT 3.5
+borg delete borg
+.UNINDENT
+.UNINDENT
+.sp
+Unless \fB\-\-inplace\fP is specified, the upgrade process first
+creates a backup copy of the repository, in
+REPOSITORY.upgrade\-DATETIME, using hardlinks. This takes
+longer than in place upgrades, but is much safer and gives
+progress information (as opposed to \fBcp \-al\fP). Once you are
+satisfied with the conversion, you can safely destroy the
+backup copy.
+.sp
+WARNING: Running the upgrade in place will make the current
+copy unusable with older version, with no way of going back
+to previous versions. This can PERMANENTLY DAMAGE YOUR
+REPOSITORY!  Attic CAN NOT READ BORG REPOSITORIES, as the
+magic strings have changed. You have been warned.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B REPOSITORY
+path to the repository to be upgraded
+.UNINDENT
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B \-p\fP,\fB  \-\-progress
+show progress display while upgrading the repository
+.TP
+.B \-n\fP,\fB  \-\-dry\-run
+do not change repository
+.TP
+.B \-i\fP,\fB  \-\-inplace
+rewrite repository in place, with no chance of going back to older
+versions of the repository.
+.TP
+.B \-\-force
+Force upgrade
+.TP
+.B \-\-tam
+Enable manifest authentication (in key and cache) (Borg 1.0.9 and later)
+.TP
+.B \-\-disable\-tam
+Disable manifest authentication (in key and cache)
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Upgrade the borg repository to the most recent version.
+$ borg upgrade \-v /path/to/repo
+making a hardlink copy in /path/to/repo.upgrade\-2016\-02\-15\-20:51:55
+opening attic repository with borg and converting
+no key file found for repository
+converting repo index /path/to/repo/index.0
+converting 1 segments...
+converting borg 0.xx to borg current
+no key file found for repository
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Upgrading a passphrase encrypted attic repo
+.sp
+attic offered a "passphrase" encryption mode, but this was removed in borg 1.0
+and replaced by the "repokey" mode (which stores the passphrase\-protected
+encryption key into the repository config).
+.sp
+Thus, to upgrade a "passphrase" attic repo to a "repokey" borg repo, 2 steps
+are needed, in this order:
+.INDENT 0.0
+.IP \(bu 2
+borg upgrade repo
+.IP \(bu 2
+borg key migrate\-to\-repokey repo
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-with-lock.1

@@ -0,0 +1,71 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-WITH-LOCK 1 "2017-02-05" "" "borg backup tool"
+.SH NAME
+borg-with-lock \- run a user specified command with the repository lock held
+.
+.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 with\-lock <options> REPOSITORY COMMAND ARGS
+.SH DESCRIPTION
+.sp
+This command runs a user\-specified command while the repository lock is held.
+.sp
+It will first try to acquire the lock (make sure that no other operation is
+running in the repo), then execute the given command as a subprocess and wait
+for its termination, release the lock and return the user command\(aqs return
+code as borg\(aqs return code.
+.INDENT 0.0
+.TP
+.B Note: if you copy a repository with the lock held, the lock will be present in
+the copy, obviously. Thus, before using borg on the copy, you need to
+use "borg break\-lock" on it.
+.UNINDENT
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B REPOSITORY
+repository to lock
+.TP
+.B COMMAND
+command to run
+.TP
+.B ARGS
+command arguments
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/usage.rst

@@ -359,14 +359,14 @@ Examples
 ~~~~~~~~
 ::
 
-    # Local repository (default is to use encryption in repokey mode)
-    $ borg init /path/to/repo
+    # Local repository, repokey encryption, BLAKE2b (often faster, since Borg 1.1)
+    $ borg init --encryption=repokey-blake2 /path/to/repo
 
     # Local repository (no encryption)
     $ borg init --encryption=none /path/to/repo
 
     # Remote repository (accesses a remote borg via ssh)
-    $ borg init user@hostname:backup
+    $ borg init --encryption=repokey-blake2 user@hostname:backup
 
     # Remote repository (store the key your home dir)
     $ borg init --encryption=keyfile user@hostname:backup
@@ -528,7 +528,7 @@ Examples
 ~~~~~~~~
 ::
 
-    $ borg init testrepo
+    $ borg init -e=none testrepo
     $ mkdir testdir
     $ cd testdir
     $ echo asdf > file1
@@ -719,7 +719,7 @@ Fully automated using environment variables:
 
 ::
 
-    $ BORG_NEW_PASSPHRASE=old borg init repo
+    $ BORG_NEW_PASSPHRASE=old borg init -e=repokey repo
     # now "old" is the current passphrase.
     $ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change-passphrase repo
     # now "new" is the current passphrase.

setup.py

@@ -1,7 +1,10 @@
 # -*- encoding: utf-8 *-*
 import os
+import io
 import re
 import sys
+from collections import OrderedDict
+from datetime import datetime
 from glob import glob
 
 from distutils.command.build import build
@@ -326,6 +329,217 @@ class build_usage(Command):
         shipout(text)
 
 
+class build_man(Command):
+    description = 'build man pages'
+
+    user_options = []
+
+    see_also = {
+        'create': ('delete', 'prune', 'check', 'patterns', 'placeholders', 'compression'),
+        'recreate': ('patterns', 'placeholders', 'compression'),
+        'list': ('info', 'diff', 'prune', 'patterns'),
+        'info': ('list', 'diff'),
+        'init': ('create', 'delete', 'check', 'list', 'key-import', 'key-export', 'key-change-passphrase'),
+        'key-import': ('key-export', ),
+        'key-export': ('key-import', ),
+        'mount': ('umount', 'extract'),  # Would be cooler if these two were on the same page
+        'umount': ('mount', ),
+        'extract': ('mount', ),
+    }
+
+    rst_prelude = textwrap.dedent("""
+    .. role:: ref(title)
+
+    .. |project_name| replace:: Borg
+    """)
+
+    def initialize_options(self):
+        pass
+
+    def finalize_options(self):
+        pass
+
+    def run(self):
+        print('building man pages (in docs/man)', file=sys.stderr)
+        os.makedirs('docs/man', exist_ok=True)
+        # allows us to build docs without the C modules fully loaded during help generation
+        from borg.archiver import Archiver
+        parser = Archiver(prog='borg').parser
+
+        self.generate_level('', parser, Archiver)
+        self.build_topic_pages(Archiver)
+
+    def generate_level(self, prefix, parser, Archiver):
+        is_subcommand = False
+        choices = {}
+        for action in parser._actions:
+            if action.choices is not None and 'SubParsersAction' in str(action.__class__):
+                is_subcommand = True
+                for cmd, parser in action.choices.items():
+                    choices[prefix + cmd] = parser
+        if prefix and not choices:
+            return
+
+        for command, parser in sorted(choices.items()):
+            if command.startswith('debug') or command == 'help':
+                continue
+
+            man_title = 'borg-' + command.replace(' ', '-')
+            print('building man page', man_title + '(1)', file=sys.stderr)
+
+            if self.generate_level(command + ' ', parser, Archiver):
+                continue
+
+            doc, write = self.new_doc()
+            self.write_man_header(write, man_title, parser.description)
+
+            self.write_heading(write, 'SYNOPSIS')
+            write('borg', command, end='')
+            self.write_usage(write, parser)
+            write('\n')
+
+            self.write_heading(write, 'DESCRIPTION')
+            write(parser.epilog)
+
+            self.write_heading(write, 'OPTIONS')
+            write('See `borg-common(1)` for common options of Borg commands.')
+            write()
+            self.write_options(write, parser)
+
+            self.write_examples(write, command)
+
+            self.write_see_also(write, man_title)
+
+            self.gen_man_page(man_title, doc.getvalue())
+
+        # Generate the borg-common(1) man page with the common options.
+        if 'create' in choices:
+            doc, write = self.new_doc()
+            man_title = 'borg-common'
+            self.write_man_header(write, man_title, 'Common options of Borg commands')
+
+            common_options = [group for group in choices['create']._action_groups if group.title == 'Common options'][0]
+
+            self.write_heading(write, 'SYNOPSIS')
+            self.write_options_group(write, common_options)
+            self.write_see_also(write, man_title)
+            self.gen_man_page(man_title, doc.getvalue())
+
+        return is_subcommand
+
+    def build_topic_pages(self, Archiver):
+        for topic, text in Archiver.helptext.items():
+            doc, write = self.new_doc()
+            man_title = 'borg-' + topic
+            print('building man page', man_title + '(1)', file=sys.stderr)
+
+            self.write_man_header(write, man_title, 'Details regarding ' + topic)
+            self.write_heading(write, 'DESCRIPTION')
+            write(text)
+            self.gen_man_page(man_title, doc.getvalue())
+
+    def new_doc(self):
+        doc = io.StringIO(self.rst_prelude)
+        doc.read()
+        write = self.printer(doc)
+        return doc, write
+
+    def printer(self, fd):
+        def write(*args, **kwargs):
+            print(*args, file=fd, **kwargs)
+        return write
+
+    def write_heading(self, write, header, char='-', double_sided=False):
+        write()
+        if double_sided:
+            write(char * len(header))
+        write(header)
+        write(char * len(header))
+        write()
+
+    def write_man_header(self, write, title, description):
+        self.write_heading(write, title, '=', double_sided=True)
+        self.write_heading(write, description, double_sided=True)
+        # man page metadata
+        write(':Author: The Borg Collective')
+        write(':Date:', datetime.utcnow().date().isoformat())
+        write(':Manual section: 1')
+        write(':Manual group: borg backup tool')
+        write()
+
+    def write_examples(self, write, command):
+        with open('docs/usage.rst') as fd:
+            usage = fd.read()
+            usage_include = '.. include:: usage/%s.rst.inc' % command
+            begin = usage.find(usage_include)
+            end = usage.find('.. include', begin + 1)
+            examples = usage[begin:end]
+            examples = examples.replace(usage_include, '')
+            examples = examples.replace('Examples\n~~~~~~~~', '')
+            examples = examples.replace('Miscellaneous Help\n------------------', '')
+            examples = re.sub('^(~+)$', lambda matches: '+' * len(matches.group(0)), examples, flags=re.MULTILINE)
+            examples = examples.strip()
+        if examples:
+            self.write_heading(write, 'EXAMPLES', '-')
+            write(examples)
+
+    def write_see_also(self, write, man_title):
+        see_also = self.see_also.get(man_title.replace('borg-', ''), ())
+        see_also = ['`borg-%s(1)`' % s for s in see_also]
+        see_also.insert(0, '`borg-common(1)`')
+        self.write_heading(write, 'SEE ALSO')
+        write(', '.join(see_also))
+
+    def gen_man_page(self, name, rst):
+        from docutils.writers import manpage
+        from docutils.core import publish_string
+        man_page = publish_string(source=rst, writer=manpage.Writer())
+        with open('docs/man/%s.1' % name, 'wb') as fd:
+            fd.write(man_page)
+
+    def write_usage(self, write, parser):
+        if any(len(o.option_strings) for o in parser._actions):
+            write(' <options> ', end='')
+        for option in parser._actions:
+            if option.option_strings:
+                continue
+            write(option.metavar, end=' ')
+
+    def write_options(self, write, parser):
+        for group in parser._action_groups:
+            if group.title == 'Common options' or not group._group_actions:
+                continue
+            title = 'arguments' if group.title == 'positional arguments' else group.title
+            self.write_heading(write, title, '+')
+            self.write_options_group(write, group)
+
+    def write_options_group(self, write, group):
+        def is_positional_group(group):
+            return any(not o.option_strings for o in group._group_actions)
+
+        if is_positional_group(group):
+            for option in group._group_actions:
+                write(option.metavar)
+                write(textwrap.indent(option.help or '', ' ' * 4))
+            return
+
+        opts = OrderedDict()
+
+        for option in group._group_actions:
+            if option.metavar:
+                option_fmt = '%s ' + option.metavar
+            else:
+                option_fmt = '%s'
+            option_str = ', '.join(option_fmt % s for s in option.option_strings)
+            option_desc = textwrap.dedent((option.help or '') % option.__dict__)
+            opts[option_str] = textwrap.indent(option_desc, ' ' * 4)
+
+        padding = len(max(opts)) + 1
+
+        for option, desc in opts.items():
+            write(option.ljust(padding), desc)
+
+
 class build_api(Command):
     description = "generate a basic api.rst file based on the modules available"
 
@@ -361,6 +575,7 @@ cmdclass = {
     'build_ext': build_ext,
     'build_api': build_api,
     'build_usage': build_usage,
+    'build_man': build_man,
     'sdist': Sdist
 }
 

src/borg/archiver.py

@@ -179,8 +179,7 @@ class Archiver:
         return matcher, include_patterns
 
     def do_serve(self, args):
-        """Start in server mode. This command is usually not used manually.
-        """
+        """Start in server mode. This command is usually not used manually."""
         return RepositoryServer(restrict_to_paths=args.restrict_to_paths, append_only=args.append_only).serve()
 
     @with_repository(create=True, exclusive=True, manifest=False)
@@ -2024,16 +2023,17 @@ class Archiver:
                                    help='add a comment text to the archive')
         archive_group.add_argument('--timestamp', dest='timestamp',
                                    type=timestamp, default=None,
-                                   metavar='yyyy-mm-ddThh:mm:ss',
-                                   help='manually specify the archive creation date/time (UTC). '
+                                   metavar='TIMESTAMP',
+                                   help='manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). '
                                         'alternatively, give a reference file/directory.')
         archive_group.add_argument('-c', '--checkpoint-interval', dest='checkpoint_interval',
                                    type=int, default=1800, metavar='SECONDS',
                                    help='write checkpoint every SECONDS seconds (Default: 1800)')
         archive_group.add_argument('--chunker-params', dest='chunker_params',
                                    type=ChunkerParams, default=CHUNKER_PARAMS,
-                                   metavar='CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE',
-                                   help='specify the chunker parameters. default: %d,%d,%d,%d' % CHUNKER_PARAMS)
+                                   metavar='PARAMS',
+                                   help='specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, '
+                                        'HASH_MASK_BITS, HASH_WINDOW_SIZE). default: %d,%d,%d,%d' % CHUNKER_PARAMS)
         archive_group.add_argument('-C', '--compression', dest='compression',
                                    type=CompressionSpec, default=dict(name='none'), metavar='COMPRESSION',
                                    help='select compression algorithm, see the output of the '
@@ -2204,12 +2204,15 @@ class Archiver:
         See the "borg help patterns" command for more help on exclude patterns.
 
         The following keys are available for --format:
+
         """) + BaseFormatter.keys_help() + textwrap.dedent("""
 
-        -- Keys for listing repository archives:
+        Keys for listing repository archives:
+
         """) + ArchiveFormatter.keys_help() + textwrap.dedent("""
 
-        -- Keys for listing archive files:
+        Keys for listing archive files:
+
         """) + ItemFormatter.keys_help()
         subparser = subparsers.add_parser('list', parents=[common_parser], add_help=False,
                                           description=self.do_list.__doc__,
@@ -2348,7 +2351,7 @@ class Archiver:
         Also, prune automatically removes checkpoint archives (incomplete archives left
         behind by interrupted backup runs) except if the checkpoint is the latest
         archive (and thus still needed). Checkpoint archives are not considered when
-        comparing archive counts against the retention limits (--keep-*).
+        comparing archive counts against the retention limits (--keep-X).
 
         If a prefix is set with -P, then only archives that start with the prefix are
         considered for deletion and only those archives count towards the totals
@@ -2607,8 +2610,8 @@ class Archiver:
                                    help='add a comment text to the archive')
         archive_group.add_argument('--timestamp', dest='timestamp',
                                    type=timestamp, default=None,
-                                   metavar='yyyy-mm-ddThh:mm:ss',
-                                   help='manually specify the archive creation date/time (UTC). '
+                                   metavar='TIMESTAMP',
+                                   help='manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). '
                                         'alternatively, give a reference file/directory.')
         archive_group.add_argument('-C', '--compression', dest='compression',
                                    type=CompressionSpec, default=None, metavar='COMPRESSION',
@@ -2623,9 +2626,11 @@ class Archiver:
                                    help='read compression patterns from COMPRESSIONCONFIG, see the output of the '
                                         '"borg help compression" command for details.')
         archive_group.add_argument('--chunker-params', dest='chunker_params',
-                                   type=ChunkerParams, default=None,
-                                   metavar='CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE',
-                                   help='specify the chunker parameters (or "default").')
+                                   type=ChunkerParams, default=CHUNKER_PARAMS,
+                                   metavar='PARAMS',
+                                   help='specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, '
+                                        'HASH_MASK_BITS, HASH_WINDOW_SIZE) or "default" to use the current defaults. '
+                                        'default: %d,%d,%d,%d' % CHUNKER_PARAMS)
 
         subparser.add_argument('location', metavar='REPOSITORY_OR_ARCHIVE', nargs='?', default='',
                                type=location_validator(),