Merge pull request #2696 from enkore/f/docs-accidental-quotes

docs: fix accidental block quotes

docs/usage/common-options.rst.inc

@@ -1,36 +1,36 @@
-    ``-h``, ``--help``
-        | show this help message and exit
-    ``--critical``
-        | work on log level CRITICAL
-    ``--error``
-        | work on log level ERROR
-    ``--warning``
-        | work on log level WARNING (default)
-    ``--info``, ``-v``, ``--verbose``
-        | work on log level INFO
-    ``--debug``
-        | enable debug output, work on log level DEBUG
-    ``--debug-topic TOPIC``
-        | enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
-    ``-p``, ``--progress``
-        | show progress information
-    ``--log-json``
-        | Output one JSON object per log line instead of formatted text.
-    ``--lock-wait N``
-        | wait for the lock, but max. N seconds (default: 1).
-    ``--show-version``
-        | show/log the borg version
-    ``--show-rc``
-        | show/log the return code (rc)
-    ``--no-files-cache``
-        | do not load/update the file metadata cache used to detect unchanged files
-    ``--umask M``
-        | set umask to M (local and remote, default: 0077)
-    ``--remote-path PATH``
-        | use PATH as borg executable on the remote (default: "borg")
-    ``--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".
+``-h``, ``--help``
+    | show this help message and exit
+``--critical``
+    | work on log level CRITICAL
+``--error``
+    | work on log level ERROR
+``--warning``
+    | work on log level WARNING (default)
+``--info``, ``-v``, ``--verbose``
+    | work on log level INFO
+``--debug``
+    | enable debug output, work on log level DEBUG
+``--debug-topic TOPIC``
+    | enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
+``-p``, ``--progress``
+    | show progress information
+``--log-json``
+    | Output one JSON object per log line instead of formatted text.
+``--lock-wait N``
+    | wait for the lock, but max. N seconds (default: 1).
+``--show-version``
+    | show/log the borg version
+``--show-rc``
+    | show/log the return code (rc)
+``--no-files-cache``
+    | do not load/update the file metadata cache used to detect unchanged files
+``--umask M``
+    | set umask to M (local and remote, default: 0077)
+``--remote-path PATH``
+    | use PATH as borg executable on the remote (default: "borg")
+``--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".

docs/usage/help.rst.inc

@@ -72,6 +72,15 @@ Path full-match, selector `pf:`
     Other include/exclude patterns that would normally match will be ignored.
     Same logic applies for exclude.
 
+.. note::
+
+    `re:`, `sh:` and `fm:` patterns are all implemented on top of the Python SRE
+    engine. It is very easy to formulate patterns for each of these types which
+    requires an inordinate amount of time to match paths. If untrusted users
+    are able to supply patterns, ensure they cannot supply `re:` patterns.
+    Further, ensure that `sh:` and `fm:` patterns only contain a handful of
+    wildcards at most.
+
 Exclusions can be passed via the command line option `--exclude`. When used
 from within a shell the patterns should be quoted to protect them from
 expansion.

docs/usage/init.rst.inc

@@ -15,7 +15,7 @@ positional arguments
 optional arguments
     ``-e``, ``--encryption``
         | select encryption key mode **(required)**
-    ``-a``, ``--append-only``
+    ``--append-only``
         | create an append-only mode repository
     ``--storage-quota``
         | Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
@@ -72,16 +72,23 @@ the encryption/decryption key or other secrets.
 Encryption modes
 ++++++++++++++++
 
+.. nanorst: inline-fill
+
 +----------+---------------+------------------------+--------------------------+
 | Hash/MAC | Not encrypted | Not encrypted,         | Encrypted (AEAD w/ AES)  |
 |          | no auth       | but authenticated      | and authenticated        |
 +----------+---------------+------------------------+--------------------------+
-| SHA-256  | none          | authenticated          | repokey, keyfile         |
+| SHA-256  | none          | `authenticated`        | repokey                  |
+|          |               |                        | keyfile                  |
 +----------+---------------+------------------------+--------------------------+
-| BLAKE2b  | n/a           | authenticated-blake2   | repokey-blake2,          |
-|          |               |                        | keyfile-blake2           |
+| BLAKE2b  | n/a           | `authenticated-blake2` | `repokey-blake2`         |
+|          |               |                        | `keyfile-blake2`         |
 +----------+---------------+------------------------+--------------------------+
 
+.. nanorst: inline-replace
+
+`Marked modes` are new in Borg 1.1 and are not backwards-compatible with Borg 1.0.x.
+
 On modern Intel/AMD CPUs (except very cheap ones), AES is usually
 hardware-accelerated.
 BLAKE2b is faster than SHA256 on Intel/AMD 64-bit CPUs
@@ -114,7 +121,8 @@ This mode is new and *not* compatible with Borg 1.0.x.
 
 `none` mode uses no encryption and no authentication. It uses SHA256 as chunk
 ID hash. Not recommended, rather consider using an authenticated or
-authenticated/encrypted mode.
+authenticated/encrypted mode. This mode has possible denial-of-service issues
+when running ``borg create`` on contents controlled by an attacker.
 Use it only for new repositories where no encryption is wanted **and** when compatibility
 with 1.0.x is important. If compatibility with 1.0.x is not important, use
 `authenticated-blake2` or `authenticated` instead.

docs/usage/list.rst.inc

@@ -67,66 +67,58 @@ See the "borg help patterns" command for more help on exclude patterns.
 
 The following keys are available for ``--format``:
 
- - NEWLINE: OS dependent line separator
- - NL: alias of NEWLINE
- - NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath
- - SPACE
- - TAB
- - CR
- - LF
+- NEWLINE: OS dependent line separator
+- NL: alias of NEWLINE
+- NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath
+- SPACE
+- TAB
+- CR
+- LF
 
 Keys for listing repository archives:
 
- - archive, name: archive name interpreted as text (might be missing non-text characters, see barchive)
- - barchive: verbatim archive name, can contain any character except NUL
- - time: time of creation of the archive
- - id: internal ID of the archive
+- archive, name: archive name interpreted as text (might be missing non-text characters, see barchive)
+- barchive: verbatim archive name, can contain any character except NUL
+- time: time of creation of the archive
+- id: internal ID of the archive
 
 Keys for listing archive files:
 
- - type
- - mode
- - uid
- - gid
- - user
- - group
- - path: path interpreted as text (might be missing non-text characters, see bpath)
- - bpath: verbatim POSIX path, can contain any character except NUL
- - source: link target for links (identical to linktarget)
- - linktarget
- - flags
-
- - size
- - csize: compressed size
- - dsize: deduplicated size
- - dcsize: deduplicated compressed size
- - num_chunks: number of chunks in this file
- - unique_chunks: number of unique chunks in this file
-
- - mtime
- - ctime
- - atime
- - isomtime
- - isoctime
- - isoatime
-
- - blake2b
- - blake2s
- - md5
- - sha1
- - sha224
- - sha256
- - sha384
- - sha3_224
- - sha3_256
- - sha3_384
- - sha3_512
- - sha512
- - shake_128
- - shake_256
-
- - archiveid
- - archivename
- - extra: prepends {source} with " -> " for soft links and " link to " for hard links
-
- - health: either "healthy" (file ok) or "broken" (if file has all-zero replacement chunks)
+- type
+- mode
+- uid
+- gid
+- user
+- group
+- path: path interpreted as text (might be missing non-text characters, see bpath)
+- bpath: verbatim POSIX path, can contain any character except NUL
+- source: link target for links (identical to linktarget)
+- linktarget
+- flags
+
+- size
+- csize: compressed size
+- dsize: deduplicated size
+- dcsize: deduplicated compressed size
+- num_chunks: number of chunks in this file
+- unique_chunks: number of unique chunks in this file
+
+- mtime
+- ctime
+- atime
+- isomtime
+- isoctime
+- isoatime
+
+- md5
+- sha1
+- sha224
+- sha256
+- sha384
+- sha512
+
+- archiveid
+- archivename
+- extra: prepends {source} with " -> " for soft links and " link to " for hard links
+
+- health: either "healthy" (file ok) or "broken" (if file has all-zero replacement chunks)

docs/usage/upgrade.rst.inc

@@ -15,7 +15,7 @@ positional arguments
 optional arguments
     ``-n``, ``--dry-run``
         | do not change repository
-    ``-i``, ``--inplace``
+    ``--inplace``
         | rewrite repository in place, with no chance of going back to older
         |                                versions of the repository.
     ``--force``

setup.py

@@ -274,7 +274,7 @@ class build_usage(Command):
         if 'create' in choices:
             common_options = [group for group in choices['create']._action_groups if group.title == 'Common options'][0]
             with open('docs/usage/common-options.rst.inc', 'w') as doc:
-                self.write_options_group(common_options, doc, False)
+                self.write_options_group(common_options, doc, False, base_indent=0)
 
         return is_subcommand
 
@@ -294,7 +294,7 @@ class build_usage(Command):
             else:
                 self.write_options_group(group, fp)
 
-    def write_options_group(self, group, fp, with_title=True):
+    def write_options_group(self, group, fp, with_title=True, base_indent=4):
         def is_positional_group(group):
             return any(not o.option_strings for o in group._group_actions)
 
@@ -303,7 +303,7 @@ class build_usage(Command):
             return '\n'.join('| ' + line for line in text.splitlines())
 
         def shipout(text):
-            fp.write(textwrap.indent('\n'.join(text), ' ' * 4))
+            fp.write(textwrap.indent('\n'.join(text), ' ' * base_indent))
 
         if not group._group_actions:
             return

src/borg/helpers.py

@@ -1507,13 +1507,13 @@ class BaseFormatter:
 
     @staticmethod
     def keys_help():
-        return " - NEWLINE: OS dependent line separator\n" \
-               " - NL: alias of NEWLINE\n" \
-               " - NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath\n" \
-               " - SPACE\n" \
-               " - TAB\n" \
-               " - CR\n" \
-               " - LF"
+        return "- NEWLINE: OS dependent line separator\n" \
+               "- NL: alias of NEWLINE\n" \
+               "- NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath\n" \
+               "- SPACE\n" \
+               "- TAB\n" \
+               "- CR\n" \
+               "- LF"
 
 
 class ArchiveFormatter(BaseFormatter):
@@ -1535,10 +1535,10 @@ class ArchiveFormatter(BaseFormatter):
 
     @staticmethod
     def keys_help():
-        return " - archive, name: archive name interpreted as text (might be missing non-text characters, see barchive)\n" \
-               " - barchive: verbatim archive name, can contain any character except NUL\n" \
-               " - time: time of creation of the archive\n" \
-               " - id: internal ID of the archive"
+        return "- archive, name: archive name interpreted as text (might be missing non-text characters, see barchive)\n" \
+               "- barchive: verbatim archive name, can contain any character except NUL\n" \
+               "- time: time of creation of the archive\n" \
+               "- id: internal ID of the archive"
 
 
 class ItemFormatter(BaseFormatter):
@@ -1590,7 +1590,7 @@ class ItemFormatter(BaseFormatter):
         for group in cls.KEY_GROUPS:
             for key in group:
                 keys.remove(key)
-                text = " - " + key
+                text = "- " + key
                 if key in cls.KEY_DESCRIPTIONS:
                     text += ": " + cls.KEY_DESCRIPTIONS[key]
                 help.append(text)