diff --git a/docs/man/borg-analyze.1 b/docs/man/borg-analyze.1 index 9b55b282e..f07406cb0 100644 --- a/docs/man/borg-analyze.1 +++ b/docs/man/borg-analyze.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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-ANALYZE" "1" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-analyze" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-analyze \- Analyzes archives. .SH SYNOPSIS .sp @@ -85,7 +86,6 @@ consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m. .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-benchmark-cpu.1 b/docs/man/borg-benchmark-cpu.1 index b013c59f8..b155602c3 100644 --- a/docs/man/borg-benchmark-cpu.1 +++ b/docs/man/borg-benchmark-cpu.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-benchmark-cpu" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-benchmark-cpu \- Benchmark CPU-bound operations. .SH SYNOPSIS .sp @@ -48,10 +49,15 @@ enough free memory so there will be no slow down due to paging activity .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. +.SS options +.INDENT 0.0 +.TP +.B \-\-json +format output as JSON +.UNINDENT .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index 43f51bc61..763ed958e 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-benchmark-crud" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. .SH SYNOPSIS .sp @@ -89,10 +90,15 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .B PATH path where to create benchmark input data .UNINDENT +.SS options +.INDENT 0.0 +.TP +.B \-\-json\-lines +Format output as JSON Lines. +.UNINDENT .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index fe24e72e5..bf5c019f9 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-benchmark" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-benchmark \- benchmark command .SH SYNOPSIS .nf @@ -42,7 +43,6 @@ These commands do various benchmarks. .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-benchmark\-crud(1)\fP, \fIborg\-benchmark\-cpu(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index ef72d2aa5..f907199ce 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-break-lock" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-break-lock \- Breaks the repository lock (for example, if it was left by a dead Borg process). .SH SYNOPSIS .sp @@ -44,7 +45,6 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index da2cc8868..a0b3dcf46 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-check" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-check \- Checks repository consistency. .SH SYNOPSIS .sp @@ -44,7 +45,7 @@ the file magic headers, and both the metadata and data of all objects in the repository. The read data is checked by size and hash. Bit rot and other types of accidental damage can be detected this way. Running the repository check can be split into multiple partial checks using \fB\-\-max\-duration\fP\&. -When checking an remote repository, please note that the checks run on +When checking an \% remote repository, please note that the checks run on the server and do not cause significant network traffic. .IP 2. 3 Checking consistency and correctness of the archive metadata and optionally @@ -105,7 +106,7 @@ The check command is a read\-only task by default. If any corruption is found, Borg will report the issue and proceed with checking. To actually repair the issues found, pass \fB\-\-repair\fP\&. .sp -\fBNOTE:\fP +\fBNote:\fP .INDENT 0.0 .INDENT 3.5 \fB\-\-repair\fP is a \fBPOTENTIALLY DANGEROUS FEATURE\fP and might lead to data @@ -197,7 +198,6 @@ consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m. .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index 5bd73fb66..f38ee3cd1 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-common" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-common \- Common options of Borg commands .SH SYNOPSIS .INDENT 0.0 @@ -99,7 +100,6 @@ repository to use .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1 index 44f48bd49..d73f1cf94 100644 --- a/docs/man/borg-compact.1 +++ b/docs/man/borg-compact.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-compact" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-compact \- Collects garbage in the repository. .SH SYNOPSIS .sp @@ -103,7 +104,6 @@ $ borg compact .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-completion.1 b/docs/man/borg-completion.1 index 1d6feaf58..036259284 100644 --- a/docs/man/borg-completion.1 +++ b/docs/man/borg-completion.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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-COMPLETION" "1" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-completion" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-completion \- Output shell completion script for the given shell. .SH SYNOPSIS .sp @@ -70,7 +71,6 @@ eval \(dq$(borg completion zsh)\(dq .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index 1c7db62b2..b75c0ac11 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-compression" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-compression \- Details regarding compression .SH DESCRIPTION .sp @@ -152,7 +153,7 @@ Example probabilities for SPEC \fB1\fP: .UNINDENT .sp Uses the Padmé algorithm to deterministically pad the compressed size to a sum of -powers of 2, limiting overhead to 12%. See for details. +powers of 2, limiting overhead to 12%. See \% for details. .UNINDENT .sp Examples: @@ -174,7 +175,6 @@ borg create \-\-compression obfuscate,250,zstd,3 ... .EE .UNINDENT .UNINDENT -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index 8493f09d3..973f39893 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-create" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-create \- Creates a new archive. .SH SYNOPSIS .sp @@ -53,6 +54,8 @@ 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 \fB\-\-tags\fP option can be used to add a list of tags to the new archive. +.sp 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. @@ -111,9 +114,10 @@ well\-meant, but in both cases mtime\-based cache modes can be problematic. .B The \fB\-\-files\-changed\fP option controls how Borg detects if a file has changed during backup: .INDENT 7.0 .IP \(bu 2 -ctime (default): Use ctime to detect changes. This is the safest option. +ctime (default on POSIX): Use ctime to detect changes. This is the safest option. +Not supported on Windows (ctime is file creation time there). .IP \(bu 2 -mtime: Use mtime to detect changes. +mtime (default on Windows): Use mtime to detect changes. .IP \(bu 2 disabled: Disable the \(dqfile has changed while we backed it up\(dq detection completely. This is not recommended unless you know what you\(aqre doing, as it could lead to @@ -190,6 +194,9 @@ read DELIM\-separated list of paths to back up from stdin. All control is extern .B \-\-paths\-from\-command interpret PATH as command and treat its output as \fB\-\-paths\-from\-stdin\fP .TP +.B \-\-paths\-from\-shell\-command +interpret PATH as shell command and treat its output as \fB\-\-paths\-from\-stdin\fP +.TP .BI \-\-paths\-delimiter \ DELIM set path delimiter for \fB\-\-paths\-from\-stdin\fP and \fB\-\-paths\-from\-command\fP (default: \fB\en\fP) .UNINDENT @@ -209,7 +216,7 @@ include/exclude paths matching PATTERN read include/exclude patterns from PATTERNFILE, one per line .TP .B \-\-exclude\-caches -exclude directories that contain a CACHEDIR.TAG file ( ) +exclude directories that contain a CACHEDIR.TAG file (\%) .TP .BI \-\-exclude\-if\-present \ NAME exclude directories that are tagged by containing a filesystem object with the given NAME @@ -251,7 +258,7 @@ detect sparse holes in input (supported only by fixed chunker) operate files cache in MODE. default: ctime,size,inode .TP .BI \-\-files\-changed \ MODE -specify how to detect if a file has changed during backup (ctime, mtime, disabled). default: ctime +specify how to detect if a file has changed during backup (ctime, mtime, disabled). default: ctime (on Windows: mtime, because ctime is file creation time there). .TP .B \-\-read\-special open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files. @@ -270,10 +277,19 @@ specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BI .TP .BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION select compression algorithm, see the output of the \(dqborg help compression\(dq command for details. +.TP +.BI \-\-hostname \ HOSTNAME +explicitly set hostname for the archive +.TP +.BI \-\-username \ USERNAME +explicitly set username for the archive +.TP +.BI \-\-tags \ TAG +add tags to archive (comma\-separated or multiple arguments) .UNINDENT .SH EXAMPLES .sp -\fBNOTE:\fP +\fBNote:\fP .INDENT 0.0 .INDENT 3.5 Archive series and performance: In Borg 2, archives that share the same NAME form an \(dqarchive series\(dq. @@ -364,6 +380,9 @@ $ borg create \(aqdaily\-projectA\(aq projectA $ find ~ \-size \-1000k | borg create \-\-paths\-from\-stdin small\-files\-only # Use \-\-paths\-from\-command with find to back up files from only a given user $ borg create \-\-paths\-from\-command joes\-files \-\- find /srv/samba/shared \-user joe +# Use \-\-paths\-from\-shell\-command with find to back up a few files from only a given user \- +# BE VERY CAREFUL AND ONLY USE TRUSTED INPUT FOR THE SHELL COMMAND! +$ borg create \-\-paths\-from\-shell\-command some\-of\-joes\-files \-\- \(dqfind /srv/samba/shared \-user joe | head\(dq # Use \-\-paths\-from\-stdin with \-\-paths\-delimiter (for example, for filenames with newlines in them) $ find ~ \-size \-1000k \-print0 | borg create \e \-\-paths\-from\-stdin \e @@ -504,15 +523,14 @@ there (optionally considering include/exclude rules). .sp If you need more control and you want to give every single fs object path to borg (maybe implementing your own recursion or your own rules), you can use -\fB\-\-paths\-from\-stdin\fP or \fB\-\-paths\-from\-command\fP (with the latter, borg will -fail to create an archive should the command fail). +\fB\-\-paths\-from\-stdin\fP, \fB\-\-paths\-from\-command\fP or \fB\-\-paths\-from\-shell\-command\fP +(with the latter two, borg will fail to create an archive should the command fail). .sp Borg supports paths with the slashdot hack to strip path prefixes here also. So, be careful not to unintentionally trigger that. .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, \fIborg\-repo\-create(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index ad20352d5..09fad9831 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-delete" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-delete \- Deletes archives. .SH SYNOPSIS .sp @@ -124,7 +125,6 @@ $ borg delete \-\-list \-\-dry\-run \-a \(aqsh:*\-May\-*\(aq .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-compact(1)\fP, \fIborg\-repo\-delete(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index 4fd5f0afe..4cbbdf407 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-diff" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-diff \- Finds differences between two archives. .SH SYNOPSIS .sp @@ -120,8 +121,7 @@ added 0 B file4 .SH NOTES .SS The FORMAT specifier syntax .sp -The \fB\-\-format\fP option uses Python\(aqs format string syntax -\&. +The \fB\-\-format\fP option uses Python\(aqs format string syntax \%\&. .sp Examples: .INDENT 0.0 @@ -142,22 +142,13 @@ $ borg diff \-\-format \(aq{content:>30} {path}{NL}\(aq ArchiveFoo ArchiveBar .UNINDENT .sp The following keys are always available: -.INDENT 0.0 -.IP \(bu 2 -NEWLINE: OS dependent line separator -.IP \(bu 2 -NL: alias of NEWLINE -.IP \(bu 2 -NUL: NUL character for creating print0 / xargs \-0 like output -.IP \(bu 2 -SPACE: space character -.IP \(bu 2 -TAB: tab character -.IP \(bu 2 -CR: carriage return character -.IP \(bu 2 -LF: line feed character -.UNINDENT +\- NEWLINE: OS dependent line separator +\- NL: alias of NEWLINE +\- NUL: NUL character for creating print0 / xargs \-0 like output +\- SPACE: space character +\- TAB: tab character +\- CR: carriage return character +\- LF: line feed character .sp Keys available only when showing differences between archives: .INDENT 0.0 @@ -264,7 +255,6 @@ parameters. If so, only chunk IDs are compared, which is very fast. .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index 6e23804db..ca1a5747f 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -1,5 +1,6 @@ '\" t -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -28,8 +29,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-export-tar" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-export-tar \- Export archive contents as a tarball .SH SYNOPSIS .sp @@ -157,7 +158,6 @@ Remove the specified number of leading path elements. Paths with fewer elements .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index 22099a4d5..8749fc332 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-extract" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-extract \- Extracts archive contents. .SH SYNOPSIS .sp @@ -53,7 +54,7 @@ decrypting, and decompressing. \fB\-\-progress\fP can be slower than no progress display, since it makes one additional pass over the archive metadata. .sp -\fBNOTE:\fP +\fBNote:\fP .INDENT 0.0 .INDENT 3.5 Currently, extract always writes into the current working directory (\(dq.\(dq), @@ -155,7 +156,6 @@ $ borg extract \-\-stdout my\-sdx | dd of=/dev/sdx bs=10M .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-mount(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-import-tar.1 b/docs/man/borg-import-tar.1 index 76d999685..892a9cdf2 100644 --- a/docs/man/borg-import-tar.1 +++ b/docs/man/borg-import-tar.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-import-tar" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-import-tar \- Create a backup archive from a tarball .SH SYNOPSIS .sp @@ -205,7 +206,6 @@ no special sparse file support .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index 48848e315..b498903c7 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-info" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-info \- Show archive details such as disk space used .SH SYNOPSIS .sp @@ -112,7 +113,6 @@ Deduplicated size: 531 B .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-list(1)\fP, \fIborg\-diff(1)\fP, \fIborg\-repo\-info(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-key-change-location.1 b/docs/man/borg-key-change-location.1 index 741510143..0394bcf22 100644 --- a/docs/man/borg-key-change-location.1 +++ b/docs/man/borg-key-change-location.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-key-change-location" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-key-change-location \- Changes the repository key location. .SH SYNOPSIS .sp @@ -65,7 +66,6 @@ keep the key also at the current location (default: remove it) .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 43ad4afa6..54509529e 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-key-change-passphrase" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-key-change-passphrase \- Changes the repository key file passphrase. .SH SYNOPSIS .sp @@ -69,7 +70,23 @@ Enter new passphrase: Enter same passphrase again: Remember your passphrase. Your data will be inaccessible without it. Key updated - +.EE +.UNINDENT +.UNINDENT +.sp +\fBNote:\fP +.INDENT 0.0 +.INDENT 3.5 +The key file paths shown above are the defaults for Linux (\fB~/.config/borg/keys/\fP). +On macOS, key files are stored in \fB~/Library/Application Support/borg/keys/\fP\&. +On Windows, they are stored in \fBC:\eUsers\e\eAppData\eRoaming\eborg\ekeys\e\fP\&. +See \fIenv_vars\fP for details. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX # Import a previously\-exported key into the specified # key file (creating or overwriting the output key) # (keyfile repositories only) @@ -93,7 +110,6 @@ $ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change\-passphrase .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index e0e1c0649..738454c03 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,35 +28,41 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-key-export" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-key-export \- Exports the repository key for backup. .SH SYNOPSIS .sp borg [common options] key export [options] [PATH] .SH DESCRIPTION .sp +This command backs up the borg key. +.sp If repository encryption is used, the repository is inaccessible -without the key. This command allows one to back up this essential key. +without the borg key (and the passphrase that protects the borg key). +If a repository is not encrypted, but authenticated, the borg key is +still needed to access the repository normally. +.sp +For repositories using \fBkeyfile\fP encryption the key is kept locally +on the system that is capable of doing backups. To guard against loss +or corruption of this key, the key needs to be backed up independently +of the main data backup. +.sp +For repositories using \fBrepokey\fP encryption or \fBauthenticated\fP mode +the key is kept in the repository. A backup is thus not strictly needed, +but guards against the repository becoming inaccessible if the key is +corrupted or lost. +.sp Note that the backup produced does not include the passphrase itself (i.e. the exported key stays encrypted). In order to regain access to a repository, one needs both the exported key and the original passphrase. +Keep the exported key and the passphrase at safe places. .sp There are three backup formats. The normal backup format is suitable for digital storage as a file. The \fB\-\-paper\fP backup format is optimized for printing and typing in while importing, with per line checks to reduce problems with manual input. The \fB\-\-qr\-html\fP creates a printable HTML template with a QR code and a copy of the \fB\-\-paper\fP\-formatted key. -.sp -For repositories using keyfile encryption the key is saved locally -on the system that is capable of doing backups. To guard against loss -of this key, the key needs to be backed up independently of the main -data backup. -.sp -For repositories using the repokey encryption the key is saved in the -repository in the config file. A backup is thus not strictly needed, -but guards against the repository becoming inaccessible if the file -is damaged for some reason. .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. @@ -92,7 +99,6 @@ borg key export \-\-qr\-html encrypted\-key\-backup.html .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-key\-import(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index 948029bcf..2dd6c2e29 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-key-import" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-key-import \- Imports the repository key from backup. .SH SYNOPSIS .sp @@ -67,7 +68,6 @@ interactively import from a backup done with \fB\-\-paper\fP .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-key\-export(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index 86c2290ac..d2d8ba66b 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-key" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-key \- Manage the keyfile or repokey of a repository .SH SYNOPSIS .nf @@ -41,7 +42,6 @@ borg [common options] key change\-location ... .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP, \fIborg\-key\-change\-location(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index a37d04c3c..a037e23ee 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-list" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-list \- List archive contents. .SH SYNOPSIS .sp @@ -122,8 +123,7 @@ $ borg list archiveA \-\-pattern \(aq+ re:.ext$\(aq \-\-pattern \(aq\- re:^.*$\( .SH NOTES .SS The FORMAT specifier syntax .sp -The \fB\-\-format\fP option uses Python\(aqs format string syntax -\&. +The \fB\-\-format\fP option uses Python\(aqs format string syntax \%\&. .sp Examples: .INDENT 0.0 @@ -144,22 +144,13 @@ $ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{ .UNINDENT .sp The following keys are always available: -.INDENT 0.0 -.IP \(bu 2 -NEWLINE: OS dependent line separator -.IP \(bu 2 -NL: alias of NEWLINE -.IP \(bu 2 -NUL: NUL character for creating print0 / xargs \-0 like output -.IP \(bu 2 -SPACE: space character -.IP \(bu 2 -TAB: tab character -.IP \(bu 2 -CR: carriage return character -.IP \(bu 2 -LF: line feed character -.UNINDENT +\- NEWLINE: OS dependent line separator +\- NL: alias of NEWLINE +\- NUL: NUL character for creating print0 / xargs \-0 like output +\- SPACE: space character +\- TAB: tab character +\- CR: carriage return character +\- LF: line feed character .sp Keys available only when listing files in an archive: .INDENT 0.0 @@ -202,6 +193,8 @@ isoctime: file change time (ISO 8601 format) .IP \(bu 2 isoatime: file access time (ISO 8601 format) .IP \(bu 2 +fingerprint: Fingerprint of the file content (may have false negatives), format: H(conditions)\-H(chunk_ids) +.IP \(bu 2 blake2b .IP \(bu 2 blake2s @@ -237,7 +230,6 @@ extra: prepends {target} with \(dq \-> \(dq for soft links and \(dq link to \(dq .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-info(1)\fP, \fIborg\-diff(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-repo\-list(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-match-archives.1 b/docs/man/borg-match-archives.1 index cb8a1de48..157b1ce3b 100644 --- a/docs/man/borg-match-archives.1 +++ b/docs/man/borg-match-archives.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-match-archives" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-match-archives \- Details regarding match-archives .SH DESCRIPTION .sp @@ -59,8 +60,7 @@ Simple string match, must fully match exactly as given. .B Shell\-style patterns, selector \fBsh:\fP Match like on the shell, wildcards like \fI*\fP and \fI?\fP work. .TP -.B Regular expressions -, selector \fBre:\fP +.B Regular expressions \%, selector \fBre:\fP Full regular expression support. This is very powerful, but can also get rather complicated. .UNINDENT @@ -93,7 +93,6 @@ borg delete \-a \(aqtags:TAG1\(aq \-a \(aqtags:TAG2\(aq .EE .UNINDENT .UNINDENT -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index 71dbfa11c..ad158ed7e 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-mount" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-mount \- Mounts an archive or an entire repository as a FUSE filesystem. .SH SYNOPSIS .sp @@ -45,6 +46,11 @@ When mounting a repository, the top directories will be named like the archives and the directory structure below these will be loaded on\-demand from the repository when entering these directories, so expect some delay. .sp +Care should be taken, as Borg backs up symlinks as\-is. When an archive +or repository is mounted, it is possible to “jump” outside the mount point +by following a symlink. If this happens, files or directories (or versions of them) +that are not part of the archive or repository may appear to be within the mount point. +.sp Unless the \fB\-\-foreground\fP option is given, the command will run in the background until the filesystem is \fBunmounted\fP\&. .sp @@ -190,7 +196,6 @@ Remove the specified number of leading path elements. Paths with fewer elements .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-umount(1)\fP, \fIborg\-extract(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index 82165f0cd..74aff87a2 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-patterns" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-patterns \- Details regarding patterns .SH DESCRIPTION .sp @@ -67,6 +68,8 @@ start with \fBsrc\fP\&. .IP \(bu 2 When you back up relative paths like \fB\&../../src\fP, the archived paths start with \fBsrc\fP\&. +.IP \(bu 2 +On native Windows, archived absolute paths look like \fBC/Windows/System32\fP\&. .UNINDENT .UNINDENT .sp @@ -74,18 +77,19 @@ Borg supports different pattern styles. To define a non\-default style for a specific pattern, prefix it with two characters followed by a colon \(aq:\(aq (i.e. \fBfm:path/*\fP, \fBsh:path/**\fP). .sp +Note: Windows users must only use forward slashes in patterns, not backslashes. +.sp The default pattern style for \fB\-\-exclude\fP differs from \fB\-\-pattern\fP, see below. .INDENT 0.0 .TP -.B Fnmatch -, selector \fBfm:\fP +.B Fnmatch \%, selector \fBfm:\fP This is the default style for \fB\-\-exclude\fP and \fB\-\-exclude\-from\fP\&. These patterns use a variant of shell pattern syntax, with \(aq*\(aq matching any number of characters, \(aq?\(aq matching any single character, \(aq[...]\(aq matching any single character specified, including ranges, and \(aq[!...]\(aq matching any character not specified. For the purpose of these patterns, -the path separator (backslash for Windows and \(aq/\(aq on other systems) is not -treated specially. Wrap meta\-characters in brackets for a literal +the path separator (forward slash \(aq/\(aq) is not treated specially. +Wrap meta\-characters in brackets for a literal match (i.e. \fB[?]\fP to match the literal character \(aq?\(aq). For a path to match a pattern, the full path must match, or it must match from the start of the full path to just before a path separator. Except @@ -102,13 +106,10 @@ levels, \fB*\fP for matching zero or more arbitrary characters with the exception of any path separator, \fB{}\fP containing comma\-separated alternative patterns. A leading path separator is always removed. .TP -.B Regular expressions -, selector \fBre:\fP +.B Regular expressions \%, selector \fBre:\fP Unlike shell patterns, regular expressions are not required to match the full path and any substring match is sufficient. It is strongly recommended to -anchor patterns to the start (\(aq^\(aq), to the end (\(aq$\(aq) or both. Path -separators (backslash for Windows and \(aq/\(aq on other systems) in paths are -always normalized to a forward slash \(aq/\(aq before applying a pattern. +anchor patterns to the start (\(aq^\(aq), to the end (\(aq$\(aq) or both. .TP .B Path prefix, selector \fBpp:\fP This pattern style is useful to match whole subdirectories. The pattern @@ -132,7 +133,7 @@ Other include/exclude patterns that would normally match will be ignored. Same logic applies for exclude. .UNINDENT .sp -\fBNOTE:\fP +\fBNote:\fP .INDENT 0.0 .INDENT 3.5 \fBre:\fP, \fBsh:\fP and \fBfm:\fP patterns are all implemented on top of @@ -144,6 +145,26 @@ cannot supply \fBre:\fP patterns. Further, ensure that \fBsh:\fP and .UNINDENT .UNINDENT .sp +\fBNote:\fP +.INDENT 0.0 +.INDENT 3.5 +\fBWindows path handling\fP: All paths in Borg archives use forward slashes (\fB/\fP) +as path separators, regardless of the platform. When creating archives on Windows, +backslashes from filesystem paths are automatically converted to forward slashes. +.UNINDENT +.UNINDENT +.sp +\fBNote:\fP +.INDENT 0.0 +.INDENT 3.5 +\fBWindows reserved characters\fP: On Windows, when extracting archives created on +POSIX systems, paths may contain characters that are reserved from being used in +file or directory names (like: \fB< > : \(dq \e | ? *\fP). +These are replaced by characters in the unicode private use area (\fBU+F0xx\fP) like +the CIFS mapchars feature also does it. It won\(aqt be pretty, but at least it works. +.UNINDENT +.UNINDENT +.sp Exclusions can be passed via the command line option \fB\-\-exclude\fP\&. When used from within a shell, the patterns should be quoted to protect them from expansion. @@ -190,7 +211,6 @@ $ borg create \-e \(aq*.o\(aq archive / # not \(aq/home/user/importantjunk\(aq or \(aq/etc/junk\(aq: $ borg create \-e \(aqhome/*/junk\(aq archive / - # The contents of directories in \(aq/home\(aq are not backed up when their name # ends in \(aq.tmp\(aq $ borg create \-\-exclude \(aqre:^home/[^/]+\e.tmp/\(aq archive / @@ -289,7 +309,7 @@ This will list the considered files one per line, prefixed with a character that indicates the action (e.g. \(aqx\(aq for excluding, see \fBItem flags\fP in \fIborg create\fP usage docs). .sp -\fBNOTE:\fP +\fBNote:\fP .INDENT 0.0 .INDENT 3.5 It is possible that a subdirectory or file is matched while its parent @@ -372,7 +392,6 @@ R /home/susan .sp This allows you to share the same patterns between multiple repositories without needing to specify them on the command line. -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index a8612b3d0..9b8bd5e7f 100644 --- a/docs/man/borg-placeholders.1 +++ b/docs/man/borg-placeholders.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-placeholders" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-placeholders \- Details regarding placeholders .SH DESCRIPTION .sp @@ -47,13 +48,11 @@ The full name of the machine in reverse domain name notation. .TP .B {now} The current local date and time, by default in ISO\-8601 format. -You can also supply your own format string -, e.g. {now:%Y\-%m\-%d_%H:%M:%S} +You can also supply your own format string \%, e.g. {now:%Y\-%m\-%d_%H:%M:%S} .TP .B {utcnow} The current UTC date and time, by default in ISO\-8601 format. -You can also supply your own format string -, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S} +You can also supply your own format string \%, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S} .TP .B {user} The user name (or UID, if no name is available) of the user running borg. @@ -96,7 +95,7 @@ borg prune \-a \(aqsh:{hostname}\-*\(aq ... .UNINDENT .UNINDENT .sp -\fBNOTE:\fP +\fBNote:\fP .INDENT 0.0 .INDENT 3.5 systemd uses a difficult, non\-standard syntax for command lines in unit files (refer to @@ -109,7 +108,6 @@ double all percent signs (\fB{hostname}\-{now:%Y\-%m\-%d_%H:%M:%S}\fP becomes \fB{hostname}\-{now:%%Y\-%%m\-%%d_%%H:%%M:%%S}\fP). .UNINDENT .UNINDENT -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index 2f75c5804..19ffdd7c9 100644 --- a/docs/man/borg-prune.1 +++ b/docs/man/borg-prune.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-prune" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-prune \- Prune archives according to specified rules. .SH SYNOPSIS .sp @@ -50,8 +51,7 @@ you run \fBborg compact\fP\&. .sp This command is normally used by automated backup scripts wanting to keep a certain number of historic backups. This retention policy is commonly referred to as -GFS - +GFS \% (Grandfather\-father\-son) backup rotation scheme. .sp The recommended way to use prune is to give the archive series name to it via the @@ -227,7 +227,6 @@ There is also a visualized prune example in \fBdocs/misc/prune\-example.txt\fP\& .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-compact(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index 4f4e32ba0..c3aeb8891 100644 --- a/docs/man/borg-recreate.1 +++ b/docs/man/borg-recreate.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-recreate" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-recreate \- Recreate archives. .SH SYNOPSIS .sp @@ -113,7 +114,7 @@ include/exclude paths matching PATTERN read include/exclude patterns from PATTERNFILE, one per line .TP .B \-\-exclude\-caches -exclude directories that contain a CACHEDIR.TAG file ( ) +exclude directories that contain a CACHEDIR.TAG file (\%) .TP .BI \-\-exclude\-if\-present \ NAME exclude directories that are tagged by containing a filesystem object with the given NAME @@ -197,7 +198,6 @@ Comment: This is a better comment .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index e9c9b643a..09506a591 100644 --- a/docs/man/borg-rename.1 +++ b/docs/man/borg-rename.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-rename" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-rename \- Rename an existing archive. .SH SYNOPSIS .sp @@ -68,7 +69,6 @@ newname Mon, 2016\-02\-15 19:50:19 .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-repo-compress.1 b/docs/man/borg-repo-compress.1 index 2b04ebb7f..1f8d26412 100644 --- a/docs/man/borg-repo-compress.1 +++ b/docs/man/borg-repo-compress.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-repo-compress" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-repo-compress \- Repository (re-)compression. .SH SYNOPSIS .sp @@ -83,7 +84,6 @@ $ borg repo\-compress \-\-progress \-\-compression=obfuscate,1,zstd,3 .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-repo-create.1 b/docs/man/borg-repo-create.1 index 28a1a3704..eb6be3e54 100644 --- a/docs/man/borg-repo-create.1 +++ b/docs/man/borg-repo-create.1 @@ -1,5 +1,6 @@ '\" t -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -28,8 +29,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-repo-create" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-repo-create \- Creates a new, empty repository. .SH SYNOPSIS .sp @@ -272,7 +273,8 @@ $ borg repo\-create \-\-encryption=none $ export BORG_REPO=ssh://user@hostname/~/backup # repokey: stores the encrypted key in /config $ borg repo\-create \-\-encryption=repokey\-aes\-ocb -# keyfile: stores the encrypted key in ~/.config/borg/keys/ +# keyfile: stores the encrypted key in the config dir\(aqs keys/ subdir +# (e.g. ~/.config/borg/keys/ on Linux, ~/Library/Application Support/borg/keys/ on macOS) $ borg repo\-create \-\-encryption=keyfile\-aes\-ocb .EE .UNINDENT @@ -280,7 +282,6 @@ $ borg repo\-create \-\-encryption=keyfile\-aes\-ocb .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-repo\-delete(1)\fP, \fIborg\-repo\-list(1)\fP, \fIborg\-check(1)\fP, \fIborg\-benchmark\-cpu(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-repo-delete.1 b/docs/man/borg-repo-delete.1 index cd8604327..b65d0d08e 100644 --- a/docs/man/borg-repo-delete.1 +++ b/docs/man/borg-repo-delete.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-repo-delete" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-repo-delete \- Deletes a repository. .SH SYNOPSIS .sp @@ -82,7 +83,6 @@ Type \(aqYES\(aq if you understand this and want to continue: YES .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-repo-info.1 b/docs/man/borg-repo-info.1 index 8a78b693b..24708c8f0 100644 --- a/docs/man/borg-repo-info.1 +++ b/docs/man/borg-repo-info.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-repo-info" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-repo-info \- Show repository information. .SH SYNOPSIS .sp @@ -66,7 +67,6 @@ Total chunks: 3302 .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-repo-list.1 b/docs/man/borg-repo-list.1 index e351a6d23..b862faa41 100644 --- a/docs/man/borg-repo-list.1 +++ b/docs/man/borg-repo-list.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-repo-list" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-repo-list \- List the archives contained in a repository. .SH SYNOPSIS .sp @@ -100,8 +101,7 @@ ba56c4a5 Thu, 2024\-09\-26 10:12:45 +0200 src tw MacBook .SH NOTES .SS The FORMAT specifier syntax .sp -The \fB\-\-format\fP option uses Python\(aqs format string syntax -\&. +The \fB\-\-format\fP option uses Python\(aqs format string syntax \%\&. .sp Examples: .INDENT 0.0 @@ -124,22 +124,13 @@ ArchiveFoo Thu, 2021\-12\-09 10:22:28 [0b8e9...3b274] .UNINDENT .sp The following keys are always available: -.INDENT 0.0 -.IP \(bu 2 -NEWLINE: OS dependent line separator -.IP \(bu 2 -NL: alias of NEWLINE -.IP \(bu 2 -NUL: NUL character for creating print0 / xargs \-0 like output -.IP \(bu 2 -SPACE: space character -.IP \(bu 2 -TAB: tab character -.IP \(bu 2 -CR: carriage return character -.IP \(bu 2 -LF: line feed character -.UNINDENT +\- NEWLINE: OS dependent line separator +\- NL: alias of NEWLINE +\- NUL: NUL character for creating print0 / xargs \-0 like output +\- SPACE: space character +\- TAB: tab character +\- CR: carriage return character +\- LF: line feed character .sp Keys available only when listing archives in a repository: .INDENT 0.0 @@ -154,11 +145,11 @@ id: internal ID of the archive .IP \(bu 2 tags: archive tags .IP \(bu 2 -start: time (start) of creation of the archive +time: nominal time of the archive .IP \(bu 2 -time: alias of \(dqstart\(dq +start: start time of the archive operation .IP \(bu 2 -end: time (end) of creation of the archive +end: end time of the archive operation .IP \(bu 2 command_line: command line which was used to create the archive .IP \(bu 2 @@ -173,7 +164,6 @@ nfiles: count of files in this archive .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-repo-space.1 b/docs/man/borg-repo-space.1 index 4c58da83b..c29ae8de8 100644 --- a/docs/man/borg-repo-space.1 +++ b/docs/man/borg-repo-space.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-repo-space" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-repo-space \- Manages reserved space in the repository. .SH SYNOPSIS .sp @@ -85,7 +86,6 @@ Free all reserved space. Do not forget to reserve space again later. .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 index e427f9ee3..a0cd4079e 100644 --- a/docs/man/borg-serve.1 +++ b/docs/man/borg-serve.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-serve" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-serve \- Starts in server mode. This command is usually not used manually. .SH SYNOPSIS .sp @@ -40,7 +41,7 @@ This command starts a repository server process. \fIborg serve\fP currently supports: .INDENT 0.0 .IP \(bu 2 -Being automatically started via SSH when the borg client uses an \&... +Being automatically started via SSH when the borg client uses an \%\&... remote repository. In this mode, \fIborg serve\fP will run until that SSH connection is terminated. .IP \(bu 2 @@ -125,7 +126,7 @@ command=\(dqBORG_XXX=value borg serve [...]\(dq,restrict ssh\-rsa [...] .UNINDENT .UNINDENT .sp -\fBNOTE:\fP +\fBNote:\fP .INDENT 0.0 .INDENT 3.5 The examples above use the \fBrestrict\fP directive and assume a POSIX @@ -141,8 +142,7 @@ in this case. .UNINDENT .UNINDENT .sp -Details about sshd usage: sshd(8) - +Details about sshd usage: sshd(8) \% .SS SSH Configuration .sp \fBborg serve\fP\(aqs pipes (\fBstdin\fP/\fBstdout\fP/\fBstderr\fP) are connected to the \fBsshd\fP process on the server side. In the event that the SSH connection between \fBborg serve\fP and the client is disconnected or stuck abnormally (for example, due to a network outage), it can take a long time for \fBsshd\fP to notice the client is disconnected. In the meantime, \fBsshd\fP continues running, and as a result so does the \fBborg serve\fP process holding the lock on the repository. This can cause subsequent \fBborg\fP operations on the remote repository to fail with the error: \fBFailed to create/acquire the lock\fP\&. @@ -194,8 +194,7 @@ chsh \-s /bin/sh BORGUSER .UNINDENT .UNINDENT .sp -Because the configured shell is used by OpenSSH - +Because the configured shell is used by OpenSSH \% to execute the command configured through the \fBauthorized_keys\fP file using \fB\(dq$SHELL\(dq \-c \(dq$COMMAND\(dq\fP, setting a minimal shell implementation reduces the attack surface @@ -204,7 +203,6 @@ used. .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-tag.1 b/docs/man/borg-tag.1 index fd3fb6d7b..f2a4e68f5 100644 --- a/docs/man/borg-tag.1 +++ b/docs/man/borg-tag.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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-TAG" "1" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-tag" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-tag \- Manage tags. .SH SYNOPSIS .sp @@ -63,13 +64,13 @@ specify the archive name .INDENT 0.0 .TP .BI \-\-set \ TAG -set tags (can be given multiple times) +set tags .TP .BI \-\-add \ TAG -add tags (can be given multiple times) +add tags .TP .BI \-\-remove \ TAG -remove tags (can be given multiple times) +remove tags .UNINDENT .SS Archive filters .INDENT 0.0 @@ -101,7 +102,6 @@ consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m. .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-transfer.1 b/docs/man/borg-transfer.1 index f50f0f0f5..b09928518 100644 --- a/docs/man/borg-transfer.1 +++ b/docs/man/borg-transfer.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-transfer" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-transfer \- archives transfer from other repository, optionally upgrade data format .SH SYNOPSIS .sp @@ -181,10 +182,66 @@ $ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=F .EE .UNINDENT .UNINDENT +.SS Keyfile considerations when upgrading from borg 1.x +.sp +If you are using a \fBkeyfile\fP encryption mode (not \fBrepokey\fP), borg 2 +may not automatically find your borg 1.x key file, because the default +key file directory has changed on some platforms due to the switch to +the platformdirs \% library. +.sp +On \fBLinux\fP, there is typically no change \-\- both borg 1.x and borg 2 +use \fB~/.config/borg/keys/\fP\&. +.sp +On \fBmacOS\fP, borg 1.x stored key files in \fB~/.config/borg/keys/\fP, +but borg 2 defaults to \fB~/Library/Application Support/borg/keys/\fP\&. +.sp +On \fBWindows\fP, borg 1.x used XDG\-style paths (e.g. \fB~/.config/borg/keys/\fP), +while borg 2 defaults to \fBC:\eUsers\e\eAppData\eRoaming\eborg\ekeys\e\fP\&. +.sp +If borg 2 cannot find your key file, you have several options: +.INDENT 0.0 +.IP 1. 3 +\fBCopy the key file\fP from the old location to the new one. +.IP 2. 3 +\fBSet BORG_KEYS_DIR\fP to point to the old key file directory: +.INDENT 3.0 +.INDENT 3.5 +.sp +.EX +export BORG_KEYS_DIR=~/.config/borg/keys +.EE +.UNINDENT +.UNINDENT +.IP 3. 3 +\fBSet BORG_KEY_FILE\fP to point directly to the specific key file: +.INDENT 3.0 +.INDENT 3.5 +.sp +.EX +export BORG_KEY_FILE=~/.config/borg/keys/your_key_file +.EE +.UNINDENT +.UNINDENT +.IP 4. 3 +\fBSet BORG_BASE_DIR\fP to force borg 2 to use the same base directory +as borg 1.x: +.INDENT 3.0 +.INDENT 3.5 +.sp +.EX +export BORG_BASE_DIR=$HOME +.EE +.UNINDENT +.UNINDENT +.sp +This makes borg 2 use \fB$HOME/.config/borg\fP, \fB$HOME/.cache/borg\fP, +etc., matching borg 1.x behaviour on all platforms. +.UNINDENT +.sp +See \fIenv_vars\fP for more details on directory environment variables. .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index df0eab8d2..0cdd4460f 100644 --- a/docs/man/borg-umount.1 +++ b/docs/man/borg-umount.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-umount" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-umount \- Unmounts the FUSE filesystem. .SH SYNOPSIS .sp @@ -95,7 +96,7 @@ root\-2016\-02\-01 root\-2016\-02\-15 .UNINDENT .UNINDENT .sp -\fBNOTE:\fP +\fBNote:\fP .INDENT 0.0 .INDENT 3.5 \fBborgfs\fP will be automatically provided if you used a distribution @@ -106,7 +107,6 @@ to manually create a symlink (see \fIpyinstaller\-binary\fP). .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-mount(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-undelete.1 b/docs/man/borg-undelete.1 index 29bed74ed..a169be56e 100644 --- a/docs/man/borg-undelete.1 +++ b/docs/man/borg-undelete.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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-UNDELETE" "1" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-undelete" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-undelete \- Undeletes archives. .SH SYNOPSIS .sp @@ -96,7 +97,6 @@ consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m. .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-version.1 b/docs/man/borg-version.1 index 78569db9b..a38e36fd2 100644 --- a/docs/man/borg-version.1 +++ b/docs/man/borg-version.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-version" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-version \- Displays the Borg client and server versions. .SH SYNOPSIS .sp @@ -69,7 +70,6 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index 408da7c32..e986254fd 100644 --- a/docs/man/borg-with-lock.1 +++ b/docs/man/borg-with-lock.1 @@ -1,4 +1,5 @@ -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -27,8 +28,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg-with-lock" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg-with-lock \- Runs a user-specified command with the repository lock held. .SH SYNOPSIS .sp @@ -50,7 +51,7 @@ running in the repository), then executes the given command as a subprocess and for its termination, releases the lock, and returns the user command\(aqs return code as Borg\(aqs return code. .sp -\fBNOTE:\fP +\fBNote:\fP .INDENT 0.0 .INDENT 3.5 If you copy a repository with the lock held, the lock will be present in @@ -74,7 +75,6 @@ command arguments .SH SEE ALSO .sp \fIborg\-common(1)\fP -.SH AUTHOR +.SH Author The Borg Collective -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. diff --git a/docs/man/borg.1 b/docs/man/borg.1 index 2c0d41824..155fce027 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -1,5 +1,6 @@ '\" t -.\" Man page generated from reStructuredText. +.\" Man page generated from reStructuredText +.\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 @@ -28,8 +29,8 @@ 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" "2025-12-23" "" "borg backup tool" -.SH NAME +.TH "borg" "1" "2026-03-15" "" "borg backup tool" +.SH Name borg \- deduplicating and encrypting backup tool .SH SYNOPSIS .sp @@ -167,7 +168,7 @@ $ borg \-r /path/to/repo compact \-v .UNINDENT .UNINDENT .sp -\fBNOTE:\fP +\fBNote:\fP .INDENT 0.0 .INDENT 3.5 Borg is quiet by default (it defaults to WARNING log level). @@ -195,7 +196,7 @@ borg create archive \-s \-\-progress path # BAD .UNINDENT .UNINDENT .sp -This is due to a problem in the argparse module: +This is due to a problem in the argparse module: \% .SS Repository URLs .sp \fBLocal filesystem\fP (or locally mounted network filesystem): @@ -209,7 +210,7 @@ expanded by your shell). .sp Note: You may also prepend \fBfile://\fP to a filesystem path to use URL style. .sp -\fBRemote repositories\fP accessed via SSH : +\fBRemote repositories\fP accessed via SSH \%: .sp \fBssh://user@host:port//abs/path/to/repo\fP — absolute path .sp @@ -229,9 +230,10 @@ For SSH and SFTP URLs, the \fBuser@\fP and \fB:port\fP parts are optional. .sp \fBRemote repositories\fP accessed via S3: .sp -\fB(s3|b2):[profile|(access_key_id:access_key_secret)@][schema://hostname[:port]]/bucket/path\fP — see the boto3 docs for more details about credentials. +\fB(s3|b2):[(profile|(access_key_id:access_key_secret))@][scheme://hostname[:port]]/bucket/path\fP — see the boto3 docs for more details about credentials. .sp If you are connecting to AWS S3, \fB[schema://hostname[:port]]\fP is optional, but \fBbucket\fP and \fBpath\fP are always required. +\fIscheme\fP is usually \fIhttps\fP here, hostname and optional port refer to your S3/B2 server, if that is not Amazon\(aqs. .sp Note: There is a known issue with some S3\-compatible services, e.g., Backblaze B2. If you encounter problems, try using \fBb2:\fP instead of \fBs3:\fP in the URL. .sp @@ -304,7 +306,7 @@ this prints only critical messages. While you can set miscellaneous log levels, do not expect every command to produce different output at different log levels — it\(aqs merely a possibility. .sp -\fBWARNING:\fP +\fBWarning:\fP .INDENT 0.0 .INDENT 3.5 Options \fB\-\-critical\fP and \fB\-\-error\fP are provided for completeness, @@ -427,15 +429,14 @@ a unique id based on the MAC address of the network interface. Except if that MA that case it returns a random value, which is not what we want (because it kills automatic stale lock removal). So, if you have an all\-zero MAC address or other reasons to better control the host id externally, just set this environment variable to a unique value. If all your FQDNs are unique, you can just use the FQDN. If not, -use \&. +use \%\&. .TP .B BORG_LOCK_WAIT You can set the default value for the \fB\-\-lock\-wait\fP option with this, so you do not need to give it as a command line option. .TP .B BORG_LOGGING_CONF -When set, use the given filename as INI -\-style logging configuration. +When set, use the given filename as INI \%\-style logging configuration. A basic example conf can be found at \fBdocs/misc/logging.conf\fP\&. .TP .B BORG_RSH @@ -555,9 +556,9 @@ Now you can init a fresh repo. Make sure you do not use the workaround any more. .INDENT 7.0 .TP .B BORG_LIST_FORMAT -Giving the default value for \fBborg repo\-list \-\-format=X\fP\&. +Giving the default value for \fBborg list \-\-format=X\fP\&. .TP -.B BORG_RLIST_FORMAT +.B BORG_REPO_LIST_FORMAT Giving the default value for \fBborg repo\-list \-\-format=X\fP\&. .TP .B BORG_PRUNE_FORMAT @@ -584,10 +585,109 @@ Note: answers are case sensitive. setting an invalid answer value might either g 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 +.sp +Directories and files: +.INDENT 0.0 +.INDENT 3.5 +.sp +\fBNote:\fP +.INDENT 0.0 +.INDENT 3.5 +Borg 2 uses the platformdirs \% library to determine +default directory locations. This means that default paths are \fBplatform\-specific\fP: +.INDENT 0.0 +.IP \(bu 2 +\fBLinux\fP: Uses XDG Base Directory Specification paths (e.g., \fB~/.config/borg\fP, +\fB~/.cache/borg\fP, \fB~/.local/share/borg\fP). XDG env var \% variables are honoured. +.IP \(bu 2 +\fBmacOS\fP: Uses native macOS directories (e.g., \fB~/Library/Application Support/borg\fP, +\fB~/Library/Caches/borg\fP). XDG env var \% variables are \fBnot\fP honoured. +.IP \(bu 2 +\fBWindows\fP: Uses Windows AppData directories (e.g., \fBC:\eUsers\e\eAppData\eRoaming\eborg\fP, +\fBC:\eUsers\e\eAppData\eLocal\eborg\fP). XDG env var \% variables are \fBnot\fP honoured. +.UNINDENT +.sp +On all platforms, you can override each directory individually using the specific environment +variables described below. You can also set \fBBORG_BASE_DIR\fP to force borg to use +\fBBORG_BASE_DIR/.config/borg\fP, \fBBORG_BASE_DIR/.cache/borg\fP, etc., regardless of the platform. +.UNINDENT +.UNINDENT +.sp +Default directory locations by platform (when no \fBBORG_*\fP environment variables are set): +.TS +box center; +l|l|l|l. +T{ +Directory +T} T{ +Linux +T} T{ +macOS +T} T{ +Windows +T} +_ +T{ +Config +T} T{ +\fB~/.config/borg\fP +T} T{ +\fB~/Library/Application Support/borg\fP +T} T{ +\fB%APPDATA%\eborg\fP +T} +_ +T{ +Cache +T} T{ +\fB~/.cache/borg\fP +T} T{ +\fB~/Library/Caches/borg\fP +T} T{ +\fB%LOCALAPPDATA%\eborg\eCache\fP +T} +_ +T{ +Data +T} T{ +\fB~/.local/share/borg\fP +T} T{ +\fB~/Library/Application Support/borg\fP +T} T{ +\fB%LOCALAPPDATA%\eborg\fP +T} +_ +T{ +Runtime +T} T{ +\fB/run/user//borg\fP +T} T{ +\fB~/Library/Caches/TemporaryItems/borg\fP +T} T{ +\fB%TEMP%\eborg\fP +T} +_ +T{ +Keys +T} T{ +\fB/keys\fP +T} T{ +\fB/keys\fP +T} T{ +\fB\ekeys\fP +T} +_ +T{ +Security +T} T{ +\fB/security\fP +T} T{ +\fB/security\fP +T} T{ +\fB\esecurity\fP +T} +.TE .INDENT 0.0 -.TP -.B Directories and files: -.INDENT 7.0 .TP .B BORG_BASE_DIR Defaults to \fB$HOME\fP or \fB~$USER\fP or \fB~\fP (in that order). @@ -596,31 +696,31 @@ to modify \fBBORG_BASE_DIR\fP: the other paths for cache, config etc. will adapt (assuming you didn\(aqt set them to a different custom value). .TP .B BORG_CACHE_DIR -Defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while -XDG env var - \fBXDG_CACHE_HOME\fP is set, then \fB$XDG_CACHE_HOME/borg\fP is being used instead. +Defaults to the platform\-specific cache directory (see table above). +If \fBBORG_BASE_DIR\fP is set, defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. +On Linux, XDG env var \% \fBXDG_CACHE_HOME\fP is also honoured if \fBBORG_BASE_DIR\fP is not set. 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 -XDG env var - \fBXDG_CONFIG_HOME\fP is set, then \fB$XDG_CONFIG_HOME/borg\fP is being used instead. +Defaults to the platform\-specific config directory (see table above). +If \fBBORG_BASE_DIR\fP is set, defaults to \fB$BORG_BASE_DIR/.config/borg\fP\&. +On Linux, XDG env var \% \fBXDG_CONFIG_HOME\fP is also honoured if \fBBORG_BASE_DIR\fP is not set. 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 .B BORG_DATA_DIR -Defaults to \fB$BORG_BASE_DIR/.local/share/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while -XDG env var - \fBXDG_DATA_HOME\fP is set, then \fB$XDG_DATA_HOME/borg\fP is being used instead. +Defaults to the platform\-specific data directory (see table above). +If \fBBORG_BASE_DIR\fP is set, defaults to \fB$BORG_BASE_DIR/.local/share/borg\fP\&. +On Linux, XDG env var \% \fBXDG_DATA_HOME\fP is also honoured if \fBBORG_BASE_DIR\fP is not set. This directory contains all borg data directories, see the FAQ for a security advisory about the data in this directory: \fIhome_data_borg\fP .TP .B BORG_RUNTIME_DIR -Defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while -XDG env var - \fBXDG_RUNTIME_DIR\fP is set, then \fB$XDG_RUNTIME_DIR/borg\fP is being used instead. +Defaults to the platform\-specific runtime directory (see table above). +If \fBBORG_BASE_DIR\fP is set, defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. +On Linux, XDG env var \% \fBXDG_RUNTIME_DIR\fP is also honoured if \fBBORG_BASE_DIR\fP is not set. This directory contains borg runtime files, like e.g. the socket file. .TP .B BORG_SECURITY_DIR @@ -653,9 +753,11 @@ you need to point to the correct key file matching the repository the command wi .TP .B TMPDIR This is where temporary files are stored (might need a lot of temporary space for some -operations), see tempfile - for details. +operations), see tempfile \% for details. .UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 .TP .B Building: .INDENT 7.0 @@ -673,10 +775,6 @@ Borg will be linked against the system libacl instead of a bundled implementatio .B BORG_LIBLZ4_PREFIX Adds given prefix directory to the default locations. If a \(aqinclude/lz4.h\(aq is found Borg will be linked against the system liblz4 instead of a bundled implementation. (setup.py) -.TP -.B BORG_LIBZSTD_PREFIX -Adds given prefix directory to the default locations. If a \(aqinclude/zstd.h\(aq is found Borg -will be linked against the system libzstd instead of a bundled implementation. (setup.py) .UNINDENT .UNINDENT .sp @@ -688,6 +786,39 @@ Be very careful when using the \(dqyes\(dq sayers, the warnings with prompt exis Also be very careful when putting your passphrase into a script, make sure it has appropriate file permissions (e.g. mode 600, root:root). .UNINDENT +.SS Automatically generated Environment Variables (jsonargparse) +.sp +Borg uses jsonargparse \% with \fBdefault_env=True\fP, which means that every +command\-line option can also be set via an environment variable. +.sp +The environment variable name is derived from the program name (\fBborg\fP), +the subcommand (if any), and the option name, all converted to uppercase +with dashes replaced by underscores. +.sp +For \fBtop\-level options\fP (not specific to a subcommand), the pattern is: +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +BORG_