From fb496bf1b7f5c1ff75b40dfa1192c4656655f3e4 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Thu, 26 Sep 2024 07:57:01 +0200 Subject: [PATCH] build_usage build_man --- docs/man/borg-benchmark-cpu.1 | 2 +- docs/man/borg-benchmark-crud.1 | 2 +- docs/man/borg-benchmark.1 | 2 +- docs/man/borg-break-lock.1 | 2 +- docs/man/borg-check.1 | 2 +- docs/man/borg-common.1 | 2 +- docs/man/borg-compact.1 | 2 +- docs/man/borg-compression.1 | 2 +- docs/man/borg-create.1 | 29 +++++------- docs/man/borg-delete.1 | 17 +++++-- docs/man/borg-diff.1 | 2 +- docs/man/borg-export-tar.1 | 2 +- docs/man/borg-extract.1 | 2 +- docs/man/borg-import-tar.1 | 6 +-- docs/man/borg-info.1 | 16 ++++--- docs/man/borg-key-change-location.1 | 2 +- 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.1 | 2 +- docs/man/borg-list.1 | 2 +- docs/man/borg-match-archives.1 | 2 +- docs/man/borg-mount.1 | 2 +- docs/man/borg-patterns.1 | 2 +- docs/man/borg-placeholders.1 | 2 +- docs/man/borg-prune.1 | 41 ++++++++++++----- docs/man/borg-recreate.1 | 4 +- docs/man/borg-rename.1 | 2 +- docs/man/borg-repo-compress.1 | 2 +- docs/man/borg-repo-create.1 | 2 +- docs/man/borg-repo-delete.1 | 2 +- docs/man/borg-repo-info.1 | 2 +- docs/man/borg-repo-list.1 | 2 +- docs/man/borg-repo-space.1 | 2 +- docs/man/borg-serve.1 | 2 +- docs/man/borg-transfer.1 | 2 +- docs/man/borg-umount.1 | 2 +- docs/man/borg-version.1 | 2 +- docs/man/borg-with-lock.1 | 2 +- docs/man/borg.1 | 65 +++++++++++---------------- docs/man/borgfs.1 | 2 +- docs/usage/create.rst.inc | 7 ++- docs/usage/delete.rst.inc | 8 +++- docs/usage/help.rst.inc | 5 ++- docs/usage/info.rst.inc | 8 +++- docs/usage/prune.rst.inc | 21 ++++++--- docs/usage/recreate.rst.inc | 4 +- 47 files changed, 167 insertions(+), 132 deletions(-) diff --git a/docs/man/borg-benchmark-cpu.1 b/docs/man/borg-benchmark-cpu.1 index 7aca3b2c38..2140bf7274 100644 --- a/docs/man/borg-benchmark-cpu.1 +++ b/docs/man/borg-benchmark-cpu.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-BENCHMARK-CPU" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-BENCHMARK-CPU" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-benchmark-cpu \- Benchmark CPU bound operations. .SH SYNOPSIS diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index dc20b75a4a..00fb828341 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-BENCHMARK-CRUD" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-BENCHMARK-CRUD" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. .SH SYNOPSIS diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index bcabbc0c91..782122432d 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-BENCHMARK" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-BENCHMARK" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-benchmark \- benchmark command .SH SYNOPSIS diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index 562adb8151..851e1ff6ec 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-BREAK-LOCK" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-BREAK-LOCK" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. .SH SYNOPSIS diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index 7d15dec2a1..4c6defab0f 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-CHECK" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-CHECK" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-check \- Check repository consistency .SH SYNOPSIS diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index 692cfdfc82..ae515f8b8f 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-COMMON" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-COMMON" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-common \- Common options of Borg commands .SH SYNOPSIS diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1 index 86c3836cb8..b8d69463a1 100644 --- a/docs/man/borg-compact.1 +++ b/docs/man/borg-compact.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-COMPACT" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-COMPACT" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-compact \- Collect garbage in repository .SH SYNOPSIS diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index c1c4e4cc7d..4d4d9e9e4e 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-COMPRESSION" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-COMPRESSION" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-compression \- Details regarding compression .SH DESCRIPTION diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index c84ee839cf..ce761d4023 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-CREATE" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-CREATE" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-create \- Create new archive .SH SYNOPSIS @@ -53,7 +53,9 @@ stdin\fP 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. .sp -The archive name needs to be unique. +The archive name does NOT need to be unique, you can and should use the same +name for a series of archives. The unique archive identifier is its ID (hash) +and you can abbreviate the ID as long as it is unique. .sp In the archive name, you may use the following placeholders: {now}, {utcnow}, {fqdn}, {hostname}, {user} and some others. @@ -153,9 +155,6 @@ only display items with the given status characters (see description) .B \-\-json output stats as JSON. Implies \fB\-\-stats\fP\&. .TP -.B \-\-prefer\-adhoc\-cache -experimental: prefer AdHocCache (w/o files cache) over AdHocWithFilesCache (with files cache). -.TP .BI \-\-stdin\-name \ NAME use NAME in archive for stdin data (default: \(aqstdin\(aq) .TP @@ -283,18 +282,18 @@ $ borg create my\-files \e # /home//.thumbnails is excluded, not /home/*/*/.thumbnails etc.) $ borg create my\-files /home \-\-exclude \(aqsh:home/*/.thumbnails\(aq -# Backup the root filesystem into an archive named \(dqroot\-YYYY\-MM\-DD\(dq +# Backup the root filesystem into an archive named \(dqroot\-archive\(dq # use zlib compression (good, but slow) \- default is lz4 (fast, low compression ratio) -$ borg create \-C zlib,6 \-\-one\-file\-system root\-{now:%Y\-%m\-%d} / +$ borg create \-C zlib,6 \-\-one\-file\-system root\-archive / -# Backup into an archive name like FQDN\-root\-TIMESTAMP -$ borg create \(aq{fqdn}\-root\-{now}\(aq / +# Backup into an archive name like FQDN\-root +$ borg create \(aq{fqdn}\-root\(aq / # Backup a remote host locally (\(dqpull\(dq style) using sshfs $ mkdir sshfs\-mount $ sshfs root@example.com:/ sshfs\-mount $ cd sshfs\-mount -$ borg create example.com\-root\-{now:%Y\-%m\-%d} . +$ borg create example.com\-root . $ cd .. $ fusermount \-u sshfs\-mount @@ -323,17 +322,13 @@ $ borg create \-\-compression lzma,N arch ~ # Only compress compressible data with lzma,N (N = 0..9) $ borg create \-\-compression auto,lzma,N arch ~ -# Use short hostname, user name and current time in archive name -$ borg create \(aq{hostname}\-{user}\-{now}\(aq ~ -# Similar, use the same datetime format that is default as of borg 1.1 -$ borg create \(aq{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S}\(aq ~ -# As above, but add nanoseconds -$ borg create \(aq{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f}\(aq ~ +# Use short hostname and user name as archive name +$ borg create \(aq{hostname}\-{user}\(aq ~ # Backing up relative paths by moving into the correct directory first $ cd /home/user/Documents # The root directory of the archive will be \(dqprojectA\(dq -$ borg create \(aqdaily\-projectA\-{now:%Y\-%m\-%d}\(aq projectA +$ borg create \(aqdaily\-projectA\(aq projectA # Use external command to determine files to archive # Use \-\-paths\-from\-stdin with find to back up only files less than 1MB in size diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index a1eab4f287..80f80dd4f9 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -27,12 +27,12 @@ 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 .. -.TH "BORG-DELETE" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-DELETE" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-delete \- Delete archives .SH SYNOPSIS .sp -borg [common options] delete [options] +borg [common options] delete [options] [NAME] .SH DESCRIPTION .sp This command deletes archives from the repository. @@ -48,6 +48,12 @@ see \fIborg_patterns\fP). .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B NAME +specify the archive name +.UNINDENT .SS optional arguments .INDENT 0.0 .TP @@ -90,11 +96,14 @@ consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. .sp .nf .ft C -# delete a single backup archive: -$ borg delete \-a Monday +# delete all backup archives named \(dqkenny\-files\(dq: +$ borg delete \-a kenny\-files # actually free disk space: $ borg compact +# delete a specific backup archive using its unique archive ID prefix +$ borg delete aid:d34db33f + # delete all archives whose names begin with the machine\(aqs hostname followed by \(dq\-\(dq $ borg delete \-a \(aqsh:{hostname}\-*\(aq diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index 91808168b2..567b9d44ea 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-DIFF" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-DIFF" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-diff \- Diff contents of two archives .SH SYNOPSIS diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index 4505c80284..212df994b8 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-EXPORT-TAR" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-EXPORT-TAR" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-export-tar \- Export archive contents as a tarball .SH SYNOPSIS diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index 5868498356..11fc96fd59 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-EXTRACT" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-EXTRACT" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-extract \- Extract archive contents .SH SYNOPSIS diff --git a/docs/man/borg-import-tar.1 b/docs/man/borg-import-tar.1 index 4c1c399fa6..2753cd98c3 100644 --- a/docs/man/borg-import-tar.1 +++ b/docs/man/borg-import-tar.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-IMPORT-TAR" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-IMPORT-TAR" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-import-tar \- Create a backup archive from a tarball .SH SYNOPSIS @@ -170,9 +170,9 @@ Outputs a script that copies all archives from repo1 to repo2: .sp .nf .ft C -for A T in \(gaborg list \-\-format=\(aq{archive} {time:%Y\-%m\-%dT%H:%M:%S}{NL}\(aq\(ga +for N I T in \(gaborg list \-\-format=\(aq{archive} {id} {time:%Y\-%m\-%dT%H:%M:%S}{NL}\(aq\(ga do - echo \(dqborg \-r repo1 export\-tar \-\-tar\-format=BORG $A \- | borg \-r repo2 import\-tar \-\-timestamp=$T $A \-\(dq + echo \(dqborg \-r repo1 export\-tar \-\-tar\-format=BORG aid:$I \- | borg \-r repo2 import\-tar \-\-timestamp=$T $N \-\(dq done .ft P .fi diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index 0658c603d0..179234cdee 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -27,12 +27,12 @@ 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 .. -.TH "BORG-INFO" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-INFO" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-info \- Show archive details such as disk space used .SH SYNOPSIS .sp -borg [common options] info [options] +borg [common options] info [options] [NAME] .SH DESCRIPTION .sp This command displays detailed information about the specified archive. @@ -48,6 +48,12 @@ All archives / deduplicated size = amount of data stored in the repo .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B NAME +specify the archive name +.UNINDENT .SS optional arguments .INDENT 0.0 .TP @@ -87,8 +93,8 @@ consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. .sp .nf .ft C -$ borg info Tuesday2022\-06\-25T20:51:39 -Archive name: Tuesday2022\-06\-25T20:51:39 +$ borg info aid:f7dea078 +Archive name: source\-backup Archive fingerprint: f7dea0788dfc026cc2be1c0f5b94beb4e4084eb3402fc40c38d8719b1bf2d943 Comment: Hostname: mba2020 @@ -96,7 +102,7 @@ Username: tw Time (start): Sat, 2022\-06\-25 20:51:40 Time (end): Sat, 2022\-06\-25 20:51:40 Duration: 0.03 seconds -Command line: /Users/tw/w/borg\-env/bin/borg \-r path/to/repo create \-\-stats \(aqTuesday{now}\(aq src \-\-progress +Command line: /usr/bin/borg \-r path/to/repo create source\-backup src Utilization of maximum supported archive size: 0% Number of files: 244 Original size: 13.80 MB diff --git a/docs/man/borg-key-change-location.1 b/docs/man/borg-key-change-location.1 index b2563314bd..a4b7cb59cd 100644 --- a/docs/man/borg-key-change-location.1 +++ b/docs/man/borg-key-change-location.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-KEY-CHANGE-LOCATION" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-KEY-CHANGE-LOCATION" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-key-change-location \- Change repository key location .SH SYNOPSIS diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 7afab03442..14176f3c27 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-key-change-passphrase \- Change repository key file passphrase .SH SYNOPSIS diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index 624c40dfe0..f131322cfa 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-KEY-EXPORT" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-KEY-EXPORT" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-key-export \- Export the repository key for backup .SH SYNOPSIS diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index 3e7cf556b0..8af5c8cacf 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-KEY-IMPORT" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-KEY-IMPORT" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-key-import \- Import the repository key from backup .SH SYNOPSIS diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index fad3a67b64..b6408e552a 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-KEY" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-KEY" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-key \- Manage a keyfile or repokey of a repository .SH SYNOPSIS diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index d12d78b378..6278b2cb38 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-LIST" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-LIST" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-list \- List archive contents .SH SYNOPSIS diff --git a/docs/man/borg-match-archives.1 b/docs/man/borg-match-archives.1 index 4c71ece08e..5bf867b24b 100644 --- a/docs/man/borg-match-archives.1 +++ b/docs/man/borg-match-archives.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-MATCH-ARCHIVES" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-MATCH-ARCHIVES" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-match-archives \- Details regarding match-archives .SH DESCRIPTION diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index 7559e1f3b1..ea9a9bb617 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-MOUNT" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-MOUNT" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-mount \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index dbf37c0972..b7c6f1cc28 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-PATTERNS" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-PATTERNS" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns .SH DESCRIPTION diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index 3efeea3006..b8731d69b9 100644 --- a/docs/man/borg-placeholders.1 +++ b/docs/man/borg-placeholders.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-PLACEHOLDERS" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-PLACEHOLDERS" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-placeholders \- Details regarding placeholders .SH DESCRIPTION diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index c6150c1983..fc5f9ca086 100644 --- a/docs/man/borg-prune.1 +++ b/docs/man/borg-prune.1 @@ -27,12 +27,12 @@ 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 .. -.TH "BORG-PRUNE" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-PRUNE" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-prune \- Prune repository archives according to specified rules .SH SYNOPSIS .sp -borg [common options] prune [options] +borg [common options] prune [options] [NAME] .SH DESCRIPTION .sp The prune command prunes a repository by deleting all archives not matching @@ -45,17 +45,18 @@ certain number of historic backups. This retention policy is commonly referred t \fI\%GFS\fP (Grandfather\-father\-son) backup rotation scheme. .sp -If you use \-\-match\-archives (\-a), then only archives that match the pattern are -considered for deletion and only those archives count towards the totals -specified by the rules. +The recommended way to use prune is to give the archive series name to it via the +NAME argument (assuming you have the same name for all archives in a series). +Alternatively, you can also use \-\-match\-archives (\-a), then only archives that +match the pattern are considered for deletion and only those archives count +towards the totals specified by the rules. Otherwise, \fIall\fP archives in the repository are candidates for deletion! There is no automatic distinction between archives representing different contents. These need to be distinguished by specifying matching globs. .sp -If you have multiple sequences of archives with different data sets (e.g. +If you have multiple series of archives with different data sets (e.g. from different machines) in one shared repository, use one prune call per -data set that matches only the respective archives using the \-\-match\-archives -(\-a) option. +series. .sp The \fB\-\-keep\-within\fP option takes an argument of the form \(dq\(dq, where char is \(dqH\(dq, \(dqd\(dq, \(dqw\(dq, \(dqm\(dq, \(dqy\(dq. For example, \fB\-\-keep\-within 2d\fP means @@ -86,6 +87,12 @@ the \fBborg repo\-list\fP description for more details about the format string). .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B NAME +specify the archive name +.UNINDENT .SS optional arguments .INDENT 0.0 .TP @@ -155,12 +162,21 @@ Be careful, prune is a potentially dangerous command, it will remove backup archives. .sp The default of prune is to apply to \fBall archives in the repository\fP unless -you restrict its operation to a subset of the archives using \fB\-a\fP / \fB\-\-match\-archives\fP\&. +you restrict its operation to a subset of the archives. +.sp +The recommended way to name archives (with \fBborg create\fP) is to use the +identical archive name within a series of archives. Then you can simply give +that name to prune also, so it operates just on that series of archives. +.sp +Alternatively, you can use \fB\-a\fP / \fB\-\-match\-archives\fP to do a match on the +archive names to select some of them. When using \fB\-a\fP, be careful to choose a good pattern \- e.g. do not use a prefix \(dqfoo\(dq if you do not also want to match \(dqfoobar\(dq. .sp It is strongly recommended to always run \fBprune \-v \-\-list \-\-dry\-run ...\fP first so you will see what it would do without it actually doing anything. +.sp +Don\(aqt forget to run \fBborg compact \-v\fP after prune to actually free disk space. .INDENT 0.0 .INDENT 3.5 .sp @@ -170,11 +186,12 @@ first so you will see what it would do without it actually doing anything. # Do a dry\-run without actually deleting anything. $ borg prune \-v \-\-list \-\-dry\-run \-\-keep\-daily=7 \-\-keep\-weekly=4 -# Same as above but only apply to archive names starting with the hostname +# Similar as above but only apply to the archive series named \(aq{hostname}\(aq: +$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \(aq{hostname}\(aq + +# Similar as above but apply to archive names starting with the hostname # of the machine followed by a \(dq\-\(dq character: $ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-a \(aqsh:{hostname}\-*\(aq -# actually free disk space: -$ borg compact # Keep 7 end of day, 4 additional end of week archives, # and an end of month archive for every month: diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index 0929c14933..941b2ca4ab 100644 --- a/docs/man/borg-recreate.1 +++ b/docs/man/borg-recreate.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-RECREATE" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-RECREATE" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-recreate \- Re-create archives .SH SYNOPSIS @@ -155,7 +155,7 @@ consider archives older than (now \- TIMESPAN), e.g. 7d or 12m. consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. .TP .BI \-\-target \ TARGET -create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive) +create a new archive with the name ARCHIVE, do not replace existing archive .TP .BI \-\-comment \ COMMENT add a comment text to the archive diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index 4fbe59c3a5..d90eb7694b 100644 --- a/docs/man/borg-rename.1 +++ b/docs/man/borg-rename.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-RENAME" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-RENAME" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-rename \- Rename an existing archive .SH SYNOPSIS diff --git a/docs/man/borg-repo-compress.1 b/docs/man/borg-repo-compress.1 index 808ba3367d..653d6086a3 100644 --- a/docs/man/borg-repo-compress.1 +++ b/docs/man/borg-repo-compress.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-REPO-COMPRESS" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-REPO-COMPRESS" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-repo-compress \- Repository (re-)compression .SH SYNOPSIS diff --git a/docs/man/borg-repo-create.1 b/docs/man/borg-repo-create.1 index 1e401b301f..44bc3e3f39 100644 --- a/docs/man/borg-repo-create.1 +++ b/docs/man/borg-repo-create.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-REPO-CREATE" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-REPO-CREATE" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-repo-create \- Create a new, empty repository .SH SYNOPSIS diff --git a/docs/man/borg-repo-delete.1 b/docs/man/borg-repo-delete.1 index 1dcaee09ac..eb963ac7fa 100644 --- a/docs/man/borg-repo-delete.1 +++ b/docs/man/borg-repo-delete.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-REPO-DELETE" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-REPO-DELETE" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-repo-delete \- Delete a repository .SH SYNOPSIS diff --git a/docs/man/borg-repo-info.1 b/docs/man/borg-repo-info.1 index 481d3f8c7a..7479eab10c 100644 --- a/docs/man/borg-repo-info.1 +++ b/docs/man/borg-repo-info.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-REPO-INFO" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-REPO-INFO" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-repo-info \- Show repository infos .SH SYNOPSIS diff --git a/docs/man/borg-repo-list.1 b/docs/man/borg-repo-list.1 index a1e9f4582b..a6256618f6 100644 --- a/docs/man/borg-repo-list.1 +++ b/docs/man/borg-repo-list.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-REPO-LIST" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-REPO-LIST" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-repo-list \- List the archives contained in a repository .SH SYNOPSIS diff --git a/docs/man/borg-repo-space.1 b/docs/man/borg-repo-space.1 index ff5393f946..9278a31f20 100644 --- a/docs/man/borg-repo-space.1 +++ b/docs/man/borg-repo-space.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-REPO-SPACE" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-REPO-SPACE" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-repo-space \- Manage reserved space in repository .SH SYNOPSIS diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 index f2a480a52e..662f287cfc 100644 --- a/docs/man/borg-serve.1 +++ b/docs/man/borg-serve.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-SERVE" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-SERVE" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-serve \- Start in server mode. This command is usually not used manually. .SH SYNOPSIS diff --git a/docs/man/borg-transfer.1 b/docs/man/borg-transfer.1 index 21cb199b1f..95058fdbf4 100644 --- a/docs/man/borg-transfer.1 +++ b/docs/man/borg-transfer.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-TRANSFER" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-TRANSFER" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-transfer \- archives transfer from other repository, optionally upgrade data format .SH SYNOPSIS diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index 6482d20d91..93d8e0e842 100644 --- a/docs/man/borg-umount.1 +++ b/docs/man/borg-umount.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-UMOUNT" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-UMOUNT" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-umount \- un-mount the FUSE filesystem .SH SYNOPSIS diff --git a/docs/man/borg-version.1 b/docs/man/borg-version.1 index fa3fbaec23..71f1dc9e79 100644 --- a/docs/man/borg-version.1 +++ b/docs/man/borg-version.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-VERSION" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-VERSION" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-version \- Display the borg client / borg server version .SH SYNOPSIS diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index ad997ea85f..b9cce8e259 100644 --- a/docs/man/borg-with-lock.1 +++ b/docs/man/borg-with-lock.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG-WITH-LOCK" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG-WITH-LOCK" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg-with-lock \- run a user specified command with the repository lock held .SH SYNOPSIS diff --git a/docs/man/borg.1 b/docs/man/borg.1 index 9398180fa0..dfee5fed59 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORG" 1 "2024-09-09" "" "borg backup tool" +.TH "BORG" 1 "2024-09-26" "" "borg backup tool" .SH NAME borg \- deduplicating and encrypting backup tool .SH SYNOPSIS @@ -67,25 +67,25 @@ $ borg \-r /path/to/repo repo\-create \-\-encryption=repokey\-aes\-ocb .UNINDENT .IP 2. 3 Back up the \fB~/src\fP and \fB~/Documents\fP directories into an archive called -\fIMonday\fP: +\fIdocs\fP: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C -$ borg \-r /path/to/repo create Monday ~/src ~/Documents +$ borg \-r /path/to/repo create docs ~/src ~/Documents .ft P .fi .UNINDENT .UNINDENT .IP 3. 3 -The next day create a new archive called \fITuesday\fP: +The next day create a new archive using the same archive name: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C -$ borg \-r /path/to/repo create \-\-stats Tuesday ~/src ~/Documents +$ borg \-r /path/to/repo create \-\-stats docs ~/src ~/Documents .ft P .fi .UNINDENT @@ -101,7 +101,7 @@ size (the amount of unique data not shared with other archives): .nf .ft C Repository: /path/to/repo -Archive name: Tuesday +Archive name: docs Archive fingerprint: bcd1b53f9b4991b7afc2b339f851b7ffe3c6d030688936fe4552eccc1877718d Time (start): Sat, 2022\-06\-25 20:21:43 Time (end): Sat, 2022\-06\-25 20:21:43 @@ -122,20 +122,20 @@ List all archives in the repository: .nf .ft C $ borg \-r /path/to/repo repo\-list -Monday Sat, 2022\-06\-25 20:21:14 [b80e24d2...b179f298] -Tuesday Sat, 2022\-06\-25 20:21:43 [bcd1b53f...1877718d] +docs Sat, 2022\-06\-25 20:21:14 [b80e24d2...b179f298] +docs Sat, 2022\-06\-25 20:21:43 [bcd1b53f...1877718d] .ft P .fi .UNINDENT .UNINDENT .IP 5. 3 -List the contents of the \fIMonday\fP archive: +List the contents of the first archive: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C -$ borg \-r /path/to/repo list Monday +$ borg \-r /path/to/repo list aid:b80e24d2 drwxr\-xr\-x user group 0 Mon, 2016\-02\-15 18:22:30 home/user/Documents \-rw\-r\-\-r\-\- user group 7961 Mon, 2016\-02\-15 18:22:30 home/user/Documents/Important.doc \&... @@ -144,34 +144,32 @@ drwxr\-xr\-x user group 0 Mon, 2016\-02\-15 18:22:30 home/user/Docume .UNINDENT .UNINDENT .IP 6. 3 -Restore the \fIMonday\fP archive by extracting the files relative to the current directory: +Restore the first archive by extracting the files relative to the current directory: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C -$ borg \-r /path/to/repo extract Monday +$ borg \-r /path/to/repo extract aid:b80e24d2 .ft P .fi .UNINDENT .UNINDENT .IP 7. 3 -Delete the \fIMonday\fP archive (please note that this does \fBnot\fP free repo disk space): +Delete the first archive (please note that this does \fBnot\fP free repo disk space): .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C -$ borg \-r /path/to/repo delete \-a Monday +$ borg \-r /path/to/repo delete aid:b80e24d2 .ft P .fi .UNINDENT .UNINDENT .sp -Please note the \fB\-a\fP option here (short for \fB\-\-match\-archives\fP) which enables you -to give a pattern to delete multiple archives, like \fB\-a \(aqsh:oldcrap\-*\(aq\fP\&. -You can also combine this with \fB\-\-first\fP, \fB\-\-last\fP and \fB\-\-sort\-by\fP\&. -Be careful, always first use with \fB\-\-dry\-run\fP and \fB\-\-list\fP! +Be careful if you use an archive NAME (and not an archive ID), that might match multiple archives! +Always first use with \fB\-\-dry\-run\fP and \fB\-\-list\fP! .IP 8. 3 Recover disk space by compacting the segment files in the repo: .INDENT 3.0 @@ -179,7 +177,7 @@ Recover disk space by compacting the segment files in the repo: .sp .nf .ft C -$ borg \-r /path/to/repo compact +$ borg \-r /path/to/repo compact \-v .ft P .fi .UNINDENT @@ -232,7 +230,7 @@ Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style .sp \fBRemote repositories\fP accessed via ssh \fI\%user@host\fP: .sp -\fBssh://user@host:port/path/to/repo\fP \- absolute path\(ga +\fBssh://user@host:port/path/to/repo\fP \- absolute path .sp \fBssh://user@host:port/./path/to/repo\fP \- path relative to current directory .sp @@ -240,7 +238,13 @@ Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style .sp \fBRemote repositories\fP accessed via sftp: .sp -\fBsftp://user@host:port/path/to/repo\fP \- absolute path\(ga +\fBsftp://user@host:port/path/to/repo\fP \- absolute path +.sp +For ssh and sftp URLs, the \fBuser@\fP and \fB:port\fP parts are optional. +.sp +\fBRemote repositories\fP accessed via rclone: +.sp +\fBrclone://remote:path\fP .sp If you frequently need the same repo URL, it is a good idea to set the \fBBORG_REPO\fP environment variable to set a default for the repo URL: @@ -462,8 +466,7 @@ cache entries for backup sources other than the current sources. .TP .B BORG_FILES_CACHE_TTL When set to a numeric value, this determines the maximum \(dqtime to live\(dq for the files cache -entries (default: 20). The files cache is used to determine quickly whether a file is unchanged. -The FAQ explains this more detailed in: \fIalways_chunking\fP +entries (default: 2). The files cache is used to determine quickly whether a file is unchanged. .TP .B BORG_USE_CHUNKS_ARCHIVE When set to no (default: yes), the \fBchunks.archive.d\fP folder will not be used. This reduces @@ -491,20 +494,6 @@ given order, e.g.: \fBnone\fP: do not try to load an implementation .UNINDENT .TP -.B BORG_CACHE_IMPL -Choose the implementation for the clientside cache, choose one of: -.INDENT 7.0 -.IP \(bu 2 -\fBadhoc\fP: builds a non\-persistent chunks cache by querying the repo. Chunks cache contents -are somewhat sloppy for already existing chunks, concerning their refcount (\(dqinfinite\(dq) and -size (0). No files cache (slow, will chunk all input files). DEPRECATED. -.IP \(bu 2 -\fBadhocwithfiles\fP: Like \fBadhoc\fP, but with a persistent files cache. Default implementation. -.IP \(bu 2 -\fBcli\fP: Determine the cache implementation from cli options. Without special options, will -usually end up with the \fBlocal\fP implementation. -.UNINDENT -.TP .B BORG_SELFTEST This can be used to influence borg\(aqs builtin self\-tests. The default is to execute the tests at the beginning of each borg command invocation. @@ -724,7 +713,7 @@ and re\-write segment files to free space. .IP \(bu 2 In future, easier to adapt to other kinds of storage: borgstore\(aqs backends are quite simple to implement. -A \fBsftp:\fP backend already exists, cloud storage might be easy to add. +\fBsftp:\fP and \fBrclone:\fP backends already exists, others might be easy to add. .IP \(bu 2 Parallel repository access with less locking is easier to implement. .UNINDENT diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1 index 288447350d..dfce86f717 100644 --- a/docs/man/borgfs.1 +++ b/docs/man/borgfs.1 @@ -27,7 +27,7 @@ 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 .. -.TH "BORGFS" 1 "2024-09-09" "" "borg backup tool" +.TH "BORGFS" 1 "2024-09-26" "" "borg backup tool" .SH NAME borgfs \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index 7924e4adfc..f6b0a4a74e 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -31,8 +31,6 @@ borg create +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--json`` | output stats as JSON. Implies ``--stats``. | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--prefer-adhoc-cache`` | experimental: prefer AdHocCache (w/o files cache) over AdHocWithFilesCache (with files cache). | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--stdin-name NAME`` | use NAME in archive for stdin data (default: 'stdin') | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--stdin-user USER`` | set user USER in archive for stdin data (default: do not store user/uid) | @@ -128,7 +126,6 @@ borg create --list output verbose list of items (files, dirs, ...) --filter STATUSCHARS only display items with the given status characters (see description) --json output stats as JSON. Implies ``--stats``. - --prefer-adhoc-cache experimental: prefer AdHocCache (w/o files cache) over AdHocWithFilesCache (with files cache). --stdin-name NAME use NAME in archive for stdin data (default: 'stdin') --stdin-user USER set user USER in archive for stdin data (default: do not store user/uid) --stdin-group GROUP set group GROUP in archive for stdin data (default: do not store group/gid) @@ -195,7 +192,9 @@ 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. -The archive name needs to be unique. +The archive name does NOT need to be unique, you can and should use the same +name for a series of archives. The unique archive identifier is its ID (hash) +and you can abbreviate the ID as long as it is unique. In the archive name, you may use the following placeholders: {now}, {utcnow}, {fqdn}, {hostname}, {user} and some others. diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc index 688bce06e4..79c5378f30 100644 --- a/docs/usage/delete.rst.inc +++ b/docs/usage/delete.rst.inc @@ -6,12 +6,16 @@ borg delete ----------- .. code-block:: none - borg [common options] delete [options] + borg [common options] delete [options] [NAME] .. only:: html .. class:: borg-options-table + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | **positional arguments** | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | | ``NAME`` | specify the archive name | +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ | **optional arguments** | +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ @@ -52,6 +56,8 @@ borg delete .. only:: latex + NAME + specify the archive name optional arguments diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index f96396b610..4833db2dc8 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -342,8 +342,9 @@ If literal curly braces need to be used, double them for escaping:: Examples:: - borg create '{hostname}-{user}' ... - borg prune '{hostname}-{user}' ... + borg create /path/to/repo::{hostname}-{user}-{utcnow} ... + borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S%z} ... + borg prune -a 'sh:{hostname}-*' ... .. note:: systemd uses a difficult, non-standard syntax for command lines in unit files (refer to diff --git a/docs/usage/info.rst.inc b/docs/usage/info.rst.inc index 3410283354..d5c913dc8d 100644 --- a/docs/usage/info.rst.inc +++ b/docs/usage/info.rst.inc @@ -6,12 +6,16 @@ borg info --------- .. code-block:: none - borg [common options] info [options] + borg [common options] info [options] [NAME] .. only:: html .. class:: borg-options-table + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | **positional arguments** | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | | ``NAME`` | specify the archive name | +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ | **optional arguments** | +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ @@ -50,6 +54,8 @@ borg info .. only:: latex + NAME + specify the archive name optional arguments diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index e3f85eaa19..241a051690 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -6,12 +6,16 @@ borg prune ---------- .. code-block:: none - borg [common options] prune [options] + borg [common options] prune [options] [NAME] .. only:: html .. class:: borg-options-table + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | **positional arguments** | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``NAME`` | specify the archive name | +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ | **optional arguments** | +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ @@ -70,6 +74,8 @@ borg prune .. only:: latex + NAME + specify the archive name optional arguments @@ -113,17 +119,18 @@ certain number of historic backups. This retention policy is commonly referred t `GFS `_ (Grandfather-father-son) backup rotation scheme. -If you use --match-archives (-a), then only archives that match the pattern are -considered for deletion and only those archives count towards the totals -specified by the rules. +The recommended way to use prune is to give the archive series name to it via the +NAME argument (assuming you have the same name for all archives in a series). +Alternatively, you can also use --match-archives (-a), then only archives that +match the pattern are considered for deletion and only those archives count +towards the totals specified by the rules. Otherwise, *all* archives in the repository are candidates for deletion! There is no automatic distinction between archives representing different contents. These need to be distinguished by specifying matching globs. -If you have multiple sequences of archives with different data sets (e.g. +If you have multiple series of archives with different data sets (e.g. from different machines) in one shared repository, use one prune call per -data set that matches only the respective archives using the --match-archives -(-a) option. +series. The ``--keep-within`` option takes an argument of the form "", where char is "H", "d", "w", "m", "y". For example, ``--keep-within 2d`` means diff --git a/docs/usage/recreate.rst.inc b/docs/usage/recreate.rst.inc index 46f0638c4d..cc123dc922 100644 --- a/docs/usage/recreate.rst.inc +++ b/docs/usage/recreate.rst.inc @@ -65,7 +65,7 @@ borg recreate +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. | +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--target TARGET`` | create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive) | + | | ``--target TARGET`` | create a new archive with the name ARCHIVE, do not replace existing archive | +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--comment COMMENT`` | add a comment text to the archive | +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -119,7 +119,7 @@ borg recreate --newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. --older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d or 12m. --newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. - --target TARGET create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive) + --target TARGET create a new archive with the name ARCHIVE, do not replace existing archive --comment COMMENT add a comment text to the archive --timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. -C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.