build_usage

11 files changed, 49 insertions, 38 deletions

diff --git a/docs/usage/benchmark_crud.rst.inc b/docs/usage/benchmark_crud.rst.inc
index c3a768a1b..3e67d7b6b 100644
--- a/docs/usage/benchmark_crud.rst.inc
+++ b/docs/usage/benchmark_crud.rst.inc
@@ -6,23 +6,23 @@ borg benchmark crud
 -------------------
 .. code-block:: none
 
-    borg [common options] benchmark crud [options] REPO PATH
+    borg [common options] benchmark crud [options] REPOSITORY PATH
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+----------+------------------------------------------+
-    | **positional arguments**                                                                                    |
-    +-------------------------------------------------------+----------+------------------------------------------+
-    |                                                       | ``REPO`` | repo to use for benchmark (must exist)   |
-    +-------------------------------------------------------+----------+------------------------------------------+
-    |                                                       | ``PATH`` | path were to create benchmark input data |
-    +-------------------------------------------------------+----------+------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                              |
-    |                                                                                                             |
-    | :ref:`common_options`                                                                                       |
-    +-------------------------------------------------------+----------+------------------------------------------+
+    +-------------------------------------------------------+----------------+----------------------------------------------+
+    | **positional arguments**                                                                                              |
+    +-------------------------------------------------------+----------------+----------------------------------------------+
+    |                                                       | ``REPOSITORY`` | repository to use for benchmark (must exist) |
+    +-------------------------------------------------------+----------------+----------------------------------------------+
+    |                                                       | ``PATH``       | path were to create benchmark input data     |
+    +-------------------------------------------------------+----------------+----------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                        |
+    |                                                                                                                       |
+    | :ref:`common_options`                                                                                                 |
+    +-------------------------------------------------------+----------------+----------------------------------------------+
 
     .. raw:: html
 
@@ -34,8 +34,8 @@ borg benchmark crud
 
 .. only:: latex
 
-    REPO
-        repo to use for benchmark (must exist)
+    REPOSITORY
+        repository to use for benchmark (must exist)
     PATH
         path were to create benchmark input data
 
@@ -54,12 +54,9 @@ command will create / read / update / delete some archives named borg-benchmark-
 
 Make sure you have free space there, you'll need about 1GB each (+ overhead).
 
-Important: The space used in the repository will **not** be freed until you run
-``borg compact``.
+If your repository is encrypted and borg needs a passphrase to unlock the key, use::
 
-If your repository is encrypted and borg needs a passphrase to unlock the key, use:
-
-BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
+    BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
 
 Measurements are done with different input file sizes and counts.
 The file contents are very artificial (either all zero or all random),
diff --git a/docs/usage/compact.rst.inc b/docs/usage/compact.rst.inc
index 7ae3d397c..90fb93529 100644
--- a/docs/usage/compact.rst.inc
+++ b/docs/usage/compact.rst.inc
@@ -6,7 +6,7 @@ borg compact
 ------------
 .. code-block:: none
 
-    borg [common options] compact [options] REPOSITORY
+    borg [common options] compact [options] [REPOSITORY]
 
 .. only:: html
 
@@ -53,11 +53,19 @@ Description
 This command frees repository space by compacting segments.
 
 Use this regularly to avoid running out of space - you do not need to use this
-after each borg command though.
+after each borg command though. It is especially useful after deleting archives,
+because only compaction will really free repository space.
 
 borg compact does not need a key, so it is possible to invoke it from the
 client or also from the server.
 
-Depending on the amount of segments that need compaction, it may take a while.
+Depending on the amount of segments that need compaction, it may take a while,
+so consider using the ``--progress`` option.
+
+When using ``--verbose``, borg will output an estimate of the freed space.
+
+After upgrading borg (server) to 1.2+, you can use ``borg compact --cleanup-commits``
+to clean up the numerous 17byte commit-only segments that borg 1.1 did not clean up
+due to a bug. It is enough to do that once per repository.
 
 See :ref:`separate_compaction` in Additional Notes for more details.
\ No newline at end of file
diff --git a/docs/usage/config.rst.inc b/docs/usage/config.rst.inc
index 1a204d8a0..d90c327ee 100644
--- a/docs/usage/config.rst.inc
+++ b/docs/usage/config.rst.inc
@@ -6,7 +6,7 @@ borg config
 -----------
 .. code-block:: none
 
-    borg [common options] config [options] REPOSITORY [NAME] [VALUE]
+    borg [common options] config [options] [REPOSITORY] [NAME] [VALUE]
 
 .. only:: html
 
diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc
index 536c1bc69..e48e41148 100644
--- a/docs/usage/create.rst.inc
+++ b/docs/usage/create.rst.inc
@@ -65,6 +65,8 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--noatime``                                     | do not store atime into archive                                                                                                                   |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--atime``                                       | do store atime into archive                                                                                                                       |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--noctime``                                     | do not store ctime into archive                                                                                                                   |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--nobirthtime``                                 | do not store birthtime (creation date) into archive                                                                                               |
@@ -132,6 +134,7 @@ borg create
         -x, --one-file-system     stay in the same file system and do not store mount points of other file systems
         --numeric-owner           only store numeric user and group identifiers
         --noatime                 do not store atime into archive
+        --atime                   do store atime into archive
         --noctime                 do not store ctime into archive
         --nobirthtime             do not store birthtime (creation date) into archive
         --nobsdflags              do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive
diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc
index a94b8d524..a33a9ae17 100644
--- a/docs/usage/delete.rst.inc
+++ b/docs/usage/delete.rst.inc
@@ -6,7 +6,7 @@ borg delete
 -----------
 .. code-block:: none
 
-    borg [common options] delete [options] [TARGET] [ARCHIVE...]
+    borg [common options] delete [options] [REPOSITORY_OR_ARCHIVE] [ARCHIVE...]
 
 .. only:: html
 
@@ -15,7 +15,7 @@ borg delete
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **positional arguments**                                                                                                                                                                                                                                                     |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``TARGET``                            | archive or repository to delete                                                                                                                        |
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to delete                                                                                                                        |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``ARCHIVE``                           | archives to delete                                                                                                                                     |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -58,8 +58,8 @@ borg delete
 
 .. only:: latex
 
-    TARGET
-        archive or repository to delete
+    REPOSITORY_OR_ARCHIVE
+        repository or archive to delete
     ARCHIVE
         archives to delete
 
diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc
index 0927dfb20..88c9bf70c 100644
--- a/docs/usage/help.rst.inc
+++ b/docs/usage/help.rst.inc
@@ -171,6 +171,8 @@ Examples::
         + /home/susan
         # don't backup the other home directories
         - /home/*
+        # don't even look in /proc
+        ! /proc
 
 .. _borg_placeholders:
 
@@ -178,8 +180,8 @@ borg help placeholders
 ~~~~~~~~~~~~~~~~~~~~~~
 
 
-Repository (or Archive) URLs, ``--prefix`` and ``--remote-path`` values support these
-placeholders:
+Repository (or Archive) URLs, ``--prefix``, ``--glob-archives``, ``--comment``
+and ``--remote-path`` values support these placeholders:
 
 {hostname}
     The (short) hostname of the machine.
diff --git a/docs/usage/info.rst.inc b/docs/usage/info.rst.inc
index 5ba601f4f..0d6bfe915 100644
--- a/docs/usage/info.rst.inc
+++ b/docs/usage/info.rst.inc
@@ -15,7 +15,7 @@ borg info
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **positional arguments**                                                                                                                                                                                                                                                     |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | archive or repository to display information about                                                                                                     |
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to display information about                                                                                                     |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **optional arguments**                                                                                                                                                                                                                                                       |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -49,7 +49,7 @@ borg info
 .. only:: latex
 
     REPOSITORY_OR_ARCHIVE
-        archive or repository to display information about
+        repository or archive to display information about
 
 
     optional arguments
diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc
index e5a43fcad..b4f6db468 100644
--- a/docs/usage/list.rst.inc
+++ b/docs/usage/list.rst.inc
@@ -15,7 +15,7 @@ borg list
     +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **positional arguments**                                                                                                                                                                                                                                                                                                                                                                               |
     +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``                     | repository/archive to list contents of                                                                                                                                                                                                                                   |
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``                     | repository or archive to list contents of                                                                                                                                                                                                                                |
     +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``PATH``                                      | paths to list; patterns are supported                                                                                                                                                                                                                                    |
     +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -67,7 +67,7 @@ borg list
 .. only:: latex
 
     REPOSITORY_OR_ARCHIVE
-        repository/archive to list contents of
+        repository or archive to list contents of
     PATH
         paths to list; patterns are supported
 
@@ -167,6 +167,7 @@ Keys for listing archive files:
 - sha256
 - sha384
 - sha512
+- xxh64: XXH64 checksum of this file (note: this is NOT a cryptographic hash!)
 
 - archiveid
 - archivename
diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc
index 2520f1ff2..f813f5583 100644
--- a/docs/usage/mount.rst.inc
+++ b/docs/usage/mount.rst.inc
@@ -15,7 +15,7 @@ borg mount
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **positional arguments**                                                                                                                                                                                                                                                     |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository/archive to mount                                                                                                                            |
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to mount                                                                                                                         |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``MOUNTPOINT``                        | where to mount filesystem                                                                                                                              |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -67,7 +67,7 @@ borg mount
 .. only:: latex
 
     REPOSITORY_OR_ARCHIVE
-        repository/archive to mount
+        repository or archive to mount
     MOUNTPOINT
         where to mount filesystem
     PATH
diff --git a/docs/usage/recreate.rst.inc b/docs/usage/recreate.rst.inc
index f2722bc78..de09ccbcc 100644
--- a/docs/usage/recreate.rst.inc
+++ b/docs/usage/recreate.rst.inc
@@ -15,7 +15,7 @@ borg recreate
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **positional arguments**                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``REPOSITORY_OR_ARCHIVE``                         | repository/archive to recreate                                                                                                                                                                                                                                                                                                                                             |
+    |                                                       | ``REPOSITORY_OR_ARCHIVE``                         | repository or archive to recreate                                                                                                                                                                                                                                                                                                                                          |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                                          | paths to recreate; patterns are supported                                                                                                                                                                                                                                                                                                                                  |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -77,7 +77,7 @@ borg recreate
 .. only:: latex
 
     REPOSITORY_OR_ARCHIVE
-        repository/archive to recreate
+        repository or archive to recreate
     PATH
         paths to recreate; patterns are supported
 
diff --git a/docs/usage/upgrade.rst.inc b/docs/usage/upgrade.rst.inc
index 47a240dd0..9f94d2cf8 100644
--- a/docs/usage/upgrade.rst.inc
+++ b/docs/usage/upgrade.rst.inc
@@ -126,7 +126,7 @@ due to the cache resync.
 Upgrade should be able to resume if interrupted, although it
 will still iterate over all segments. If you want to start
 from scratch, use `borg delete` over the copied repository to
-make sure the cache files are also removed:
+make sure the cache files are also removed::
 
     borg delete borg