build_usage

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,9 +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).
 
-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),

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
 

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
 

docs/usage/help.rst.inc

@@ -96,6 +96,9 @@ 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.
 
+To test your exclusion patterns without performing an actual backup you can
+run ``borg create --list --dry-run ...``.
+
 Examples::
 
     # Exclude '/home/user/file.o' but not '/home/user/file.odt':
@@ -134,6 +137,13 @@ Examples::
     A root path starts with the prefix `R`, followed by a path (a plain path, not a
     file pattern). An include rule starts with the prefix +, an exclude rule starts
     with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern.
+
+    .. note::
+
+        Via ``--pattern`` or ``--patterns-from`` you can define BOTH inclusion and exclusion
+        of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and
+        ``--exlude-from`` ONLY excludes are defined.
+
     Inclusion patterns are useful to include paths that are contained in an excluded
     path. The first matching pattern is used so if an include pattern matches before
     an exclude pattern, the file is backed up. If an exclude-norecurse pattern matches
@@ -171,6 +181,8 @@ Examples::
         + /home/susan
         # don't backup the other home directories
         - /home/*
+        # don't even look in /proc
+        ! /proc
 
 .. _borg_placeholders:
 

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

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
 

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

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
 

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