Merge pull request #4040 from ThomasWaldmann/update-man-usage

Update man / usage

docs/man/borg-benchmark-crud.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK-CRUD 1 "2018-06-11" "" "borg backup tool"
+.TH BORG-BENCHMARK-CRUD 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-BENCHMARK 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-CHANGE-PASSPHRASE 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-CHECK 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-COMMON 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-COMPRESSION 1 "2018-08-11" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .

docs/man/borg-config.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CONFIG 1 "2018-06-11" "" "borg backup tool"
+.TH BORG-CONFIG 1 "2018-08-11" "" "borg backup tool"
 .SH NAME
 borg-config \- get, set, and delete values in a repository or cache config file
 .

docs/man/borg-create.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CREATE 1 "2018-06-11" "" "borg backup tool"
+.TH BORG-CREATE 1 "2018-08-11" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .

docs/man/borg-delete.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DELETE 1 "2018-06-11" "" "borg backup tool"
+.TH BORG-DELETE 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-DIFF 1 "2018-08-11" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .
@@ -32,12 +32,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-borg [common options] diff [options] REPO_ARCHIVE1 ARCHIVE2 [PATH...]
+borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
 .SH DESCRIPTION
 .sp
 This command finds differences (file contents, user/group/mode) between archives.
 .sp
-A repository location and an archive name must be specified for REPO_ARCHIVE1.
+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
@@ -57,7 +57,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B REPO_ARCHIVE1
+.B REPO::ARCHIVE1
 repository location and ARCHIVE1 name
 .TP
 .B ARCHIVE2

docs/man/borg-export-tar.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXPORT-TAR 1 "2018-06-11" "" "borg backup tool"
+.TH BORG-EXPORT-TAR 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-EXTRACT 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-INFO 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-INIT 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-KEY-EXPORT 1 "2018-08-11" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .

docs/man/borg-key-import.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-IMPORT 1 "2018-06-11" "" "borg backup tool"
+.TH BORG-KEY-IMPORT 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-KEY 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-LIST 1 "2018-08-11" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .

docs/man/borg-mount.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-MOUNT 1 "2018-06-11" "" "borg backup tool"
+.TH BORG-MOUNT 1 "2018-08-11" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .

docs/man/borg-patterns.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PATTERNS 1 "2018-06-11" "" "borg backup tool"
+.TH BORG-PATTERNS 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-PLACEHOLDERS 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-PRUNE 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-RECREATE 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-RENAME 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-SERVE 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-UMOUNT 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-UPGRADE 1 "2018-08-11" "" "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 "2018-06-11" "" "borg backup tool"
+.TH BORG-WITH-LOCK 1 "2018-08-11" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .

docs/man/borg.1

@@ -411,6 +411,14 @@ Borg assumes that it can derive a unique hostname / identity (see \fBborg debug
 If this is not the case or you do not want Borg to automatically remove stale locks,
 set this to \fIno\fP\&.
 .TP
+.B BORG_HOST_ID
+Borg usually computes a host id from the FQDN plus the results of \fBuuid.getnode()\fP (which usually returns
+a unique id based on the MAC address of the network interface. Except if that MAC happens to be all\-zero \- in
+that case it returns a random value, which is not what we want (because it kills automatic stale lock removal).
+So, if you have a all\-zero MAC address or other reasons to better externally control the host id, just set this
+environment variable to a unique value. If all your FQDNs are unique, you can just use the FQDN. If not,
+use \fI\%fqdn@uniqueid\fP\&.
+.TP
 .B BORG_LOGGING_CONF
 When set, use the given filename as \fI\%INI\fP\-style logging configuration.
 .TP
@@ -433,7 +441,7 @@ exceptions is not shown.
 Please only use for good reasons as it makes issues harder to analyze.
 .TP
 .B TMPDIR
-where temporary files are stored (might need a lot of temporary space for some operations)
+where temporary files are stored (might need a lot of temporary space for some operations), see \fI\%tempfile\fP for details
 .UNINDENT
 .TP
 .B Some automatic "answerers" (if set, they automatically answer confirmation questions):
@@ -735,6 +743,8 @@ T}	T{
 Yes
 T}	T{
 Yes
+T}	T{
+Yes (all)
 T}
 _
 T{
@@ -743,6 +753,8 @@ T}	T{
 n/a
 T}	T{
 n/a
+T}	T{
+Yes (all)
 T}
 _
 T{
@@ -751,10 +763,14 @@ T}	T{
 n/a
 T}	T{
 No [2]
+T}	T{
+Yes (all)
 T}
 _
 T{
-Solaris 11
+Solaris and derivatives
+T}	T{
+No [3]
 T}	T{
 No [3]
 T}	T{
@@ -762,10 +778,6 @@ n/a
 T}
 _
 T{
-OpenIndiana
-T}
-_
-T{
 Windows (cygwin)
 T}	T{
 No [4]

docs/man/borgfs.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORGFS 1 "2018-06-11" "" "borg backup tool"
+.TH BORGFS 1 "2018-08-11" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .

docs/usage/diff.rst.inc

@@ -6,7 +6,7 @@ borg diff
 ---------
 .. code-block:: none
 
-    borg [common options] diff [options] REPO_ARCHIVE1 ARCHIVE2 [PATH...]
+    borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
 
 .. only:: html
 
@@ -15,7 +15,7 @@ borg diff
     +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
     | **positional arguments**                                                                                                                                                   |
     +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``REPO_ARCHIVE1``                     | repository location and ARCHIVE1 name                                      |
+    |                                                       | ``REPO::ARCHIVE1``                    | repository location and ARCHIVE1 name                                      |
     +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
     |                                                       | ``ARCHIVE2``                          | ARCHIVE2 name (no repository location allowed)                             |
     +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
@@ -54,7 +54,7 @@ borg diff
 
 .. only:: latex
 
-    REPO_ARCHIVE1
+    REPO::ARCHIVE1
         repository location and ARCHIVE1 name
     ARCHIVE2
         ARCHIVE2 name (no repository location allowed)
@@ -83,7 +83,7 @@ Description
 
 This command finds differences (file contents, user/group/mode) between archives.
 
-A repository location and an archive name must be specified for REPO_ARCHIVE1.
+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).