build_usage

docs/usage/benchmark_crud.rst.inc

@@ -50,7 +50,7 @@ This command benchmarks borg CRUD (create, read, update, delete) operations.
 
 It creates input data below the given PATH and backups this data into the given REPO.
 The REPO must already exist (it could be a fresh empty repo or an existing repo, the
-command will create / read / update / delete some archives named borg-test-data\* there.
+command will create / read / update / delete some archives named borg-benchmark-crud\* there.
 
 Make sure you have free space there, you'll need about 1GB each (+ overhead).
 
@@ -70,7 +70,7 @@ C- == borg create (1st archive creation, no compression, do not use files cache)
 R- == borg extract (extract archive, dry-run, do everything, but do not write files to disk)
       R-Z- == all zero files. Measuring heavily duplicated files.
       R-R- == random files. No duplication here, measuring throughput through all processing
-              stages, except writing to disk.
+      stages, except writing to disk.
 
 U- == borg create (2nd archive creation of unchanged input files, measure files cache speed)
       The throughput value is kind of virtual here, it does not actually read the file.

docs/usage/common-options.rst.inc

@@ -15,3 +15,4 @@
 --remote-ratelimit RATE    set remote network upload rate limit in kiByte/s (default: 0=unlimited)
 --consider-part-files    treat part files like normal files (e.g. to list/extract them)
 --debug-profile FILE    Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof".
+--rsh RSH          Use this command to connect to the 'borg serve' process (default: 'ssh')

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
 
@@ -27,6 +27,8 @@ borg config
     +-------------------------------------------------------+----------------------+----------------------------------------+
     |                                                       | ``-d``, ``--delete`` | delete the key from the config file    |
     +-------------------------------------------------------+----------------------+----------------------------------------+
+    |                                                       | ``-l``, ``--list``   | list the configuration of the repo     |
+    +-------------------------------------------------------+----------------------+----------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                        |
     |                                                                                                                       |
     | :ref:`common_options`                                                                                                 |
@@ -51,8 +53,9 @@ borg config
 
 
     optional arguments
-        -c, --cache      get and set values from the repo cache
-        -d, --delete     delete the key from the config file
+        -c, --cache    get and set values from the repo cache
+        -d, --delete    delete the key from the config file
+        -l, --list     list the configuration of the repo
 
 
     :ref:`common_options`
@@ -64,10 +67,13 @@ Description
 This command gets and sets options in a local repository or cache config file.
 For security reasons, this command only works on local repositories.
 
-To delete a config value entirely, use ``--delete``. To get an existing key, pass
-only the key name. To set a key, pass both the key name and the new value. Keys
-can be specified in the format "section.name" or simply "name"; the section will
-default to "repository" and "cache" for the repo and cache configs, respectively.
+To delete a config value entirely, use ``--delete``. To list the values
+of the configuration file or the default values, use ``--list``.  To get and existing
+key, pass only the key name. To set a key, pass both the key name and
+the new value. Keys can be specified in the format "section.name" or
+simply "name"; the section will default to "repository" and "cache" for
+the repo and cache configs, respectively.
+
 
 By default, borg config manipulates the repository config file. Using ``--cache``
 edits the repository cache's config file instead.

docs/usage/create.rst.inc

@@ -33,7 +33,7 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--no-cache-sync``                               | experimental: do not synchronize the cache. Implies not using the files cache.                                                                    |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--no-files-cache``                              | do not load/update the file metadata cache used to detect unchanged files                                                                         |
+    |                                                       | ``--stdin-name NAME``                             | use NAME in archive for stdin data (default: "stdin")                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                |
     |                                                                                                                                                                                                                                                               |
@@ -49,11 +49,11 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--patterns-from PATTERNFILE``                   | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                        |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)                                              |
+    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                   |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-if-present NAME``                     | exclude directories that are tagged by containing a filesystem object with the given NAME                                                         |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--keep-exclude-tags``, ``--keep-tag-files``     | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                         |
+    |                                                       | ``--keep-exclude-tags``                           | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                         |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-nodump``                              | exclude files flagged NODUMP                                                                                                                      |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -71,8 +71,6 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--nobsdflags``                                  | do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive                                                                              |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--ignore-inode``                                | ignore inode data in the file metadata cache used to detect unchanged files.                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--files-cache MODE``                            | operate files cache in MODE. default: ctime,size,inode                                                                                            |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--read-special``                                | open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files. |
@@ -85,7 +83,7 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                            |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095                           |
+    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095             |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details.                                                  |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -113,7 +111,7 @@ borg create
         --filter STATUSCHARS    only display items with the given status characters (see description)
         --json          output stats as JSON. Implies ``--stats``.
         --no-cache-sync    experimental: do not synchronize the cache. Implies not using the files cache.
-        --no-files-cache    do not load/update the file metadata cache used to detect unchanged files
+        --stdin-name NAME    use NAME in archive for stdin data (default: "stdin")
 
 
     :ref:`common_options`
@@ -124,9 +122,9 @@ borg create
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
         --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
-        --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
+        --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)
         --exclude-if-present NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
-        --keep-exclude-tags, --keep-tag-files    if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
+        --keep-exclude-tags               if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
         --exclude-nodump                  exclude files flagged NODUMP
 
 
@@ -137,7 +135,6 @@ borg create
         --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
-        --ignore-inode            ignore inode data in the file metadata cache used to detect unchanged files.
         --files-cache MODE        operate files cache in MODE. default: ctime,size,inode
         --read-special            open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.
 
@@ -146,7 +143,7 @@ borg create
         --comment COMMENT                             add a comment text to the archive
         --timestamp TIMESTAMP                         manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory.
         -c SECONDS, --checkpoint-interval SECONDS     write checkpoint every SECONDS seconds (Default: 1800)
-        --chunker-params PARAMS                       specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
+        --chunker-params PARAMS                       specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095
         -C COMPRESSION, --compression COMPRESSION     select compression algorithm, see the output of the "borg help compression" command for details.
 
 

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).
 

docs/usage/help.rst.inc

@@ -6,6 +6,15 @@ borg help patterns
 ~~~~~~~~~~~~~~~~~~
 
 
+The path/filenames used as input for the pattern matching start from the
+currently active recursion root. You usually give the recursion root(s)
+when invoking borg and these can be either relative or absolute paths.
+
+So, when you give `relative/` as root, the paths going into the matcher
+will look like `relative/.../file.ext`. When you give `/absolute/` as root,
+they will look like `/absolute/.../file.ext`. This is meant when we talk
+about "full path" below.
+
 File patterns support these styles: fnmatch, shell, regular expressions,
 path prefixes and path full-matches. By default, fnmatch is used for
 ``--exclude`` patterns and shell-style is used for the experimental ``--pattern``
@@ -22,11 +31,11 @@ two alphanumeric characters followed by a colon (i.e. `aa:something/*`).
     any number of characters, '?' matching any single character, '[...]'
     matching any single character specified, including ranges, and '[!...]'
     matching any character not specified. For the purpose of these patterns,
-    the path separator ('\' for Windows and '/' on other systems) is not
+    the path separator (backslash for Windows and '/' on other systems) is not
     treated specially. Wrap meta-characters in brackets for a literal
     match (i.e. `[?]` to match the literal character `?`). For a path
-    to match a pattern, it must completely match from start to end, or
-    must match from the start to just before a path separator. Except
+    to match a pattern, the full path must match, or it must match
+    from the start of the full path to just before a path separator. Except
     for the root path, paths will never end in the path separator when
     matching is attempted.  Thus, if a given pattern ends in a path
     separator, a '\*' is appended before matching is attempted.
@@ -40,23 +49,23 @@ Shell-style patterns, selector `sh:`
 
 Regular expressions, selector `re:`
     Regular expressions similar to those found in Perl are supported. Unlike
-    shell patterns regular expressions are not required to match the complete
+    shell patterns regular expressions are not required to match the full
     path and any substring match is sufficient. It is strongly recommended to
     anchor patterns to the start ('^'), to the end ('$') or both. Path
-    separators ('\' for Windows and '/' on other systems) in paths are
+    separators (backslash for Windows and '/' on other systems) in paths are
     always normalized to a forward slash ('/') before applying a pattern. The
     regular expression syntax is described in the `Python documentation for
     the re module <https://docs.python.org/3/library/re.html>`_.
 
 Path prefix, selector `pp:`
     This pattern style is useful to match whole sub-directories. The pattern
-    `pp:/data/bar` matches `/data/bar` and everything therein.
+    `pp:root/somedir` matches `root/somedir` and everything therein.
 
 Path full-match, selector `pf:`
-    This pattern style is useful to match whole paths.
+    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, precise path must be given.
-    `pf:/data/foo.txt` matches `/data/foo.txt` only.
+    unspecified parts - the full path must be given.
+    `pf:root/file.ext` matches `root/file.txt` only.
 
     Implementation note: this is implemented via very time-efficient O(1)
     hashtable lookups (this means you can have huge amounts of such patterns
@@ -139,7 +148,16 @@ Examples::
     considered first (in the order of appearance). Then patterns from ``--patterns-from``
     are added. Exclusion patterns from ``--exclude-from`` files are appended last.
 
-    An example ``--patterns-from`` file could look like that::
+    Examples::
+
+        # backup pics, but not the ones from 2018, except the good ones:
+        # note: using = is essential to avoid cmdline argument parsing issues.
+        borg create --pattern=+pics/2018/good --pattern=-pics/2018 repo::arch pics
+
+        # use a file with patterns:
+        borg create --patterns-from patterns.lst repo::arch
+
+    The patterns.lst file could look like that::
 
         # "sh:" pattern style is the default, so the following line is not needed:
         P sh
@@ -241,7 +259,13 @@ none
     Do not compress.
 
 lz4
-    Use lz4 compression. High speed, low compression. (default)
+    Use lz4 compression. Very high speed, very low compression. (default)
+
+zstd[,L]
+    Use zstd ("zstandard") compression, a modern wide-range algorithm.
+    If you do not explicitly give the compression level L (ranging from 1
+    to 22), it will use level 3.
+    Archives compressed with zstd are not compatible with borg < 1.1.4.
 
 zlib[,L]
     Use zlib ("gz") compression. Medium speed, medium compression.
@@ -268,6 +292,8 @@ auto,C[,L]
 Examples::
 
     borg create --compression lz4 REPO::ARCHIVE data
+    borg create --compression zstd REPO::ARCHIVE data
+    borg create --compression zstd,10 REPO::ARCHIVE data
     borg create --compression zlib REPO::ARCHIVE data
     borg create --compression zlib,1 REPO::ARCHIVE data
     borg create --compression auto,lzma,6 REPO::ARCHIVE data

docs/usage/init.rst.inc

@@ -12,23 +12,25 @@ borg init
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                 |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    |                                                       | ``REPOSITORY``                     | repository to create                                                        |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                   |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    |                                                       | ``-e MODE``, ``--encryption MODE`` | select encryption key mode **(required)**                                   |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    |                                                       | ``--append-only``                  | create an append-only mode repository                                       |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    |                                                       | ``--storage-quota QUOTA``          | Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota. |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                           |
-    |                                                                                                                                                                          |
-    | :ref:`common_options`                                                                                                                                                    |
-    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                                                                                                                            |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``REPOSITORY``                     | repository to create                                                                                                                                                                                                                   |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                                                                                                                                              |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-e MODE``, ``--encryption MODE`` | select encryption key mode **(required)**                                                                                                                                                                                              |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--append-only``                  | create an append-only mode repository. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details. |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--storage-quota QUOTA``          | Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.                                                                                                                                                            |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--make-parent-dirs``             | create the parent directories of the repository directory, if they are missing.                                                                                                                                                        |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                                                                      |
+    |                                                                                                                                                                                                                                                                                                                                     |
+    | :ref:`common_options`                                                                                                                                                                                                                                                                                                               |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -46,8 +48,9 @@ borg init
 
     optional arguments
         -e MODE, --encryption MODE     select encryption key mode **(required)**
-        --append-only                  create an append-only mode repository
+        --append-only                  create an append-only mode repository. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.
         --storage-quota QUOTA          Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
+        --make-parent-dirs             create the parent directories of the repository directory, if they are missing.
 
 
     :ref:`common_options`

docs/usage/key_import.rst.inc

@@ -58,4 +58,4 @@ This command restores a key previously backed up with the export command.
 
 If the ``--paper`` option is given, the import will be an interactive
 process in which each line is checked for plausibility before
-proceeding to the next line. For this format PATH must not be given.
+proceeding to the next line. For this format PATH must not be given.

docs/usage/list.rst.inc

@@ -129,6 +129,9 @@ Keys for listing repository archives:
 - time: alias of "start"
 - end: time (end) of creation of the archive
 
+- hostname: hostname of host on which this archive was created
+- username: username of user who created this archive
+
 
 Keys for listing archive files:
 

docs/usage/mount.rst.inc

@@ -113,14 +113,18 @@ used in fstab entries:
 To allow a regular user to use fstab entries, add the ``user`` option:
 ``/path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0``
 
-For mount options, see the fuse(8) manual page. Additional mount options
-supported by borg:
+For FUSE configuration and mount options, see the mount.fuse(8) manual page.
+
+Additional mount options supported by borg:
 
 - 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.
 - allow_damaged_files: by default damaged files (where missing chunks were
   replaced with runs of zeros by borg check ``--repair``) are not readable and
   return EIO (I/O error). Set this option to read such files.
+- ignore_permissions: for security reasons the "default_permissions" mount
+  option is internally enforced by borg. "ignore_permissions" can be given to
+  not enforce "default_permissions".
 
 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

docs/usage/recreate.rst.inc

@@ -43,11 +43,11 @@ borg recreate
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--patterns-from PATTERNFILE``                   | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                                                                                                                                                 |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)                                                                                                                                                                                                                                                                       |
+    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                                                                                                                                                                                                                                            |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-if-present NAME``                     | exclude directories that are tagged by containing a filesystem object with the given NAME                                                                                                                                                                                                                                                                                  |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--keep-exclude-tags``, ``--keep-tag-files``     | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                                                                                                                                                                                                                                                  |
+    |                                                       | ``--keep-exclude-tags``                           | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                                                                                                                                                                                                                                                  |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **Archive options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -63,7 +63,7 @@ borg recreate
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--recompress MODE``                             | recompress data chunks according to ``--compression``. MODE `if-different`: recompress if current compression is with a different compression algorithm (the level is not considered). MODE `always`: recompress even if current compression is with the same compression algorithm (use this to change the compression level). MODE `never` (default): do not recompress. |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: 19,23,21,4095                                                                                                                                                                                                           |
+    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: buzhash,19,23,21,4095                                                                                                                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
@@ -97,9 +97,9 @@ borg recreate
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
         --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
-        --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
+        --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)
         --exclude-if-present NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
-        --keep-exclude-tags, --keep-tag-files    if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
+        --keep-exclude-tags               if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
 
 
     Archive options
@@ -109,7 +109,7 @@ borg recreate
         --timestamp TIMESTAMP                         manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
         -C COMPRESSION, --compression COMPRESSION     select compression algorithm, see the output of the "borg help compression" command for details.
         --recompress MODE                             recompress data chunks according to ``--compression``. MODE `if-different`: recompress if current compression is with a different compression algorithm (the level is not considered). MODE `always`: recompress even if current compression is with the same compression algorithm (use this to change the compression level). MODE `never` (default): do not recompress.
-        --chunker-params PARAMS                       specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: 19,23,21,4095
+        --chunker-params PARAMS                       specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: buzhash,19,23,21,4095
 
 
 Description

docs/usage/serve.rst.inc

@@ -19,7 +19,7 @@ borg serve
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--restrict-to-repository PATH`` | restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--append-only``                 | only allow appending to repository segment files                                                                                                                                                                                                                                                                                                                                                                                                                      |
+    |                                                       | ``--append-only``                 | only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.                                                                                                                                                                                                                     |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--storage-quota QUOTA``         | Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.                                                                                                                                                                                                                                                                                              |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -43,7 +43,7 @@ borg serve
     optional arguments
         --restrict-to-path PATH    restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository.
         --restrict-to-repository PATH    restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
-        --append-only             only allow appending to repository segment files
+        --append-only             only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.
         --storage-quota QUOTA     Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.
 
 

docs/usage/with-lock.rst.inc

@@ -57,5 +57,9 @@ running in the repo), then execute the given command as a subprocess and wait
 for its termination, release the lock and return the user command's return
 code as borg's return code.
 
-As example you can use "borg with-lock" to copy a repo to another location
-(see :ref:`can_i_copy_or_synchronize_my_repo_to_another_location` in the FAQ).
+.. note::
+
+    If you copy a repository with the lock held, the lock will be present in
+    the copy. Thus, before using borg on the copy from a different host,
+    you need to use "borg break-lock" on the copied repository, because
+    Borg is cautious and does not automatically remove stale locks made by a different host.