build_man (1.1-maint)

also: git add borgfs.1

docs/man/borg-benchmark-crud.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK-CRUD 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-BENCHMARK-CRUD 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .

docs/man/borg-benchmark.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-BENCHMARK 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-benchmark \- benchmark command
 .

docs/man/borg-break-lock.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BREAK-LOCK 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .

docs/man/borg-change-passphrase.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CHANGE-PASSPHRASE 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-CHANGE-PASSPHRASE 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-change-passphrase \- Change repository key file passphrase
 .

docs/man/borg-check.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CHECK 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-CHECK 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .

docs/man/borg-common.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMMON 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-COMMON 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .

docs/man/borg-compression.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMPRESSION 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-COMPRESSION 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .

docs/man/borg-create.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CREATE 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-CREATE 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .
@@ -110,8 +110,9 @@ the currently processed path.
 .sp
 When using \fB\-\-stats\fP, you will get some statistics about how much data was
 added \- the "This Archive" deduplicated size there is most interesting as that is
-how much your repository will grow.
-Please note that the "All archives" stats refer to the state after creation.
+how much your repository will grow. Please note that the "All archives" stats refer to
+the state after creation. Also, the \fB\-\-stats\fP and \fB\-\-dry\-run\fP options are mutually
+exclusive because the data is not actually compressed and deduplicated during a dry run.
 .sp
 See the output of the "borg help patterns" command for more help on exclude patterns.
 See the output of the "borg help placeholders" command for more help on placeholders.
@@ -193,6 +194,9 @@ do not store atime into archive
 .B \-\-noctime
 do not store ctime into archive
 .TP
+.B \-\-nobirthtime
+do not store birthtime (creation date) into archive
+.TP
 .B \-\-nobsdflags
 do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive
 .TP

docs/man/borg-delete.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DELETE 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-DELETE 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .

docs/man/borg-diff.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DIFF 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-DIFF 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .

docs/man/borg-export-tar.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXPORT-TAR 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-EXPORT-TAR 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .

docs/man/borg-extract.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXTRACT 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-EXTRACT 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .

docs/man/borg-info.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INFO 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-INFO 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .

docs/man/borg-init.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INIT 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-INIT 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .

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

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-key-change-passphrase \- Change repository key file passphrase
 .

docs/man/borg-key-export.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-EXPORT 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-KEY-EXPORT 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .
@@ -37,6 +37,9 @@ borg [common options] key export [options] [REPOSITORY] [PATH]
 .sp
 If repository encryption is used, the repository is inaccessible
 without the key. This command allows to backup this essential key.
+Note that the backup produced does not include the passphrase itself
+(i.e. the exported key stays encrypted). In order to regain access to a
+repository, one needs both the exported key and the original passphrase.
 .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

docs/man/borg-key-import.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-IMPORT 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-KEY-IMPORT 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .

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

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
 .

docs/man/borg-key.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-KEY 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-key \- Manage a keyfile or repokey of a repository
 .

docs/man/borg-list.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-LIST 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-LIST 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .
@@ -152,10 +152,10 @@ LF
 Keys for listing repository archives:
 .INDENT 0.0
 .IP \(bu 2
-name: archive name interpreted as text (might be missing non\-text characters, see barchive)
-.IP \(bu 2
 archive: archive name interpreted as text (might be missing non\-text characters, see barchive)
 .IP \(bu 2
+name: alias of "archive"
+.IP \(bu 2
 barchive: verbatim archive name, can contain any character except NUL
 .IP \(bu 2
 comment: archive comment interpreted as text (might be missing non\-text characters, see bcomment)
@@ -164,10 +164,10 @@ bcomment: verbatim archive comment, can contain any character except NUL
 .IP \(bu 2
 id: internal ID of the archive
 .IP \(bu 2
-time: time (start) of creation of the archive
-.IP \(bu 2
 start: time (start) of creation of the archive
 .IP \(bu 2
+time: alias of "start"
+.IP \(bu 2
 end: time (end) of creation of the archive
 .UNINDENT
 .sp

docs/man/borg-mount.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-MOUNT 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-MOUNT 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT
+borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
 .SH DESCRIPTION
 .sp
 This command mounts an archive as a FUSE filesystem. This can be useful for
@@ -81,6 +81,9 @@ repository/archive to mount
 .TP
 .B MOUNTPOINT
 where to mount filesystem
+.TP
+.B PATH
+paths to extract; patterns are supported
 .UNINDENT
 .SS optional arguments
 .INDENT 0.0
@@ -109,6 +112,24 @@ consider first N archives after other filters were applied
 .BI \-\-last \ N
 consider last N archives after other filters were applied
 .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
+.BI \-\-pattern \ PATTERN
+experimental: include/exclude paths matching PATTERN
+.TP
+.BI \-\-patterns\-from \ PATTERNFILE
+experimental: read include/exclude patterns from PATTERNFILE, one per line
+.TP
+.BI \-\-strip\-components \ NUMBER
+Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.
+.UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-umount(1)\fP, \fIborg\-extract(1)\fP

docs/man/borg-patterns.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PATTERNS 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-PATTERNS 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .

docs/man/borg-placeholders.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PLACEHOLDERS 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-PLACEHOLDERS 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-placeholders \- Details regarding placeholders
 .

docs/man/borg-prune.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PRUNE 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-PRUNE 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .

docs/man/borg-recreate.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RECREATE 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-RECREATE 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .

docs/man/borg-rename.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RENAME 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-RENAME 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-rename \- Rename an existing archive
 .

docs/man/borg-serve.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-SERVE 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-SERVE 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .

docs/man/borg-umount.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UMOUNT 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-UMOUNT 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .

docs/man/borg-upgrade.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UPGRADE 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-UPGRADE 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-upgrade \- upgrade a repository from a previous version
 .

docs/man/borg-with-lock.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-WITH-LOCK 1 "2017-11-05" "" "borg backup tool"
+.TH BORG-WITH-LOCK 1 "2017-11-25" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .

docs/man/borgfs.1

@@ -0,0 +1,142 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORGFS 1 "2017-11-25" "" "borg backup tool"
+.SH NAME
+borgfs \- 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
+borgfs [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
+.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 \fB\-\-repair\fP) 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
+.TP
+.B PATH
+paths to extract; patterns are supported
+.UNINDENT
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B \-V\fP,\fB  \-\-version
+show version number and exit
+.TP
+.B \-f\fP,\fB  \-\-foreground
+stay in foreground, do not daemonize
+.TP
+.B \-o
+Extra mount options
+.UNINDENT
+.SS Archive filters
+.INDENT 0.0
+.TP
+.BI \-P \ PREFIX\fP,\fB \ \-\-prefix \ PREFIX
+only consider archive names starting with this prefix.
+.TP
+.BI \-a \ GLOB\fP,\fB \ \-\-glob\-archives \ GLOB
+only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
+.TP
+.BI \-\-sort\-by \ KEYS
+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
+.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
+.BI \-\-pattern \ PATTERN
+experimental: include/exclude paths matching PATTERN
+.TP
+.BI \-\-patterns\-from \ PATTERNFILE
+experimental: read include/exclude patterns from PATTERNFILE, one per line
+.TP
+.BI \-\-strip\-components \ NUMBER
+Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.