build_usage

docs/usage/check.rst.inc

@@ -84,6 +84,9 @@ Description
 
 The check command verifies the consistency of a repository and the corresponding archives.
 
+check --repair is a potentially dangerous function and might lead to data loss
+(for kinds of corruption it is not capable of dealing with). BE VERY CAREFUL!
+
 First, the underlying repository data files are checked:
 
 - For all segments, the segment magic header is checked.

docs/usage/create.rst.inc

@@ -162,7 +162,8 @@ that means if relative paths are desired, the command has to be run from the cor
 directory.
 
 When giving '-' as path, borg will read data from standard input and create a
-file 'stdin' in the created archive from that data.
+file 'stdin' in the created archive from that data. See section *Reading from
+stdin* below for details.
 
 The archive will consume almost no disk space for files or parts of files that
 have already been stored in other archives.
@@ -204,6 +205,7 @@ ctime vs. mtime: safety vs. speed
   as it can not be set from userspace. But, a metadata-only change will already
   update the ctime, so there might be some unnecessary chunking/hashing even
   without content changes. Some filesystems do not support ctime (change time).
+  E.g. doing a chown or chmod to a file will change its ctime.
 - mtime usually works and only updates if file contents were changed. But mtime
   can be arbitrarily set from userspace, e.g. to set mtime back to the same value
   it had before a content change happened. This can be used maliciously as well as
@@ -243,6 +245,8 @@ only include the objects specified by ``--exclude-if-present`` in your backup,
 and not include any other contents of the containing folder, this can be enabled
 through using the ``--keep-exclude-tags`` option.
 
+.. _list_item_flags:
+
 Item flags
 ++++++++++
 
@@ -280,4 +284,23 @@ Other flags used include:
 - 'i' = backup data was read from standard input (stdin)
 - '-' = dry run, item was *not* backed up
 - 'x' = excluded, item was *not* backed up
-- '?' = missing status code (if you see this, please file a bug report!)
+- '?' = missing status code (if you see this, please file a bug report!)
+
+Reading from stdin
+++++++++++++++++++
+
+To read from stdin, specify ``-`` as path and pipe directly to borg::
+
+    backup-vm --id myvm --stdout | borg create REPO::ARCHIVE -
+
+Note that piping to borg creates an archive even if the command piping
+to borg exits with a failure. In this case, **one can end up with
+truncated output being backed up**.
+
+Reading from stdin yields just a stream of data without file metadata
+associated with it, and the files cache is not needed at all. So it is
+safe to disable it via ``--no-files-cache`` and speed up backup
+creation a bit.
+
+By default, the content read from stdin is stored in a file called 'stdin'.
+Use ``--stdin-name`` to change the name.

docs/usage/help.rst.inc

@@ -74,7 +74,7 @@ Path full-match, selector `pf:`
     This pattern style is (only) useful to match full paths.
     This is kind of a pseudo pattern as it can not have any variable or
     unspecified parts - the full path must be given.
-    `pf:root/file.ext` matches `root/file.txt` only.
+    `pf:root/file.ext` matches `root/file.ext` only.
 
     Implementation note: this is implemented via very time-efficient O(1)
     hashtable lookups (this means you can have huge amounts of such patterns

docs/usage/prune.rst.inc

@@ -21,7 +21,7 @@ borg prune
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``-n``, ``--dry-run``                 | do not change repository                                                                                                                               |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--force``                           | force pruning of corrupted archives                                                                                                                    |
+    |                                                                             | ``--force``                           | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work.                                                        |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``-s``, ``--stats``                   | print statistics for the deleted archive                                                                                                               |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -72,7 +72,7 @@ borg prune
 
     optional arguments
         -n, --dry-run         do not change repository
-        --force               force pruning of corrupted archives
+        --force               force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
         -s, --stats           print statistics for the deleted archive
         --list                output verbose list of archives it keeps/prunes
         --keep-within INTERVAL    keep all archives within this time interval

docs/usage/recreate.rst.inc

@@ -117,11 +117,13 @@ Description
 
 Recreate the contents of existing archives.
 
-This is an *experimental* feature. Do *not* use this on your only backup.
+recreate is a potentially dangerous function and might lead to data loss
+(if used wrongly). BE VERY CAREFUL!
 
-``--exclude``, ``--exclude-from``, ``--exclude-if-present``, ``--keep-exclude-tags``, 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.
+``--exclude``, ``--exclude-from``, ``--exclude-if-present``, ``--keep-exclude-tags``
+and PATH have the exact same semantics as in "borg create", but they only check
+for files in the archives and not in the local file system. If PATHs are specified,
+the resulting archives will only contain files from these PATHs.
 
 Note that all paths in an archive are relative, therefore absolute patterns/paths
 will *not* match (``--exclude``, ``--exclude-from``, PATHs).
@@ -139,7 +141,7 @@ Borg 1.x archives.
 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.
+interpreted. See :ref:`list_item_flags` in ``borg create`` for details.
 
 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