ran build_usage

2016-10-01 18:23:36 +02:00 · 2016-10-01 18:23:36 +02:00 · 0411512750
parent 24feaf35dc
commit 0411512750
8 changed files with 229 additions and 36 deletions
--- a/docs/usage/common-options.rst.inc
+++ b/docs/usage/common-options.rst.inc
@ -24,5 +24,7 @@
        | set umask to M (local and remote, default: 0077)
    ``--remote-path PATH``
        | set remote path to executable (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)
--- a/docs/usage/create.rst.inc
+++ b/docs/usage/create.rst.inc
@ -61,18 +61,9 @@ Archive options
    ``--chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE``
        | specify the chunker parameters. default: 19,23,21,4095
    ``-C COMPRESSION``, ``--compression COMPRESSION``
-        | select compression algorithm (and level):
-        | none == no compression (default),
-        | auto,C[,L] == built-in heuristic (try with lz4 whether the data is
-        |               compressible) decides between none or C[,L] - with C[,L]
-        |               being any valid compression algorithm (and optional level),
-        | lz4 == lz4,
-        | zlib == zlib (default level 6),
-        | zlib,0 .. zlib,9 == zlib (with level 0..9),
-        | lzma == lzma (default level 6),
-        | lzma,0 .. lzma,9 == lzma (with level 0..9).
+        | select compression algorithm, see the output of the "borg help compression" command for details.
    ``--compression-from COMPRESSIONCONFIG``
-        | read compression patterns from COMPRESSIONCONFIG, one per line
+        | read compression patterns from COMPRESSIONCONFIG, see the output of the "borg help compression" command for details.

 Description
 ~~~~~~~~~~~
--- a/docs/usage/delete.rst.inc
+++ b/docs/usage/delete.rst.inc
@ -27,6 +27,16 @@ optional arguments
 `Common options`_
    |

+filters
+    ``-P``, ``--prefix``
+        | only consider archive names starting with this prefix
+    ``--sort-by``
+        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+    ``--first N``
+        | consider first N archives after other filters were applied
+    ``--last N``
+        | consider last N archives after other filters were applied
+
 Description
 ~~~~~~~~~~~

--- a/docs/usage/help.rst.inc
+++ b/docs/usage/help.rst.inc
@ -99,40 +99,134 @@ borg help placeholders
 ~~~~~~~~~~~~~~~~~~~~~~


- Repository (or Archive) URLs, --prefix and --remote-path values support these
- placeholders:
+Repository (or Archive) URLs, --prefix and --remote-path values support these
+placeholders:

- {hostname}
+{hostname}

-     The (short) hostname of the machine.
+    The (short) hostname of the machine.

- {fqdn}
+{fqdn}

-     The full name of the machine.
+    The full name of the machine.

- {now}
+{now}

-     The current local date and time.
+    The current local date and time, by default in ISO-8601 format.
+    You can also supply your own `format string <https://docs.python.org/3.4/library/datetime.html#strftime-and-strptime-behavior>`_, e.g. {now:%Y-%m-%d_%H:%M:%S}

- {utcnow}
+{utcnow}

-     The current UTC date and time.
+    The current UTC date and time, by default in ISO-8601 format.
+    You can also supply your own `format string <https://docs.python.org/3.4/library/datetime.html#strftime-and-strptime-behavior>`_, e.g. {utcnow:%Y-%m-%d_%H:%M:%S}

- {user}
+{user}

-     The user name (or UID, if no name is available) of the user running borg.
+    The user name (or UID, if no name is available) of the user running borg.

- {pid}
+{pid}

-     The current process ID.
+    The current process ID.

- {borgversion}
+{borgversion}

-     The version of borg.
+    The version of borg.

 Examples::

-     borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
-     borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
-     borg prune --prefix '{hostname}-' ...
+    borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
+    borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
+    borg prune --prefix '{hostname}-' ...
+
+.. _borg_compression:
+
+borg help compression
+~~~~~~~~~~~~~~~~~~~~~
+
+
+Compression is off by default, if you want some, you have to specify what you want.
+
+Valid compression specifiers are:
+
+none
+
+    Do not compress. (default)
+
+lz4
+
+    Use lz4 compression. High speed, low compression.
+
+zlib[,L]
+
+    Use zlib ("gz") compression. Medium speed, medium compression.
+    If you do not explicitely give the compression level L (ranging from 0
+    to 9), it will use level 6.
+    Giving level 0 (means "no compression", but still has zlib protocol
+    overhead) is usually pointless, you better use "none" compression.
+
+lzma[,L]
+
+    Use lzma ("xz") compression. Low speed, high compression.
+    If you do not explicitely give the compression level L (ranging from 0
+    to 9), it will use level 6.
+    Giving levels above 6 is pointless and counterproductive because it does
+    not compress better due to the buffer size used by borg - but it wastes
+    lots of CPU cycles and RAM.
+
+auto,C[,L]
+
+    Use a built-in heuristic to decide per chunk whether to compress or not.
+    The heuristic tries with lz4 whether the data is compressible.
+    For incompressible data, it will not use compression (uses "none").
+    For compressible data, it uses the given C[,L] compression - with C[,L]
+    being any valid compression specifier.
+
+The decision about which compression to use is done by borg like this:
+
+1. find a compression specifier (per file):
+   match the path/filename against all patterns in all --compression-from
+   files (if any). If a pattern matches, use the compression spec given for
+   that pattern. If no pattern matches (and also if you do not give any
+   --compression-from option), default to the compression spec given by
+   --compression. See docs/misc/compression.conf for an example config.
+
+2. if the found compression spec is not "auto", the decision is taken:
+   use the found compression spec.
+
+3. if the found compression spec is "auto", test compressibility of each
+   chunk using lz4.
+   If it is compressible, use the C,[L] compression spec given within the
+   "auto" specifier. If it is not compressible, use no compression.
+
+Examples::
+
+    borg create --compression lz4 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
+    borg create --compression-from compression.conf --compression auto,lzma ...
+
+compression.conf has entries like::
+
+    # example config file for --compression-from option
+    #
+    # Format of non-comment / non-empty lines:
+    # <compression-spec>:<path/filename pattern>
+    # compression-spec is same format as for --compression option
+    # path/filename pattern is same format as for --exclude option
+    none:*.gz
+    none:*.zip
+    none:*.mp3
+    none:*.ogg
+
+General remarks:
+
+It is no problem to mix different compression methods in one repo,
+deduplication is done on the source data chunks (not on the compressed
+or encrypted data).
+
+If some specific chunk was once compressed and stored into the repo, creating
+another backup that also uses this chunk will not change the stored chunk.
+So if you use different compression specs for the backups, whichever stores a
+chunk first determines its compression. See also borg recreate.

--- a/docs/usage/info.rst.inc
+++ b/docs/usage/info.rst.inc
@ -15,13 +15,26 @@ positional arguments
 `Common options`_
    |

+filters
+    ``-P``, ``--prefix``
+        | only consider archive names starting with this prefix
+    ``--sort-by``
+        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+    ``--first N``
+        | consider first N archives after other filters were applied
+    ``--last N``
+        | consider last N archives after other filters were applied
+
 Description
 ~~~~~~~~~~~

 This command displays detailed information about the specified archive or repository.

-The "This archive" line refers exclusively to the given archive:
-"Deduplicated size" is the size of the unique chunks stored only for the
-given archive.
+Please note that the deduplicated sizes of the individual archives do not add
+up to the deduplicated size of the repository ("all archives"), because the two
+are meaning different things:

-The "All archives" line shows global statistics (all chunks).
+This archive / deduplicated size = amount of data stored ONLY for this archive
+                                 = unique chunks of this archive.
+All archives / deduplicated size = amount of data stored in the repo
+                                 = all chunks in the repository.
--- a/docs/usage/key_export.rst.inc
+++ b/docs/usage/key_export.rst.inc
@ -0,0 +1,43 @@
+.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
+
+.. _borg_key_export:
+
+borg key export
+---------------
+::
+
+    borg key export <options> REPOSITORY PATH
+
+positional arguments
+    REPOSITORY
+
+    PATH
+        where to store the backup
+
+optional arguments
+    ``--paper``
+        | Create an export suitable for printing and later type-in
+
+`Common options`_
+    |
+
+Description
+~~~~~~~~~~~
+
+If repository encryption is used, the repository is inaccessible
+without the key. This command allows to backup this essential key.
+
+There are two backup formats. The normal backup format is suitable for
+digital storage as a file. The ``--paper`` backup format is optimized
+for printing and typing in while importing, with per line checks to
+reduce problems with manual input.
+
+For repositories using keyfile encryption the key is saved locally
+on the system that is capable of doing backups. To guard against loss
+of this key, the key needs to be backed up independently of the main
+data backup.
+
+For repositories using the repokey encryption the key is saved in the
+repository in the config file. A backup is thus not strictly needed,
+but guards against the repository becoming inaccessible if the file
+is damaged for some reason.
--- a/docs/usage/key_import.rst.inc
+++ b/docs/usage/key_import.rst.inc
@ -0,0 +1,32 @@
+.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
+
+.. _borg_key_import:
+
+borg key import
+---------------
+::
+
+    borg key import <options> REPOSITORY PATH
+
+positional arguments
+    REPOSITORY
+
+    PATH
+        path to the backup
+
+optional arguments
+    ``--paper``
+        | interactively import from a backup done with --paper
+
+`Common options`_
+    |
+
+Description
+~~~~~~~~~~~
+
+This command allows to restore 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.
--- a/docs/usage/list.rst.inc
+++ b/docs/usage/list.rst.inc
@ -20,8 +20,6 @@ optional arguments
    ``--format``, ``--list-format``
        | specify format for file listing
        |                                 (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
-    ``-P``, ``--prefix``
-        | only consider archive names starting with this prefix
    ``-e PATTERN``, ``--exclude PATTERN``
        | exclude paths matching PATTERN
    ``--exclude-from EXCLUDEFILE``
@ -30,6 +28,16 @@ optional arguments
 `Common options`_
    |

+filters
+    ``-P``, ``--prefix``
+        | only consider archive names starting with this prefix
+    ``--sort-by``
+        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+    ``--first N``
+        | consider first N archives after other filters were applied
+    ``--last N``
+        | consider last N archives after other filters were applied
+
 Description
 ~~~~~~~~~~~