From 9ffb2472e40b0b0b6b76812861c1710704884cd0 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Tue, 6 Oct 2020 19:33:46 +0200 Subject: [PATCH 1/3] set release date --- docs/changes.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/changes.rst b/docs/changes.rst index ba2b82b14..bad60a6dc 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -217,8 +217,8 @@ The best check that everything is ok is to run a dry-run extraction:: Changelog ========= -Version 1.1.14 (not released yet) ---------------------------------- +Version 1.1.14 (2020-10-07) +--------------------------- Compatibility notes: From 69c319e7d2a54e09f89891cf5362cdafd1323d05 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Tue, 6 Oct 2020 19:42:06 +0200 Subject: [PATCH 2/3] build_usage --- docs/usage/check.rst.inc | 3 +++ docs/usage/create.rst.inc | 27 +++++++++++++++++++++++++-- docs/usage/help.rst.inc | 2 +- docs/usage/prune.rst.inc | 4 ++-- docs/usage/recreate.rst.inc | 12 +++++++----- 5 files changed, 38 insertions(+), 10 deletions(-) diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc index 1e3291c19..e9669bbe9 100644 --- a/docs/usage/check.rst.inc +++ b/docs/usage/check.rst.inc @@ -84,6 +84,9 @@ Description The check command verifies the consistency of a repository and the corresponding archives. +check --repair is a potentially dangerous function and might lead to data loss +(for kinds of corruption it is not capable of dealing with). BE VERY CAREFUL! + First, the underlying repository data files are checked: - For all segments, the segment magic header is checked. diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index 995f45d16..26f5c5653 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -162,7 +162,8 @@ that means if relative paths are desired, the command has to be run from the cor directory. When giving '-' as path, borg will read data from standard input and create a -file 'stdin' in the created archive from that data. +file 'stdin' in the created archive from that data. See section *Reading from +stdin* below for details. The archive will consume almost no disk space for files or parts of files that have already been stored in other archives. @@ -204,6 +205,7 @@ ctime vs. mtime: safety vs. speed as it can not be set from userspace. But, a metadata-only change will already update the ctime, so there might be some unnecessary chunking/hashing even without content changes. Some filesystems do not support ctime (change time). + E.g. doing a chown or chmod to a file will change its ctime. - mtime usually works and only updates if file contents were changed. But mtime can be arbitrarily set from userspace, e.g. to set mtime back to the same value it had before a content change happened. This can be used maliciously as well as @@ -243,6 +245,8 @@ only include the objects specified by ``--exclude-if-present`` in your backup, and not include any other contents of the containing folder, this can be enabled through using the ``--keep-exclude-tags`` option. +.. _list_item_flags: + Item flags ++++++++++ @@ -280,4 +284,23 @@ Other flags used include: - 'i' = backup data was read from standard input (stdin) - '-' = dry run, item was *not* backed up - 'x' = excluded, item was *not* backed up -- '?' = missing status code (if you see this, please file a bug report!) \ No newline at end of file +- '?' = missing status code (if you see this, please file a bug report!) + +Reading from stdin +++++++++++++++++++ + +To read from stdin, specify ``-`` as path and pipe directly to borg:: + + backup-vm --id myvm --stdout | borg create REPO::ARCHIVE - + +Note that piping to borg creates an archive even if the command piping +to borg exits with a failure. In this case, **one can end up with +truncated output being backed up**. + +Reading from stdin yields just a stream of data without file metadata +associated with it, and the files cache is not needed at all. So it is +safe to disable it via ``--no-files-cache`` and speed up backup +creation a bit. + +By default, the content read from stdin is stored in a file called 'stdin'. +Use ``--stdin-name`` to change the name. \ No newline at end of file diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index 56b138afc..908da403b 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -74,7 +74,7 @@ Path full-match, selector `pf:` This pattern style is (only) useful to match full paths. This is kind of a pseudo pattern as it can not have any variable or unspecified parts - the full path must be given. - `pf:root/file.ext` matches `root/file.txt` only. + `pf:root/file.ext` matches `root/file.ext` only. Implementation note: this is implemented via very time-efficient O(1) hashtable lookups (this means you can have huge amounts of such patterns diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index 81c2d32f9..dc42e18a3 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -21,7 +21,7 @@ borg prune +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``-n``, ``--dry-run`` | do not change repository | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--force`` | force pruning of corrupted archives | + | | ``--force`` | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work. | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``-s``, ``--stats`` | print statistics for the deleted archive | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -72,7 +72,7 @@ borg prune optional arguments -n, --dry-run do not change repository - --force force pruning of corrupted archives + --force force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work. -s, --stats print statistics for the deleted archive --list output verbose list of archives it keeps/prunes --keep-within INTERVAL keep all archives within this time interval diff --git a/docs/usage/recreate.rst.inc b/docs/usage/recreate.rst.inc index c503f6d50..05dab0e2a 100644 --- a/docs/usage/recreate.rst.inc +++ b/docs/usage/recreate.rst.inc @@ -117,11 +117,13 @@ Description Recreate the contents of existing archives. -This is an *experimental* feature. Do *not* use this on your only backup. +recreate is a potentially dangerous function and might lead to data loss +(if used wrongly). BE VERY CAREFUL! -``--exclude``, ``--exclude-from``, ``--exclude-if-present``, ``--keep-exclude-tags``, and PATH -have the exact same semantics as in "borg create". If PATHs are specified the -resulting archive will only contain files from these PATHs. +``--exclude``, ``--exclude-from``, ``--exclude-if-present``, ``--keep-exclude-tags`` +and PATH have the exact same semantics as in "borg create", but they only check +for files in the archives and not in the local file system. If PATHs are specified, +the resulting archives will only contain files from these PATHs. Note that all paths in an archive are relative, therefore absolute patterns/paths will *not* match (``--exclude``, ``--exclude-from``, PATHs). @@ -139,7 +141,7 @@ Borg 1.x archives. Depending on the PATHs and patterns given, recreate can be used to permanently delete files from archives. When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHS are -interpreted. +interpreted. See :ref:`list_item_flags` in ``borg create`` for details. The archive being recreated is only removed after the operation completes. The archive that is built during the operation exists at the same time at From 464a7191b0416bc6270504145850fa819dc2a1a7 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Tue, 6 Oct 2020 19:43:05 +0200 Subject: [PATCH 3/3] build_man --- docs/man/borg-benchmark-crud.1 | 2 +- docs/man/borg-benchmark.1 | 2 +- docs/man/borg-break-lock.1 | 2 +- docs/man/borg-change-passphrase.1 | 2 +- docs/man/borg-check.1 | 9 +++-- docs/man/borg-common.1 | 2 +- docs/man/borg-compression.1 | 2 +- docs/man/borg-config.1 | 2 +- docs/man/borg-create.1 | 37 ++++++++++++++++--- docs/man/borg-delete.1 | 6 ++-- docs/man/borg-diff.1 | 4 +-- docs/man/borg-export-tar.1 | 4 +-- docs/man/borg-extract.1 | 4 +-- docs/man/borg-info.1 | 6 ++-- docs/man/borg-init.1 | 4 +-- docs/man/borg-key-change-passphrase.1 | 2 +- docs/man/borg-key-export.1 | 2 +- docs/man/borg-key-import.1 | 2 +- docs/man/borg-key-migrate-to-repokey.1 | 2 +- docs/man/borg-key.1 | 2 +- docs/man/borg-list.1 | 10 +++--- docs/man/borg-mount.1 | 8 ++--- docs/man/borg-patterns.1 | 4 +-- docs/man/borg-placeholders.1 | 2 +- docs/man/borg-prune.1 | 8 ++--- docs/man/borg-recreate.1 | 20 ++++++----- docs/man/borg-rename.1 | 2 +- docs/man/borg-serve.1 | 2 +- docs/man/borg-umount.1 | 2 +- docs/man/borg-upgrade.1 | 2 +- docs/man/borg-with-lock.1 | 2 +- docs/man/borg.1 | 49 +++++++------------------- docs/man/borgfs.1 | 8 ++--- 33 files changed, 112 insertions(+), 105 deletions(-) diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index 69810f551..ec730625b 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BENCHMARK-CRUD 1 "2020-06-06" "" "borg backup tool" +.TH BORG-BENCHMARK-CRUD 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. . diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index a8eaaa9c6..74282976d 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BENCHMARK 1 "2020-06-06" "" "borg backup tool" +.TH BORG-BENCHMARK 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-benchmark \- benchmark command . diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index 2bfe5de08..eb434e9d8 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 "2020-06-06" "" "borg backup tool" +.TH BORG-BREAK-LOCK 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. . diff --git a/docs/man/borg-change-passphrase.1 b/docs/man/borg-change-passphrase.1 index a76132bca..5869d244f 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 "2020-06-06" "" "borg backup tool" +.TH BORG-CHANGE-PASSPHRASE 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-change-passphrase \- Change repository key file passphrase . diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index 08ab521b4..bb8c606e1 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 "2020-06-06" "" "borg backup tool" +.TH BORG-CHECK 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-check \- Check repository consistency . @@ -37,6 +37,9 @@ borg [common options] check [options] [REPOSITORY_OR_ARCHIVE] .sp The check command verifies the consistency of a repository and the corresponding archives. .sp +check \-\-repair is a potentially dangerous function and might lead to data loss +(for kinds of corruption it is not capable of dealing with). BE VERY CAREFUL! +.sp First, the underlying repository data files are checked: .INDENT 0.0 .IP \(bu 2 @@ -121,10 +124,10 @@ work slower, but using less space .SS Archive filters .INDENT 0.0 .TP -.BI \-P \ PREFIX\fP,\fB \ \-\-prefix \ PREFIX +.BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX only consider archive names starting with this prefix. .TP -.BI \-a \ GLOB\fP,\fB \ \-\-glob\-archives \ GLOB +.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. .TP .BI \-\-sort\-by \ KEYS diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index 922b6b118..d6dce89de 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 "2020-06-06" "" "borg backup tool" +.TH BORG-COMMON 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-common \- Common options of Borg commands . diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index fde710025..5390fbc01 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 "2020-06-06" "" "borg backup tool" +.TH BORG-COMPRESSION 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-compression \- Details regarding compression . diff --git a/docs/man/borg-config.1 b/docs/man/borg-config.1 index 8e92ad824..d1d5a112a 100644 --- a/docs/man/borg-config.1 +++ b/docs/man/borg-config.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CONFIG 1 "2020-06-06" "" "borg backup tool" +.TH BORG-CONFIG 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-config \- get, set, and delete values in a repository or cache config file . diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index c1694a705..a2ed3ad30 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 "2020-06-06" "" "borg backup tool" +.TH BORG-CREATE 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-create \- Create new archive . @@ -41,7 +41,8 @@ that means if relative paths are desired, the command has to be run from the cor directory. .sp When giving \(aq\-\(aq as path, borg will read data from standard input and create a -file \(aqstdin\(aq in the created archive from that data. +file \(aqstdin\(aq in the created archive from that data. See section \fIReading from +stdin\fP below for details. .sp The archive will consume almost no disk space for files or parts of files that have already been stored in other archives. @@ -92,6 +93,7 @@ ctime is a rather safe way to detect changes to a file (metadata and contents) as it can not be set from userspace. But, a metadata\-only change will already update the ctime, so there might be some unnecessary chunking/hashing even without content changes. Some filesystems do not support ctime (change time). +E.g. doing a chown or chmod to a file will change its ctime. .IP \(bu 2 mtime usually works and only updates if file contents were changed. But mtime can be arbitrarily set from userspace, e.g. to set mtime back to the same value @@ -158,7 +160,7 @@ use NAME in archive for stdin data (default: "stdin") .SS Exclusion options .INDENT 0.0 .TP -.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN +.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN exclude paths matching PATTERN .TP .BI \-\-exclude\-from \ EXCLUDEFILE @@ -221,13 +223,13 @@ add a comment text to the archive .BI \-\-timestamp \ TIMESTAMP manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss format). Alternatively, give a reference file/directory. .TP -.BI \-c \ SECONDS\fP,\fB \ \-\-checkpoint\-interval \ SECONDS +.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS write checkpoint every SECONDS seconds (Default: 1800) .TP .BI \-\-chunker\-params \ PARAMS specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095 .TP -.BI \-C \ COMPRESSION\fP,\fB \ \-\-compression \ COMPRESSION +.BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. .UNINDENT .SH EXAMPLES @@ -372,6 +374,31 @@ Other flags used include: .IP \(bu 2 \(aq?\(aq = missing status code (if you see this, please file a bug report!) .UNINDENT +.SS Reading from stdin +.sp +To read from stdin, specify \fB\-\fP as path and pipe directly to borg: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +backup\-vm \-\-id myvm \-\-stdout | borg create REPO::ARCHIVE \- +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Note that piping to borg creates an archive even if the command piping +to borg exits with a failure. In this case, \fBone can end up with +truncated output being backed up\fP\&. +.sp +Reading from stdin yields just a stream of data without file metadata +associated with it, and the files cache is not needed at all. So it is +safe to disable it via \fB\-\-no\-files\-cache\fP and speed up backup +creation a bit. +.sp +By default, the content read from stdin is stored in a file called \(aqstdin\(aq. +Use \fB\-\-stdin\-name\fP to change the name. .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-check(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index 526752abd..760185a26 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 "2020-06-06" "" "borg backup tool" +.TH BORG-DELETE 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-delete \- Delete an existing repository or archives . @@ -76,10 +76,10 @@ work slower, but using less space .SS Archive filters .INDENT 0.0 .TP -.BI \-P \ PREFIX\fP,\fB \ \-\-prefix \ PREFIX +.BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX only consider archive names starting with this prefix. .TP -.BI \-a \ GLOB\fP,\fB \ \-\-glob\-archives \ GLOB +.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. .TP .BI \-\-sort\-by \ KEYS diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index afde2f997..ba7e0efa7 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 "2020-06-06" "" "borg backup tool" +.TH BORG-DIFF 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-diff \- Diff contents of two archives . @@ -81,7 +81,7 @@ Sort the output lines by file path. .SS Exclusion options .INDENT 0.0 .TP -.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN +.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN exclude paths matching PATTERN .TP .BI \-\-exclude\-from \ EXCLUDEFILE diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index a99c04cfb..e05e1719c 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 "2020-06-06" "" "borg backup tool" +.TH BORG-EXPORT-TAR 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-export-tar \- Export archive contents as a tarball . @@ -99,7 +99,7 @@ output verbose list of items (files, dirs, ...) .SS Exclusion options .INDENT 0.0 .TP -.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN +.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN exclude paths matching PATTERN .TP .BI \-\-exclude\-from \ EXCLUDEFILE diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index b6ce69f68..b7f09b7d9 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 "2020-06-06" "" "borg backup tool" +.TH BORG-EXTRACT 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-extract \- Extract archive contents . @@ -92,7 +92,7 @@ create holes in output sparse file from all\-zero chunks .SS Exclusion options .INDENT 0.0 .TP -.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN +.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN exclude paths matching PATTERN .TP .BI \-\-exclude\-from \ EXCLUDEFILE diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index fa0686bf6..0a0a8fda5 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 "2020-06-06" "" "borg backup tool" +.TH BORG-INFO 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-info \- Show archive details such as disk space used . @@ -68,10 +68,10 @@ format output as JSON .SS Archive filters .INDENT 0.0 .TP -.BI \-P \ PREFIX\fP,\fB \ \-\-prefix \ PREFIX +.BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX only consider archive names starting with this prefix. .TP -.BI \-a \ GLOB\fP,\fB \ \-\-glob\-archives \ GLOB +.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. .TP .BI \-\-sort\-by \ KEYS diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1 index 7275c5111..1b397ada4 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 "2020-06-06" "" "borg backup tool" +.TH BORG-INIT 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-init \- Initialize an empty repository . @@ -189,7 +189,7 @@ repository to create .SS optional arguments .INDENT 0.0 .TP -.BI \-e \ MODE\fP,\fB \ \-\-encryption \ MODE +.BI \-e \ MODE\fR,\fB \ \-\-encryption \ MODE select encryption key mode \fB(required)\fP .TP .B \-\-append\-only diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 4ef78b015..1df0ea18d 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 "2020-06-06" "" "borg backup tool" +.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-key-change-passphrase \- Change repository key file passphrase . diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index 1b121520b..f57d590aa 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 "2020-06-06" "" "borg backup tool" +.TH BORG-KEY-EXPORT 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-key-export \- Export the repository key for backup . diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index b65b3ecbb..280500944 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 "2020-06-06" "" "borg backup tool" +.TH BORG-KEY-IMPORT 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-key-import \- Import the repository key from backup . diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1 index 502eba046..f8a52c2dc 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 "2020-06-06" "" "borg backup tool" +.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-key-migrate-to-repokey \- Migrate passphrase -> repokey . diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index 6d15cc38b..b43623147 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 "2020-06-06" "" "borg backup tool" +.TH BORG-KEY 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-key \- Manage a keyfile or repokey of a repository . diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index afed4b67d..3921df7a0 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 "2020-06-06" "" "borg backup tool" +.TH BORG-LIST 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-list \- List archive or repository contents . @@ -56,7 +56,7 @@ paths to list; patterns are supported .B \-\-short only print file/directory names, nothing else .TP -.BI \-\-format \ FORMAT\fP,\fB \ \-\-list\-format \ FORMAT +.BI \-\-format \ FORMAT\fR,\fB \ \-\-list\-format \ FORMAT specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {mtime} {path}{extra}{NL}") .TP .B \-\-json @@ -68,10 +68,10 @@ Only valid for listing archive contents. Format output as JSON Lines. The form o .SS Archive filters .INDENT 0.0 .TP -.BI \-P \ PREFIX\fP,\fB \ \-\-prefix \ PREFIX +.BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX only consider archive names starting with this prefix. .TP -.BI \-a \ GLOB\fP,\fB \ \-\-glob\-archives \ GLOB +.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. .TP .BI \-\-sort\-by \ KEYS @@ -86,7 +86,7 @@ consider last N archives after other filters were applied .SS Exclusion options .INDENT 0.0 .TP -.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN +.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN exclude paths matching PATTERN .TP .BI \-\-exclude\-from \ EXCLUDEFILE diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index afff012c3..f99c7979c 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 "2020-06-06" "" "borg backup tool" +.TH BORG-MOUNT 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-mount \- Mount archive or an entire repository as a FUSE filesystem . @@ -102,10 +102,10 @@ Extra mount options .SS Archive filters .INDENT 0.0 .TP -.BI \-P \ PREFIX\fP,\fB \ \-\-prefix \ PREFIX +.BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX only consider archive names starting with this prefix. .TP -.BI \-a \ GLOB\fP,\fB \ \-\-glob\-archives \ GLOB +.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. .TP .BI \-\-sort\-by \ KEYS @@ -120,7 +120,7 @@ consider last N archives after other filters were applied .SS Exclusion options .INDENT 0.0 .TP -.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN +.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN exclude paths matching PATTERN .TP .BI \-\-exclude\-from \ EXCLUDEFILE diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index 6df156a30..855f19090 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 "2020-06-06" "" "borg backup tool" +.TH BORG-PATTERNS 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns . @@ -101,7 +101,7 @@ This pattern style is useful to match whole sub\-directories. The pattern This pattern style is (only) useful to match full paths. This is kind of a pseudo pattern as it can not have any variable or unspecified parts \- the full path must be given. -\fIpf:root/file.ext\fP matches \fIroot/file.txt\fP only. +\fIpf:root/file.ext\fP matches \fIroot/file.ext\fP only. .sp Implementation note: this is implemented via very time\-efficient O(1) hashtable lookups (this means you can have huge amounts of such patterns diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index 5312f119b..951697206 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 "2020-06-06" "" "borg backup tool" +.TH BORG-PLACEHOLDERS 1 "2020-10-06" "" "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 af8cf6e84..78fa8625a 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 "2020-06-06" "" "borg backup tool" +.TH BORG-PRUNE 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-prune \- Prune repository archives according to specified rules . @@ -94,7 +94,7 @@ repository to prune do not change repository .TP .B \-\-force -force pruning of corrupted archives +force pruning of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work. .TP .B \-s\fP,\fB \-\-stats print statistics for the deleted archive @@ -132,10 +132,10 @@ work slower, but using less space .SS Archive filters .INDENT 0.0 .TP -.BI \-P \ PREFIX\fP,\fB \ \-\-prefix \ PREFIX +.BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX only consider archive names starting with this prefix. .TP -.BI \-a \ GLOB\fP,\fB \ \-\-glob\-archives \ GLOB +.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. .UNINDENT .SH EXAMPLES diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index 4974838ce..36ebeb252 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 "2020-06-06" "" "borg backup tool" +.TH BORG-RECREATE 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-recreate \- Re-create archives . @@ -37,11 +37,13 @@ borg [common options] recreate [options] [REPOSITORY_OR_ARCHIVE] [PATH...] .sp Recreate the contents of existing archives. .sp -This is an \fIexperimental\fP feature. Do \fInot\fP use this on your only backup. +recreate is a potentially dangerous function and might lead to data loss +(if used wrongly). BE VERY CAREFUL! .sp -\fB\-\-exclude\fP, \fB\-\-exclude\-from\fP, \fB\-\-exclude\-if\-present\fP, \fB\-\-keep\-exclude\-tags\fP, and PATH -have the exact same semantics as in "borg create". If PATHs are specified the -resulting archive will only contain files from these PATHs. +\fB\-\-exclude\fP, \fB\-\-exclude\-from\fP, \fB\-\-exclude\-if\-present\fP, \fB\-\-keep\-exclude\-tags\fP +and PATH have the exact same semantics as in "borg create", but they only check +for files in the archives and not in the local file system. If PATHs are specified, +the resulting archives will only contain files from these PATHs. .sp Note that all paths in an archive are relative, therefore absolute patterns/paths will \fInot\fP match (\fB\-\-exclude\fP, \fB\-\-exclude\-from\fP, PATHs). @@ -59,7 +61,7 @@ Borg 1.x archives. Depending on the PATHs and patterns given, recreate can be used to permanently delete files from archives. When in doubt, use \fB\-\-dry\-run \-\-verbose \-\-list\fP to see how patterns/PATHS are -interpreted. +interpreted. See \fIlist_item_flags\fP in \fBborg create\fP for details. .sp The archive being recreated is only removed after the operation completes. The archive that is built during the operation exists at the same time at @@ -112,7 +114,7 @@ print statistics at end .SS Exclusion options .INDENT 0.0 .TP -.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN +.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN exclude paths matching PATTERN .TP .BI \-\-exclude\-from \ EXCLUDEFILE @@ -139,7 +141,7 @@ if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit .BI \-\-target \ TARGET create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive) .TP -.BI \-c \ SECONDS\fP,\fB \ \-\-checkpoint\-interval \ SECONDS +.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS write checkpoint every SECONDS seconds (Default: 1800) .TP .BI \-\-comment \ COMMENT @@ -148,7 +150,7 @@ add a comment text to the archive .BI \-\-timestamp \ TIMESTAMP manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss format). alternatively, give a reference file/directory. .TP -.BI \-C \ COMPRESSION\fP,\fB \ \-\-compression \ COMPRESSION +.BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. .TP .BI \-\-recompress \ MODE diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index 9028be72f..25f2d0b0c 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 "2020-06-06" "" "borg backup tool" +.TH BORG-RENAME 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-rename \- Rename an existing archive . diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 index e580a61f6..1bb689215 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 "2020-06-06" "" "borg backup tool" +.TH BORG-SERVE 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-serve \- Start in server mode. This command is usually not used manually. . diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index cffcb759a..f98f94a2c 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 "2020-06-06" "" "borg backup tool" +.TH BORG-UMOUNT 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-umount \- un-mount the FUSE filesystem . diff --git a/docs/man/borg-upgrade.1 b/docs/man/borg-upgrade.1 index 6cf4cf599..0540611f3 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 "2020-06-06" "" "borg backup tool" +.TH BORG-UPGRADE 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-upgrade \- upgrade a repository from a previous version . diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index 43a9441a5..18bc6bb58 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 "2020-06-06" "" "borg backup tool" +.TH BORG-WITH-LOCK 1 "2020-10-06" "" "borg backup tool" .SH NAME borg-with-lock \- run a user specified command with the repository lock held . diff --git a/docs/man/borg.1 b/docs/man/borg.1 index 8c83a5567..9762bccc1 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG 1 "2020-06-06" "" "borg backup tool" +.TH BORG 1 "2017-02-05" "" "borg backup tool" .SH NAME borg \- deduplicating and encrypting backup tool . @@ -30,26 +30,10 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.SH BORG -.SS deduplicating and encrypting backup tool -.INDENT 0.0 -.TP -.B Author -The Borg Collective -.TP -.B Date -2020\-06\-06 -.TP -.B Manual section -1 -.TP -.B Manual group -borg backup tool -.UNINDENT -.SS SYNOPSIS +.SH SYNOPSIS .sp borg [common options] [options] [arguments] -.SS DESCRIPTION +.SH DESCRIPTION .\" we don't include the README.rst here since we want to keep this terse. . .sp @@ -66,7 +50,7 @@ Borg stores a set of files in an \fIarchive\fP\&. A \fIrepository\fP is a collec of \fIarchives\fP\&. The format of repositories is Borg\-specific. Borg does not distinguish archives from each other in any way other than their name, it does not matter when or where archives were created (e.g. different hosts). -.SS EXAMPLES +.SH EXAMPLES .SS A step\-by\-step example .INDENT 0.0 .IP 1. 3 @@ -201,7 +185,7 @@ reports during command execution. You can also add the \fB\-v\fP (or get other informational messages. .UNINDENT .UNINDENT -.SS NOTES +.SH NOTES .SS Positional Arguments and Options: Order matters .sp Borg only supports taking options (\fB\-s\fP and \fB\-\-progress\fP in the example) @@ -493,18 +477,17 @@ For "Warning: Attempting to access a previously unknown unencrypted repository" For "Warning: The repository at location ... was previously located at ..." .TP .B BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO (or =YES) -For "Warning: \(aqcheck \-\-repair\(aq is an experimental feature that might result in data loss." +For "This is a potentially dangerous function..." (check \-\-repair) .TP .B BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES) For "You requested to completely DELETE the repository \fIincluding\fP all archives it contains:" -.TP -.B BORG_RECREATE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES) -For "recreate is an experimental feature." .UNINDENT .sp Note: answers are case sensitive. setting an invalid answer value might either give the default answer or ask you interactively, depending on whether retries are allowed (they by default are allowed). So please test your scripts interactively before making them a non\-interactive script. +.UNINDENT +.INDENT 0.0 .TP .B Directories and files: .INDENT 7.0 @@ -517,22 +500,14 @@ to modify \fBBORG_BASE_DIR\fP: the other paths for cache, config etc. will adapt .TP .B BORG_CACHE_DIR Defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while - -.nf -\(gaXDG env var\(ga_ -.fi - \fBXDG_CACHE_HOME\fP is set, then \fB$XDG_CACHE_HOME/borg\fP is being used instead. +\fI\%XDG env var\fP \fBXDG_CACHE_HOME\fP is set, then \fB$XDG_CACHE_HOME/borg\fP is being used instead. This directory contains the local cache and might need a lot of space for dealing with big repositories. Make sure you\(aqre aware of the associated security aspects of the cache location: \fIcache_security\fP .TP .B BORG_CONFIG_DIR Defaults to \fB$BORG_BASE_DIR/.config/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while - -.nf -\(gaXDG env var\(ga_ -.fi - \fBXDG_CONFIG_HOME\fP is set, then \fB$XDG_CONFIG_HOME/borg\fP is being used instead. +\fI\%XDG env var\fP \fBXDG_CONFIG_HOME\fP is set, then \fB$XDG_CONFIG_HOME/borg\fP is being used instead. This directory contains all borg configuration directories, see the FAQ for a security advisory about the data in this directory: \fIhome_config_borg\fP .TP @@ -713,7 +688,7 @@ default temporary directory at /tmp. This can be remediated by ensuring the $TMPDIR, $TEMP, or $TMP environment variable is properly set for the sshd process. For some OSes, this can be done just by setting the correct value in the -.bashrc (or equivalent login config file for other shells), however in +\&.bashrc (or equivalent login config file for other shells), however in other cases it may be necessary to first enable \fBPermitUserEnvironment yes\fP in your \fBsshd_config\fP file, then add \fBenvironment="TMPDIR=/my/big/tmpdir"\fP at the start of the public key to be used in the \fBauthorized_hosts\fP file. @@ -880,7 +855,7 @@ This includes resource forks on Mac OS X. .IP [7] 5 aka \fIBSD flags\fP\&. The Linux set of flags [1] is portable across platforms. The BSDs define additional flags. -.SS SEE ALSO +.SH SEE ALSO .sp \fIborg\-common(1)\fP for common command line options .sp diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1 index ae301210f..723fedac8 100644 --- a/docs/man/borgfs.1 +++ b/docs/man/borgfs.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORGFS 1 "2020-06-06" "" "borg backup tool" +.TH BORGFS 1 "2020-10-06" "" "borg backup tool" .SH NAME borgfs \- Mount archive or an entire repository as a FUSE filesystem . @@ -105,10 +105,10 @@ Extra mount options .SS Archive filters .INDENT 0.0 .TP -.BI \-P \ PREFIX\fP,\fB \ \-\-prefix \ PREFIX +.BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX only consider archive names starting with this prefix. .TP -.BI \-a \ GLOB\fP,\fB \ \-\-glob\-archives \ GLOB +.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. .TP .BI \-\-sort\-by \ KEYS @@ -123,7 +123,7 @@ consider last N archives after other filters were applied .SS Exclusion options .INDENT 0.0 .TP -.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN +.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN exclude paths matching PATTERN .TP .BI \-\-exclude\-from \ EXCLUDEFILE