From b7a6ac94c3caf90dad6a4d295b2750d600ab6b1f Mon Sep 17 00:00:00 2001 From: Marian Beermann Date: Wed, 17 May 2017 11:52:48 +0200 Subject: [PATCH] docs: ran build_man, build_usage --- docs/man/borg-benchmark-crud.1 | 101 ++++++++++++++++++++++ docs/man/borg-benchmark.1 | 47 ++++++++++ docs/man/borg-break-lock.1 | 4 +- docs/man/borg-change-passphrase.1 | 4 +- docs/man/borg-check.1 | 7 +- docs/man/borg-common.1 | 8 +- docs/man/borg-compression.1 | 2 +- docs/man/borg-create.1 | 11 +-- docs/man/borg-delete.1 | 7 +- docs/man/borg-diff.1 | 4 +- docs/man/borg-export-tar.1 | 4 +- docs/man/borg-extract.1 | 10 +-- docs/man/borg-info.1 | 4 +- docs/man/borg-init.1 | 12 +-- docs/man/borg-key-change-passphrase.1 | 4 +- docs/man/borg-key-export.1 | 4 +- docs/man/borg-key-import.1 | 4 +- docs/man/borg-key-migrate-to-repokey.1 | 4 +- docs/man/borg-key.1 | 10 +-- docs/man/borg-list.1 | 9 +- docs/man/borg-mount.1 | 4 +- docs/man/borg-patterns.1 | 2 +- docs/man/borg-placeholders.1 | 2 +- docs/man/borg-prune.1 | 7 +- docs/man/borg-recreate.1 | 7 +- docs/man/borg-rename.1 | 4 +- docs/man/borg-serve.1 | 4 +- docs/man/borg-umount.1 | 4 +- docs/man/borg-upgrade.1 | 7 +- docs/man/borg-with-lock.1 | 4 +- docs/man/borg.1 | 2 +- docs/usage/benchmark_crud.rst.inc | 59 +++++++++++++ docs/usage/break-lock.rst.inc | 2 +- docs/usage/change-passphrase.rst.inc | 2 +- docs/usage/check.rst.inc | 4 +- docs/usage/common-options.rst.inc | 6 +- docs/usage/create.rst.inc | 8 +- docs/usage/delete.rst.inc | 4 +- docs/usage/diff.rst.inc | 2 +- docs/usage/export-tar.rst.inc | 2 +- docs/usage/extract.rst.inc | 9 +- docs/usage/info.rst.inc | 2 +- docs/usage/init.rst.inc | 10 +-- docs/usage/key_change-passphrase.rst.inc | 2 +- docs/usage/key_export.rst.inc | 2 +- docs/usage/key_import.rst.inc | 2 +- docs/usage/key_migrate-to-repokey.rst.inc | 2 +- docs/usage/list.rst.inc | 6 +- docs/usage/mount.rst.inc | 2 +- docs/usage/prune.rst.inc | 4 +- docs/usage/recreate.rst.inc | 4 +- docs/usage/rename.rst.inc | 2 +- docs/usage/serve.rst.inc | 2 +- docs/usage/umount.rst.inc | 2 +- docs/usage/upgrade.rst.inc | 4 +- docs/usage/with-lock.rst.inc | 2 +- 56 files changed, 327 insertions(+), 126 deletions(-) create mode 100644 docs/man/borg-benchmark-crud.1 create mode 100644 docs/man/borg-benchmark.1 create mode 100644 docs/usage/benchmark_crud.rst.inc diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 new file mode 100644 index 000000000..ed1a5e1e0 --- /dev/null +++ b/docs/man/borg-benchmark-crud.1 @@ -0,0 +1,101 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-BENCHMARK-CRUD 1 "2017-05-17" "" "borg backup tool" +.SH NAME +borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +borg [common options] benchmark crud REPO PATH +.SH DESCRIPTION +.sp +This command benchmarks borg CRUD (create, read, update, delete) operations. +.sp +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. +.sp +Make sure you have free space there, you\(aqll need about 1GB each (+ overhead). +.sp +If your repository is encrypted and borg needs a passphrase to unlock the key, use: +.sp +BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH +.sp +Measurements are done with different input file sizes and counts. +The file contents are very artificial (either all zero or all random), +thus the measurement results do not necessarily reflect performance with real data. +Also, due to the kind of content used, no compression is used in these benchmarks. +.INDENT 0.0 +.TP +.B C\- == borg create (1st archive creation, no compression, do not use files cache) +C\-Z\- == all\-zero files. full dedup, this is primarily measuring reader/chunker/hasher. +C\-R\- == random files. no dedup, measuring throughput through all processing stages. +.TP +.B 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 +.IP "System Message: ERROR/3 (docs/virtmanpage.rst:, line 56)" +Unexpected indentation. +.INDENT 7.0 +.INDENT 3.5 +stages, except writing to disk. +.UNINDENT +.UNINDENT +.TP +.B 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. +U\-Z\- == needs to check the 2 all\-zero chunks\(aq existence in the repo. +U\-R\- == needs to check existence of a lot of different chunks in the repo. +.TP +.B D\- == borg delete archive (delete last remaining archive, measure deletion + compaction) +D\-Z\- == few chunks to delete / few segments to compact/remove. +D\-R\- == many chunks to delete / many segments to compact/remove. +.UNINDENT +.sp +Please note that there might be quite some variance in these measurements. +Try multiple measurements and having a otherwise idle machine (and network, if you use it). +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B REPO +repo to use for benchmark (must exist) +.TP +.B PATH +path were to create benchmark input data +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 new file mode 100644 index 000000000..0f46eb8a6 --- /dev/null +++ b/docs/man/borg-benchmark.1 @@ -0,0 +1,47 @@ +.\" Man page generated from reStructuredText. +. +.TH BORG-BENCHMARK 1 "2017-05-17" "" "borg backup tool" +.SH NAME +borg-benchmark \- benchmark command +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.nf +borg [common options] benchmark crud ... +.fi +.sp +.SH DESCRIPTION +.sp +These commands do various benchmarks. +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP, \fIborg\-benchmark\-crud(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index c83b2d6d4..a7275b0c0 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BREAK-LOCK 1 "2017-04-29" "" "borg backup tool" +.TH BORG-BREAK-LOCK 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg break\-lock REPOSITORY +borg [common options] break\-lock REPOSITORY .SH DESCRIPTION .sp This command breaks the repository and cache locks. diff --git a/docs/man/borg-change-passphrase.1 b/docs/man/borg-change-passphrase.1 index 1a73f339c..a4649a71e 100644 --- a/docs/man/borg-change-passphrase.1 +++ b/docs/man/borg-change-passphrase.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CHANGE-PASSPHRASE 1 "2017-04-29" "" "borg backup tool" +.TH BORG-CHANGE-PASSPHRASE 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-change-passphrase \- Change repository key file passphrase . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg change\-passphrase REPOSITORY +borg [common options] change\-passphrase REPOSITORY .SH DESCRIPTION .sp The key files used for repository encryption are optionally passphrase diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index ea4ef558a..cb694cac1 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CHECK 1 "2017-04-29" "" "borg backup tool" +.TH BORG-CHECK 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-check \- Check repository consistency . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg check REPOSITORY_OR_ARCHIVE +borg [common options] check REPOSITORY_OR_ARCHIVE .SH DESCRIPTION .sp The check command verifies the consistency of a repository and the corresponding archives. @@ -120,9 +120,6 @@ attempt to repair any inconsistencies found .TP .B \-\-save\-space work slower, but using less space -.TP -.B \-p\fP,\fB \-\-progress -show progress display while checking .UNINDENT .SS filters .INDENT 0.0 diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index 3ca2d1f9c..223fd33a7 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-COMMON 1 "2017-04-29" "" "borg backup tool" +.TH BORG-COMMON 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-common \- Common options of Borg commands . @@ -54,6 +54,9 @@ enable debug output, work on log level DEBUG .BI \-\-debug\-topic \ TOPIC enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug. if TOPIC is not fully qualified. .TP +.B \-p\fP,\fB \-\-progress +show progress information +.TP .B \-\-log\-json Output one JSON object per log line instead of formatted text. .TP @@ -80,6 +83,9 @@ set remote network upload rate limit in kiByte/s (default: 0=unlimited) .TP .B \-\-consider\-part\-files treat part files like normal files (e.g. to list/extract them) +.TP +.BI \-\-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". .UNINDENT .SH SEE ALSO .sp diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index da3c8487d..9e176f224 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-COMPRESSION 1 "2017-04-29" "" "borg backup tool" +.TH BORG-COMPRESSION 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-compression \- Details regarding compression . diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index 8196befaf..0cae7ca0c 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CREATE 1 "2017-04-29" "" "borg backup tool" +.TH BORG-CREATE 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-create \- Create new archive . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg create ARCHIVE PATH +borg [common options] create ARCHIVE PATH .SH DESCRIPTION .sp This command creates a backup archive containing all files found while recursively @@ -63,6 +63,10 @@ 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. .sp +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. +.sp See the output of the "borg help patterns" command for more help on exclude patterns. See the output of the "borg help placeholders" command for more help on placeholders. .SH OPTIONS @@ -86,9 +90,6 @@ do not create a backup archive .B \-s\fP,\fB \-\-stats print statistics for the created archive .TP -.B \-p\fP,\fB \-\-progress -show progress display while creating the archive, showing Original, Compressed and Deduplicated sizes, followed by the Number of files seen and the path being processed, default: False -.TP .B \-\-list output verbose list of items (files, dirs, ...) .TP diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index c911ec823..c7c96aa15 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-DELETE 1 "2017-04-29" "" "borg backup tool" +.TH BORG-DELETE 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-delete \- Delete an existing repository or archives . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg delete TARGET +borg [common options] delete TARGET .SH DESCRIPTION .sp This command deletes an archive from the repository or the complete repository. @@ -50,9 +50,6 @@ archive or repository to delete .SS optional arguments .INDENT 0.0 .TP -.B \-p\fP,\fB \-\-progress -show progress display while deleting a single archive -.TP .B \-s\fP,\fB \-\-stats print statistics for the deleted archive .TP diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index c01f70f4c..b69a792be 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-DIFF 1 "2017-04-29" "" "borg backup tool" +.TH BORG-DIFF 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-diff \- Diff contents of two archives . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg diff REPO_ARCHIVE1 ARCHIVE2 PATH +borg [common options] diff REPO_ARCHIVE1 ARCHIVE2 PATH .SH DESCRIPTION .sp This command finds differences (file contents, user/group/mode) between archives. diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index ecbefc142..73cd98150 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-EXPORT-TAR 1 "2017-05-16" "" "borg backup tool" +.TH BORG-EXPORT-TAR 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-export-tar \- Export archive contents as a tarball . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg export\-tar ARCHIVE FILE PATH +borg [common options] export\-tar ARCHIVE FILE PATH .SH DESCRIPTION .sp This command creates a tarball from an archive. diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index 9e8d113d3..dbe9c3537 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-EXTRACT 1 "2017-04-29" "" "borg backup tool" +.TH BORG-EXTRACT 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-extract \- Extract archive contents . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg extract ARCHIVE PATH +borg [common options] extract ARCHIVE PATH .SH DESCRIPTION .sp This command extracts the contents of an archive. By default the entire @@ -45,6 +45,9 @@ See the output of the "borg help patterns" command for more help on exclude patt By using \fB\-\-dry\-run\fP, you can do all extraction steps except actually writing the output data: reading metadata and data chunks from the repo, checking the hash/hmac, decrypting, decompressing. +.sp +\fB\-\-progress\fP can be slower than no progress display, since it makes one additional +pass over the archive metadata. .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. @@ -60,9 +63,6 @@ paths to extract; patterns are supported .SS optional arguments .INDENT 0.0 .TP -.B \-p\fP,\fB \-\-progress -show progress while extracting (may be slower) -.TP .B \-\-list output verbose list of items (files, dirs, ...) .TP diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index cc165d6d4..f235a866c 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-INFO 1 "2017-04-29" "" "borg backup tool" +.TH BORG-INFO 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-info \- Show archive details such as disk space used . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg info REPOSITORY_OR_ARCHIVE +borg [common options] info REPOSITORY_OR_ARCHIVE .SH DESCRIPTION .sp This command displays detailed information about the specified archive or repository. diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1 index c5eb14dc6..d0e1f5ed7 100644 --- a/docs/man/borg-init.1 +++ b/docs/man/borg-init.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-INIT 1 "2017-04-29" "" "borg backup tool" +.TH BORG-INIT 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-init \- Initialize an empty repository . @@ -32,13 +32,13 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg init REPOSITORY +borg [common options] init REPOSITORY .SH DESCRIPTION .sp This command initializes an empty repository. A repository is a filesystem directory containing the deduplicated data from zero or more archives. .sp -Encryption can be enabled at repository init time. +Encryption can be enabled at repository init time. It cannot be changed later. .sp It is not recommended to work without encryption. Repository encryption protects you e.g. against the case that an attacker has access to your backup repository. @@ -94,8 +94,8 @@ These modes are new and \fInot\fP compatible with borg 1.0.x. .sp \fIauthenticated\fP mode uses no encryption, but authenticates repository contents through the same keyed BLAKE2b\-256 hash as the other blake2 modes (it uses it -as chunk ID hash). The key is stored like repokey. -This mode is new and not compatible with borg 1.0.x. +as the chunk ID hash). The key is stored like repokey. +This mode is new and \fInot\fP compatible with borg 1.0.x. .sp \fInone\fP mode uses no encryption and no authentication. It uses sha256 as chunk ID hash. Not recommended, rather consider using an authenticated or @@ -123,7 +123,7 @@ repository to create .INDENT 0.0 .TP .B \-e\fP,\fB \-\-encryption -select encryption key mode +select encryption key mode \fB(required)\fP .TP .B \-a\fP,\fB \-\-append\-only create an append\-only mode repository diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 6903cf4a1..6457d3a7f 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-04-29" "" "borg backup tool" +.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-key-change-passphrase \- Change repository key file passphrase . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg key change\-passphrase REPOSITORY +borg [common options] key change\-passphrase REPOSITORY .SH DESCRIPTION .sp The key files used for repository encryption are optionally passphrase diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index 6210505f8..9736bba3e 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-EXPORT 1 "2017-04-29" "" "borg backup tool" +.TH BORG-KEY-EXPORT 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-key-export \- Export the repository key for backup . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg key export REPOSITORY PATH +borg [common options] key export REPOSITORY PATH .SH DESCRIPTION .sp If repository encryption is used, the repository is inaccessible diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index a6c0abef1..2ab5af4c2 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-IMPORT 1 "2017-04-29" "" "borg backup tool" +.TH BORG-KEY-IMPORT 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-key-import \- Import the repository key from backup . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg key import REPOSITORY PATH +borg [common options] key import REPOSITORY PATH .SH DESCRIPTION .sp This command allows to restore a key previously backed up with the diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1 index ea3eed034..178429792 100644 --- a/docs/man/borg-key-migrate-to-repokey.1 +++ b/docs/man/borg-key-migrate-to-repokey.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-04-29" "" "borg backup tool" +.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-key-migrate-to-repokey \- Migrate passphrase -> repokey . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg key migrate\-to\-repokey REPOSITORY +borg [common options] key migrate\-to\-repokey REPOSITORY .SH DESCRIPTION .sp This command migrates a repository from passphrase mode (removed in Borg 1.0) diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index b05452e2e..e61f8e30a 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY 1 "2017-04-29" "" "borg backup tool" +.TH BORG-KEY 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-key \- Manage a keyfile or repokey of a repository . @@ -32,10 +32,10 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .nf -borg key export ... -borg key import ... -borg key change\-passphrase ... -borg key migrate\-to\-repokey ... +borg [common options] key export ... +borg [common options] key import ... +borg [common options] key change\-passphrase ... +borg [common options] key migrate\-to\-repokey ... .fi .sp .SH SEE ALSO diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index de919db38..66bcf1c17 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-LIST 1 "2017-04-29" "" "borg backup tool" +.TH BORG-LIST 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-list \- List archive or repository contents . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg list REPOSITORY_OR_ARCHIVE PATH +borg [common options] list REPOSITORY_OR_ARCHIVE PATH .SH DESCRIPTION .sp This command lists the contents of a repository or an archive. @@ -61,7 +61,10 @@ specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}") .TP .B \-\-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 "bpath" key is therefore not available. +Only valid for listing repository contents. 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. +.TP +.B \-\-json\-lines +Only valid for listing archive contents. 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. .UNINDENT .SS filters .INDENT 0.0 diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index 89a3ee241..298967af1 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-MOUNT 1 "2017-04-29" "" "borg backup tool" +.TH BORG-MOUNT 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-mount \- Mount archive or an entire repository as a FUSE filesystem . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg mount REPOSITORY_OR_ARCHIVE MOUNTPOINT +borg [common options] mount REPOSITORY_OR_ARCHIVE MOUNTPOINT .SH DESCRIPTION .sp This command mounts an archive as a FUSE filesystem. This can be useful for diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index e2d12055e..0c329d0d7 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PATTERNS 1 "2017-04-29" "" "borg backup tool" +.TH BORG-PATTERNS 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns . diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index c906f8dc2..72ae10462 100644 --- a/docs/man/borg-placeholders.1 +++ b/docs/man/borg-placeholders.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PLACEHOLDERS 1 "2017-04-29" "" "borg backup tool" +.TH BORG-PLACEHOLDERS 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-placeholders \- Details regarding placeholders . diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index 550312281..dcb817a6e 100644 --- a/docs/man/borg-prune.1 +++ b/docs/man/borg-prune.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PRUNE 1 "2017-04-29" "" "borg backup tool" +.TH BORG-PRUNE 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-prune \- Prune repository archives according to specified rules . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg prune REPOSITORY +borg [common options] prune REPOSITORY .SH DESCRIPTION .sp The prune command prunes a repository by deleting all archives not matching @@ -91,9 +91,6 @@ do not change repository .B \-\-force force pruning of corrupted archives .TP -.B \-p\fP,\fB \-\-progress -show progress display while deleting archives -.TP .B \-s\fP,\fB \-\-stats print statistics for the deleted archive .TP diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index 8f2bf554e..0e22a3207 100644 --- a/docs/man/borg-recreate.1 +++ b/docs/man/borg-recreate.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-RECREATE 1 "2017-04-29" "" "borg backup tool" +.TH BORG-RECREATE 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-recreate \- Re-create archives . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg recreate REPOSITORY_OR_ARCHIVE PATH +borg [common options] recreate REPOSITORY_OR_ARCHIVE PATH .SH DESCRIPTION .sp Recreate the contents of existing archives. @@ -92,9 +92,6 @@ output verbose list of items (files, dirs, ...) .BI \-\-filter \ STATUSCHARS only display items with the given status characters .TP -.B \-p\fP,\fB \-\-progress -show progress display while recreating archives -.TP .B \-n\fP,\fB \-\-dry\-run do not change anything .TP diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index 6a85b8d1d..9c075314f 100644 --- a/docs/man/borg-rename.1 +++ b/docs/man/borg-rename.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-RENAME 1 "2017-04-29" "" "borg backup tool" +.TH BORG-RENAME 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-rename \- Rename an existing archive . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg rename ARCHIVE NEWNAME +borg [common options] rename ARCHIVE NEWNAME .SH DESCRIPTION .sp This command renames an archive in the repository. diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 index 90957e8b3..798d6486d 100644 --- a/docs/man/borg-serve.1 +++ b/docs/man/borg-serve.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-SERVE 1 "2017-04-29" "" "borg backup tool" +.TH BORG-SERVE 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-serve \- Start in server mode. This command is usually not used manually. . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg serve +borg [common options] serve .SH DESCRIPTION .sp This command starts a repository server process. This command is usually not used manually. diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index 98be9f533..26a3c1f6c 100644 --- a/docs/man/borg-umount.1 +++ b/docs/man/borg-umount.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-UMOUNT 1 "2017-04-29" "" "borg backup tool" +.TH BORG-UMOUNT 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-umount \- un-mount the FUSE filesystem . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg umount MOUNTPOINT +borg [common options] umount MOUNTPOINT .SH DESCRIPTION .sp This command un\-mounts a FUSE filesystem that was mounted with \fBborg mount\fP\&. diff --git a/docs/man/borg-upgrade.1 b/docs/man/borg-upgrade.1 index b91f693d7..ed9e419d3 100644 --- a/docs/man/borg-upgrade.1 +++ b/docs/man/borg-upgrade.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-UPGRADE 1 "2017-04-29" "" "borg backup tool" +.TH BORG-UPGRADE 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-upgrade \- upgrade a repository from a previous version . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg upgrade REPOSITORY +borg [common options] upgrade REPOSITORY .SH DESCRIPTION .sp Upgrade an existing, local Borg repository. @@ -129,9 +129,6 @@ path to the repository to be upgraded .SS optional arguments .INDENT 0.0 .TP -.B \-p\fP,\fB \-\-progress -show progress display while upgrading the repository -.TP .B \-n\fP,\fB \-\-dry\-run do not change repository .TP diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index 6fe30706c..4099a9110 100644 --- a/docs/man/borg-with-lock.1 +++ b/docs/man/borg-with-lock.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-WITH-LOCK 1 "2017-04-29" "" "borg backup tool" +.TH BORG-WITH-LOCK 1 "2017-05-17" "" "borg backup tool" .SH NAME borg-with-lock \- run a user specified command with the repository lock held . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg with\-lock REPOSITORY COMMAND ARGS +borg [common options] with\-lock REPOSITORY COMMAND ARGS .SH DESCRIPTION .sp This command runs a user\-specified command while the repository lock is held. diff --git a/docs/man/borg.1 b/docs/man/borg.1 index 8e9247451..7e663cb33 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg [options] [arguments] +borg [common options] [options] [arguments] .SH DESCRIPTION .\" we don't include the README.rst here since we want to keep this terse. . diff --git a/docs/usage/benchmark_crud.rst.inc b/docs/usage/benchmark_crud.rst.inc new file mode 100644 index 000000000..d47e8d62b --- /dev/null +++ b/docs/usage/benchmark_crud.rst.inc @@ -0,0 +1,59 @@ +.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! + +.. _borg_benchmark_crud: + +borg benchmark crud +------------------- +:: + + borg [common options] benchmark crud REPO PATH + +positional arguments + REPO + repo to use for benchmark (must exist) + PATH + path were to create benchmark input data + +`Common options`_ + | + +Description +~~~~~~~~~~~ + +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. + +Make sure you have free space there, you'll need about 1GB each (+ overhead). + +If your repository is encrypted and borg needs a passphrase to unlock the key, use: + +BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH + +Measurements are done with different input file sizes and counts. +The file contents are very artificial (either all zero or all random), +thus the measurement results do not necessarily reflect performance with real data. +Also, due to the kind of content used, no compression is used in these benchmarks. + +C- == borg create (1st archive creation, no compression, do not use files cache) + C-Z- == all-zero files. full dedup, this is primarily measuring reader/chunker/hasher. + C-R- == random files. no dedup, measuring throughput through all processing stages. + +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. + +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. + U-Z- == needs to check the 2 all-zero chunks' existence in the repo. + U-R- == needs to check existence of a lot of different chunks in the repo. + +D- == borg delete archive (delete last remaining archive, measure deletion + compaction) + D-Z- == few chunks to delete / few segments to compact/remove. + D-R- == many chunks to delete / many segments to compact/remove. + +Please note that there might be quite some variance in these measurements. +Try multiple measurements and having a otherwise idle machine (and network, if you use it). \ No newline at end of file diff --git a/docs/usage/break-lock.rst.inc b/docs/usage/break-lock.rst.inc index 756b0d391..1b8e5915a 100644 --- a/docs/usage/break-lock.rst.inc +++ b/docs/usage/break-lock.rst.inc @@ -6,7 +6,7 @@ borg break-lock --------------- :: - borg break-lock REPOSITORY + borg [common options] break-lock REPOSITORY positional arguments REPOSITORY diff --git a/docs/usage/change-passphrase.rst.inc b/docs/usage/change-passphrase.rst.inc index 92a82c0db..b0a6c2bbb 100644 --- a/docs/usage/change-passphrase.rst.inc +++ b/docs/usage/change-passphrase.rst.inc @@ -6,7 +6,7 @@ borg change-passphrase ---------------------- :: - borg change-passphrase REPOSITORY + borg [common options] change-passphrase REPOSITORY positional arguments REPOSITORY diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc index 9958603ef..56bc42c8c 100644 --- a/docs/usage/check.rst.inc +++ b/docs/usage/check.rst.inc @@ -6,7 +6,7 @@ borg check ---------- :: - borg check REPOSITORY_OR_ARCHIVE + borg [common options] check REPOSITORY_OR_ARCHIVE positional arguments REPOSITORY_OR_ARCHIVE @@ -23,8 +23,6 @@ optional arguments | attempt to repair any inconsistencies found ``--save-space`` | work slower, but using less space - ``-p``, ``--progress`` - | show progress display while checking `Common options`_ | diff --git a/docs/usage/common-options.rst.inc b/docs/usage/common-options.rst.inc index 5dadfd52c..7299aa721 100644 --- a/docs/usage/common-options.rst.inc +++ b/docs/usage/common-options.rst.inc @@ -12,6 +12,8 @@ | 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. 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`` @@ -29,4 +31,6 @@ ``--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) \ No newline at end of file + | 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". \ No newline at end of file diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index d3aa2be11..6b7006cb3 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -6,7 +6,7 @@ borg create ----------- :: - borg create ARCHIVE PATH + borg [common options] create ARCHIVE PATH positional arguments ARCHIVE @@ -19,8 +19,6 @@ optional arguments | do not create a backup archive ``-s``, ``--stats`` | print statistics for the created archive - ``-p``, ``--progress`` - | show progress display while creating the archive, showing Original, Compressed and Deduplicated sizes, followed by the Number of files seen and the path being processed, default: False ``--list`` | output verbose list of items (files, dirs, ...) ``--filter STATUSCHARS`` @@ -104,6 +102,10 @@ 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. + See the output of the "borg help patterns" command for more help on exclude patterns. See the output of the "borg help placeholders" command for more help on placeholders. diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc index 5c1361a27..0977f0221 100644 --- a/docs/usage/delete.rst.inc +++ b/docs/usage/delete.rst.inc @@ -6,15 +6,13 @@ borg delete ----------- :: - borg delete TARGET + borg [common options] delete TARGET positional arguments TARGET archive or repository to delete optional arguments - ``-p``, ``--progress`` - | show progress display while deleting a single archive ``-s``, ``--stats`` | print statistics for the deleted archive ``-c``, ``--cache-only`` diff --git a/docs/usage/diff.rst.inc b/docs/usage/diff.rst.inc index 65d5afe67..0163c5dc1 100644 --- a/docs/usage/diff.rst.inc +++ b/docs/usage/diff.rst.inc @@ -6,7 +6,7 @@ borg diff --------- :: - borg diff REPO_ARCHIVE1 ARCHIVE2 PATH + borg [common options] diff REPO_ARCHIVE1 ARCHIVE2 PATH positional arguments REPO_ARCHIVE1 diff --git a/docs/usage/export-tar.rst.inc b/docs/usage/export-tar.rst.inc index af5fb5458..f2c4e03a0 100644 --- a/docs/usage/export-tar.rst.inc +++ b/docs/usage/export-tar.rst.inc @@ -6,7 +6,7 @@ borg export-tar --------------- :: - borg export-tar ARCHIVE FILE PATH + borg [common options] export-tar ARCHIVE FILE PATH positional arguments ARCHIVE diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc index 704c7c647..f5b2d4947 100644 --- a/docs/usage/extract.rst.inc +++ b/docs/usage/extract.rst.inc @@ -6,7 +6,7 @@ borg extract ------------ :: - borg extract ARCHIVE PATH + borg [common options] extract ARCHIVE PATH positional arguments ARCHIVE @@ -15,8 +15,6 @@ positional arguments paths to extract; patterns are supported optional arguments - ``-p``, ``--progress`` - | show progress while extracting (may be slower) ``--list`` | output verbose list of items (files, dirs, ...) ``-n``, ``--dry-run`` @@ -53,4 +51,7 @@ See the output of the "borg help patterns" command for more help on exclude patt By using ``--dry-run``, you can do all extraction steps except actually writing the output data: reading metadata and data chunks from the repo, checking the hash/hmac, -decrypting, decompressing. \ No newline at end of file +decrypting, decompressing. + +``--progress`` can be slower than no progress display, since it makes one additional +pass over the archive metadata. \ No newline at end of file diff --git a/docs/usage/info.rst.inc b/docs/usage/info.rst.inc index 4926b6407..0376329ab 100644 --- a/docs/usage/info.rst.inc +++ b/docs/usage/info.rst.inc @@ -6,7 +6,7 @@ borg info --------- :: - borg info REPOSITORY_OR_ARCHIVE + borg [common options] info REPOSITORY_OR_ARCHIVE positional arguments REPOSITORY_OR_ARCHIVE diff --git a/docs/usage/init.rst.inc b/docs/usage/init.rst.inc index 9e858d22c..a5a6dbfd8 100644 --- a/docs/usage/init.rst.inc +++ b/docs/usage/init.rst.inc @@ -6,7 +6,7 @@ borg init --------- :: - borg init REPOSITORY + borg [common options] init REPOSITORY positional arguments REPOSITORY @@ -14,7 +14,7 @@ positional arguments optional arguments ``-e``, ``--encryption`` - | select encryption key mode + | select encryption key mode **(required)** ``-a``, ``--append-only`` | create an append-only mode repository @@ -27,7 +27,7 @@ Description This command initializes an empty repository. A repository is a filesystem directory containing the deduplicated data from zero or more archives. -Encryption can be enabled at repository init time. +Encryption can be enabled at repository init time. It cannot be changed later. It is not recommended to work without encryption. Repository encryption protects you e.g. against the case that an attacker has access to your backup repository. @@ -82,8 +82,8 @@ These modes are new and *not* compatible with borg 1.0.x. `authenticated` mode uses no encryption, but authenticates repository contents through the same keyed BLAKE2b-256 hash as the other blake2 modes (it uses it -as chunk ID hash). The key is stored like repokey. -This mode is new and not compatible with borg 1.0.x. +as the chunk ID hash). The key is stored like repokey. +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 diff --git a/docs/usage/key_change-passphrase.rst.inc b/docs/usage/key_change-passphrase.rst.inc index c34fd002b..7666afc2f 100644 --- a/docs/usage/key_change-passphrase.rst.inc +++ b/docs/usage/key_change-passphrase.rst.inc @@ -6,7 +6,7 @@ borg key change-passphrase -------------------------- :: - borg key change-passphrase REPOSITORY + borg [common options] key change-passphrase REPOSITORY positional arguments REPOSITORY diff --git a/docs/usage/key_export.rst.inc b/docs/usage/key_export.rst.inc index 3013b8d2f..e976ae2dc 100644 --- a/docs/usage/key_export.rst.inc +++ b/docs/usage/key_export.rst.inc @@ -6,7 +6,7 @@ borg key export --------------- :: - borg key export REPOSITORY PATH + borg [common options] key export REPOSITORY PATH positional arguments REPOSITORY diff --git a/docs/usage/key_import.rst.inc b/docs/usage/key_import.rst.inc index c92bc9cd2..ceb89e3f7 100644 --- a/docs/usage/key_import.rst.inc +++ b/docs/usage/key_import.rst.inc @@ -6,7 +6,7 @@ borg key import --------------- :: - borg key import REPOSITORY PATH + borg [common options] key import REPOSITORY PATH positional arguments REPOSITORY diff --git a/docs/usage/key_migrate-to-repokey.rst.inc b/docs/usage/key_migrate-to-repokey.rst.inc index 66629bdbb..df242566f 100644 --- a/docs/usage/key_migrate-to-repokey.rst.inc +++ b/docs/usage/key_migrate-to-repokey.rst.inc @@ -6,7 +6,7 @@ borg key migrate-to-repokey --------------------------- :: - borg key migrate-to-repokey REPOSITORY + borg [common options] key migrate-to-repokey REPOSITORY positional arguments REPOSITORY diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc index ee14a108c..cd8db74c9 100644 --- a/docs/usage/list.rst.inc +++ b/docs/usage/list.rst.inc @@ -6,7 +6,7 @@ borg list --------- :: - borg list REPOSITORY_OR_ARCHIVE PATH + borg [common options] list REPOSITORY_OR_ARCHIVE PATH positional arguments REPOSITORY_OR_ARCHIVE @@ -21,7 +21,9 @@ optional arguments | specify format for file listing | (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{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 "bpath" key is therefore not available. + | Only valid for listing repository contents. 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-lines`` + | Only valid for listing archive contents. 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. `Common options`_ | diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc index e7e60ce27..026cc680f 100644 --- a/docs/usage/mount.rst.inc +++ b/docs/usage/mount.rst.inc @@ -6,7 +6,7 @@ borg mount ---------- :: - borg mount REPOSITORY_OR_ARCHIVE MOUNTPOINT + borg [common options] mount REPOSITORY_OR_ARCHIVE MOUNTPOINT positional arguments REPOSITORY_OR_ARCHIVE diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index c09b9885d..40e0c26cc 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -6,7 +6,7 @@ borg prune ---------- :: - borg prune REPOSITORY + borg [common options] prune REPOSITORY positional arguments REPOSITORY @@ -17,8 +17,6 @@ optional arguments | do not change repository ``--force`` | force pruning of corrupted archives - ``-p``, ``--progress`` - | show progress display while deleting archives ``-s``, ``--stats`` | print statistics for the deleted archive ``--list`` diff --git a/docs/usage/recreate.rst.inc b/docs/usage/recreate.rst.inc index a84c9faf1..fd3ef446d 100644 --- a/docs/usage/recreate.rst.inc +++ b/docs/usage/recreate.rst.inc @@ -6,7 +6,7 @@ borg recreate ------------- :: - borg recreate REPOSITORY_OR_ARCHIVE PATH + borg [common options] recreate REPOSITORY_OR_ARCHIVE PATH positional arguments REPOSITORY_OR_ARCHIVE @@ -19,8 +19,6 @@ optional arguments | output verbose list of items (files, dirs, ...) ``--filter STATUSCHARS`` | only display items with the given status characters - ``-p``, ``--progress`` - | show progress display while recreating archives ``-n``, ``--dry-run`` | do not change anything ``-s``, ``--stats`` diff --git a/docs/usage/rename.rst.inc b/docs/usage/rename.rst.inc index 6e53d2450..13baa7e45 100644 --- a/docs/usage/rename.rst.inc +++ b/docs/usage/rename.rst.inc @@ -6,7 +6,7 @@ borg rename ----------- :: - borg rename ARCHIVE NEWNAME + borg [common options] rename ARCHIVE NEWNAME positional arguments ARCHIVE diff --git a/docs/usage/serve.rst.inc b/docs/usage/serve.rst.inc index 628ff399f..f3f1aa659 100644 --- a/docs/usage/serve.rst.inc +++ b/docs/usage/serve.rst.inc @@ -6,7 +6,7 @@ borg serve ---------- :: - borg serve + borg [common options] serve optional arguments ``--restrict-to-path PATH`` diff --git a/docs/usage/umount.rst.inc b/docs/usage/umount.rst.inc index f99c1d46a..ab02038b8 100644 --- a/docs/usage/umount.rst.inc +++ b/docs/usage/umount.rst.inc @@ -6,7 +6,7 @@ borg umount ----------- :: - borg umount MOUNTPOINT + borg [common options] umount MOUNTPOINT positional arguments MOUNTPOINT diff --git a/docs/usage/upgrade.rst.inc b/docs/usage/upgrade.rst.inc index 4048ae5a8..bdf76ccd3 100644 --- a/docs/usage/upgrade.rst.inc +++ b/docs/usage/upgrade.rst.inc @@ -6,15 +6,13 @@ borg upgrade ------------ :: - borg upgrade REPOSITORY + borg [common options] upgrade REPOSITORY positional arguments REPOSITORY path to the repository to be upgraded optional arguments - ``-p``, ``--progress`` - | show progress display while upgrading the repository ``-n``, ``--dry-run`` | do not change repository ``-i``, ``--inplace`` diff --git a/docs/usage/with-lock.rst.inc b/docs/usage/with-lock.rst.inc index 407bda72b..47b5abcc3 100644 --- a/docs/usage/with-lock.rst.inc +++ b/docs/usage/with-lock.rst.inc @@ -6,7 +6,7 @@ borg with-lock -------------- :: - borg with-lock REPOSITORY COMMAND ARGS + borg [common options] with-lock REPOSITORY COMMAND ARGS positional arguments REPOSITORY