From b5ff043ac1a05d25755e5dcddaf49abb6364732a Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Mon, 2 Jan 2023 23:50:50 +0100 Subject: [PATCH] build_usage --- docs/usage/check.rst.inc | 3 -- docs/usage/create.rst.inc | 8 ++--- docs/usage/delete.rst.inc | 3 -- docs/usage/list.rst.inc | 65 +++++++++++++++++++-------------------- docs/usage/prune.rst.inc | 3 -- docs/usage/rlist.rst.inc | 60 +++++++++++++++++------------------- 6 files changed, 65 insertions(+), 77 deletions(-) diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc index beb9dc367..a12c68f64 100644 --- a/docs/usage/check.rst.inc +++ b/docs/usage/check.rst.inc @@ -23,8 +23,6 @@ borg check +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ | | ``--repair`` | attempt to repair any inconsistencies found | +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--save-space`` | work slower, but using less space | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ | | ``--max-duration SECONDS`` | do only a partial repo check for max. SECONDS seconds (Default: unlimited) | +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ | .. class:: borg-common-opt-ref | @@ -59,7 +57,6 @@ borg check --archives-only only perform archives checks --verify-data perform cryptographic archive data integrity verification (conflicts with ``--repository-only``) --repair attempt to repair any inconsistencies found - --save-space work slower, but using less space --max-duration SECONDS do only a partial repo check for max. SECONDS seconds (Default: unlimited) diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index 41232a8e1..b7d649a1a 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -43,7 +43,7 @@ borg create +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--content-from-command`` | interpret PATH as command and store its stdout. See also section Reading from stdin below. | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--paths-from-stdin`` | read DELIM-separated list of paths to back up from stdin. Will not recurse into directories. | + | | ``--paths-from-stdin`` | read DELIM-separated list of paths to back up from stdin. Will not recurse into directories. | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--paths-from-command`` | interpret PATH as command and treat its output as ``--paths-from-stdin`` | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -241,9 +241,9 @@ creation of a new archive to ensure fast operation. This is because the file cac is used to determine changed files quickly uses absolute filenames. If this is not possible, consider creating a bind mount to a stable location. -The ``--progress`` option shows (from left to right) Original, Compressed and Deduplicated -(O, C and D, respectively), then the Number of files (N) processed so far, followed by -the currently processed path. +The ``--progress`` option shows (from left to right) Original and (uncompressed) +deduplicated size (O and U respectively), then the Number of files (N) processed so far, +followed by the currently processed path. When using ``--stats``, you will get some statistics about how much data was added - the "This Archive" deduplicated size there is most interesting as that is diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc index 63413584e..c28e746af 100644 --- a/docs/usage/delete.rst.inc +++ b/docs/usage/delete.rst.inc @@ -27,8 +27,6 @@ borg delete +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ | | ``--force`` | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. | +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--save-space`` | work slower, but using less space | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ | .. class:: borg-common-opt-ref | @@ -65,7 +63,6 @@ borg delete -s, --stats print statistics for the deleted archive --cache-only delete only the local cache for the given repository --force force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. - --save-space work slower, but using less space -c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800) diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc index 422d95209..38220c81a 100644 --- a/docs/usage/list.rst.inc +++ b/docs/usage/list.rst.inc @@ -12,35 +12,35 @@ borg list .. class:: borg-options-table - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **positional arguments** | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``NAME`` | specify the archive name | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``PATH`` | paths to list; patterns are supported | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **options** | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--short`` | only print file/directory names, nothing else | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--format FORMAT`` | specify format for file listing (default: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}") | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--json-lines`` | Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **Exclusion options** | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **positional arguments** | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``NAME`` | specify the archive name | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``PATH`` | paths to list; patterns are supported | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **options** | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--short`` | only print file/directory names, nothing else | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--format FORMAT`` | specify format for file listing (default: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}") | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--json-lines`` | Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Exclusion options** | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. raw:: html @@ -61,7 +61,7 @@ borg list options --short only print file/directory names, nothing else --format FORMAT specify format for file listing (default: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}") - --json-lines Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. + --json-lines Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. :ref:`common_options` @@ -106,7 +106,7 @@ The following keys are always available: - NEWLINE: OS dependent line separator - NL: alias of NEWLINE -- NUL: NUL character for creating print0 / xargs -0 like output, see barchive and bpath keys below +- NUL: NUL character for creating print0 / xargs -0 like output - SPACE - TAB - CR @@ -120,8 +120,7 @@ Keys available only when listing files in an archive: - 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 +- path: file path - source: link target for symlinks (identical to linktarget) - linktarget - hlid: hard link identity (same if hardlinking same fs object) diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index b56d3e9f9..203b327f4 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -39,8 +39,6 @@ borg prune +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ | | ``-y``, ``--keep-yearly`` | number of yearly archives to keep | +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``--save-space`` | work slower, but using less space | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ | .. class:: borg-common-opt-ref | @@ -77,7 +75,6 @@ borg prune -w, --keep-weekly number of weekly archives to keep -m, --keep-monthly number of monthly archives to keep -y, --keep-yearly number of yearly archives to keep - --save-space work slower, but using less space -c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800) diff --git a/docs/usage/rlist.rst.inc b/docs/usage/rlist.rst.inc index 9ded180d8..5455e5453 100644 --- a/docs/usage/rlist.rst.inc +++ b/docs/usage/rlist.rst.inc @@ -12,31 +12,31 @@ borg rlist .. class:: borg-options-table - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **options** | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--consider-checkpoints`` | Show checkpoint archives in the repository contents list (default: hidden). | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--short`` | only print the archive names, nothing else | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--format FORMAT`` | specify format for archive listing (default: "{archive:<36} {time} [{id}]{NL}") | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--json`` | Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available. | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **Archive filters** — Archive filters can be applied to repository targets. | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--sort-by KEYS`` | 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 | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **options** | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--consider-checkpoints`` | Show checkpoint archives in the repository contents list (default: hidden). | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--short`` | only print the archive names, nothing else | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--format FORMAT`` | specify format for archive listing (default: "{archive:<36} {time} [{id}]{NL}") | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--json`` | Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Archive filters** — Archive filters can be applied to repository targets. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--sort-by KEYS`` | 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 | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. raw:: html @@ -54,7 +54,7 @@ borg rlist --consider-checkpoints Show checkpoint archives in the repository contents list (default: hidden). --short only print the archive names, nothing else --format FORMAT specify format for archive listing (default: "{archive:<36} {time} [{id}]{NL}") - --json Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available. + --json Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. :ref:`common_options` @@ -99,7 +99,7 @@ The following keys are always available: - NEWLINE: OS dependent line separator - NL: alias of NEWLINE -- NUL: NUL character for creating print0 / xargs -0 like output, see barchive and bpath keys below +- NUL: NUL character for creating print0 / xargs -0 like output - SPACE - TAB - CR @@ -107,11 +107,9 @@ The following keys are always available: Keys available only when listing archives in a repository: -- archive: archive name interpreted as text (might be missing non-text characters, see barchive) +- archive: archive name - name: alias of "archive" -- barchive: verbatim archive name, can contain any character except NUL -- comment: archive comment interpreted as text (might be missing non-text characters, see bcomment) -- bcomment: verbatim archive comment, can contain any character except NUL +- comment: archive comment - id: internal ID of the archive - start: time (start) of creation of the archive