diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0f489aaef5..f3ded45048 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -279,7 +279,7 @@ jobs:
- name: Build Borg fat binaries (${{ matrix.binary }})
if: ${{ matrix.binary && startsWith(github.ref, 'refs/tags/') }}
run: |
- pip install 'pyinstaller==6.14.2'
+ pip install -r requirements.d/pyinstaller.txt
mkdir -p dist/binary
# Ensure locally built binaries in ./dist/binary are found during tox tests
echo "$GITHUB_WORKSPACE/dist/binary" >> "$GITHUB_PATH"
@@ -429,7 +429,7 @@ jobs:
tox -e py311-mfusepy
if [[ "${{ matrix.do_binaries }}" == "true" && "${{ startsWith(github.ref, 'refs/tags/') }}" == "true" ]]; then
- python -m pip install 'pyinstaller==6.14.2'
+ python -m pip install -r requirements.d/pyinstaller.txt
mkdir -p dist/binary
pyinstaller --clean --distpath=dist/binary scripts/borg.exe.spec
pushd dist/binary
@@ -576,7 +576,7 @@ jobs:
. env/bin/activate
# python -m pip install --upgrade pip
# pip install --upgrade setuptools build wheel
- pip install pyinstaller==6.14.2
+ pip install -r requirements.d/pyinstaller.txt
- name: Build
run: |
diff --git a/Vagrantfile b/Vagrantfile
index 2bec9f5190..e1904c7ae2 100644
--- a/Vagrantfile
+++ b/Vagrantfile
@@ -206,7 +206,7 @@ def install_pyinstaller()
. ~/.bash_profile
cd /vagrant/borg
. borg-env/bin/activate
- pip install 'pyinstaller==6.14.2'
+ pip install -r requirements.d/pyinstaller.txt
EOF
end
diff --git a/docs/changes.rst b/docs/changes.rst
index fdf2608214..a80b6e7f1a 100644
--- a/docs/changes.rst
+++ b/docs/changes.rst
@@ -144,8 +144,8 @@ Compatibility notes:
Change Log 2.x
==============
-Version 2.0.0b20 (not released yet)
------------------------------------
+Version 2.0.0b20 (2025-12-24)
+-----------------------------
Please note:
diff --git a/docs/man/borg-analyze.1 b/docs/man/borg-analyze.1
index 1842607ff1..9b55b282e6 100644
--- a/docs/man/borg-analyze.1
+++ b/docs/man/borg-analyze.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-ANALYZE" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-analyze \- Analyze archives
+borg-analyze \- Analyzes archives.
.SH SYNOPSIS
.sp
borg [common options] analyze [options]
@@ -37,21 +37,21 @@ borg [common options] analyze [options]
.sp
Analyze archives to find \(dqhot spots\(dq.
.sp
-Borg analyze relies on the usual archive matching options to select the
+\fBborg analyze\fP relies on the usual archive matching options to select the
archives that should be considered for analysis (e.g. \fB\-a series_name\fP).
-Then it iterates over all matching archives, over all contained files and
-collects information about chunks stored in all directories it encountered.
+Then it iterates over all matching archives, over all contained files, and
+collects information about chunks stored in all directories it encounters.
.sp
-It considers chunk IDs and their plaintext sizes (we don\(aqt have the compressed
-size in the repository easily available) and adds up added/removed chunks\(aq
-sizes per direct parent directory and outputs a list of \(dqdirectory: size\(dq.
+It considers chunk IDs and their plaintext sizes (we do not have the compressed
+size in the repository easily available) and adds up the sizes of added and removed
+chunks per direct parent directory, and outputs a list of \(dqdirectory: size\(dq.
.sp
-You can use that list to find directories with a lot of \(dqactivity\(dq \- maybe
-some of these are temporary or cache directories you did forget to exclude.
+You can use that list to find directories with a lot of \(dqactivity\(dq — maybe
+some of these are temporary or cache directories you forgot to exclude.
.sp
-To not have these unwanted directories in your backups, you could carefully
-exclude these in \fBborg create\fP (for future backups) or use \fBborg recreate\fP
-to re\-create existing archives without these.
+To avoid including these unwanted directories in your backups, you can carefully
+exclude them in \fBborg create\fP (for future backups) or use \fBborg recreate\fP
+to recreate existing archives without them.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -59,28 +59,28 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.INDENT 0.0
.TP
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
-only consider archives matching all patterns. see \(dqborg help match\-archives\(dq.
+only consider archives matching all patterns. See \(dqborg help match\-archives\(dq.
.TP
.BI \-\-sort\-by \ KEYS
Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
.TP
.BI \-\-first \ N
-consider first N archives after other filters were applied
+consider the first N archives after other filters are applied
.TP
.BI \-\-last \ N
-consider last N archives after other filters were applied
+consider the last N archives after other filters are applied
.TP
.BI \-\-oldest \ TIMESPAN
-consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
+consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newest \ TIMESPAN
-consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m.
+consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-older \ TIMESPAN
-consider archives older than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newer \ TIMESPAN
-consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.UNINDENT
.SH SEE ALSO
.sp
diff --git a/docs/man/borg-benchmark-cpu.1 b/docs/man/borg-benchmark-cpu.1
index 2f4db75efe..b013c59f87 100644
--- a/docs/man/borg-benchmark-cpu.1
+++ b/docs/man/borg-benchmark-cpu.1
@@ -27,15 +27,15 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CPU" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-benchmark-cpu \- Benchmark CPU bound operations.
+borg-benchmark-cpu \- Benchmark CPU-bound operations.
.SH SYNOPSIS
.sp
borg [common options] benchmark cpu [options]
.SH DESCRIPTION
.sp
-This command benchmarks misc. CPU bound borg operations.
+This command benchmarks miscellaneous CPU\-bound Borg operations.
.sp
It creates input data in memory, runs the operation and then displays throughput.
To reduce outside influence on the timings, please make sure to run this with:
diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1
index e8658c9cb0..43f51bc613 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" "2025-08-02" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CRUD" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
.SH SYNOPSIS
@@ -37,11 +37,11 @@ borg [common options] benchmark crud [options] PATH
.sp
This command benchmarks borg CRUD (create, read, update, delete) operations.
.sp
-It creates input data below the given PATH and backups this data into the given REPO.
+It creates input data below the given PATH and backs up this data into the given REPO.
The REPO must already exist (it could be a fresh empty repo or an existing repo, the
command will create / read / update / delete some archives named borg\-benchmark\-crud* there.
.sp
-Make sure you have free space there, you\(aqll need about 1GB each (+ overhead).
+Make sure you have free space there; you will need about 1 GB each (+ overhead).
.sp
If your repository is encrypted and borg needs a passphrase to unlock the key, use:
.INDENT 0.0
@@ -87,7 +87,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.INDENT 0.0
.TP
.B PATH
-path were to create benchmark input data
+path where to create benchmark input data
.UNINDENT
.SH SEE ALSO
.sp
diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1
index 638027856b..fe24e72e5c 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" "2025-08-02" "" "borg backup tool"
+.TH "BORG-BENCHMARK" "1" "2025-12-23" "" "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 251b32fa2e..ef72d2aa5e 100644
--- a/docs/man/borg-break-lock.1
+++ b/docs/man/borg-break-lock.1
@@ -27,17 +27,17 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-BREAK-LOCK" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
+borg-break-lock \- Breaks the repository lock (for example, if it was left by a dead Borg process).
.SH SYNOPSIS
.sp
borg [common options] break\-lock [options]
.SH DESCRIPTION
.sp
This command breaks the repository and cache locks.
-Please use carefully and only while no borg process (on any machine) is
-trying to access the Cache or the Repository.
+Use with care and only when no Borg process (on any machine) is
+trying to access the cache or the repository.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1
index 9237a80df4..da2cc8868a 100644
--- a/docs/man/borg-check.1
+++ b/docs/man/borg-check.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-CHECK" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-check \- Check repository consistency
+borg-check \- Checks repository consistency.
.SH SYNOPSIS
.sp
borg [common options] check [options]
@@ -44,7 +44,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 a 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
@@ -53,9 +53,9 @@ repository manifest exists, the archive metadata chunk is present, and that
all chunks referencing files (items) in the archive exist. This requires
reading archive and file metadata, but not data. To scan for archives whose
entries were lost from the archive directory, pass \fB\-\-find\-lost\-archives\fP\&.
-It requires reading all data and is hence very time consuming.
+It requires reading all data and is hence very time\-consuming.
To additionally cryptographically verify the file (content) data integrity,
-pass \fB\-\-verify\-data\fP, which is even more time consuming.
+pass \fB\-\-verify\-data\fP, which is even more time\-consuming.
.sp
When checking archives of a remote repository, archive checks run on the client
machine because they require decrypting data and therefore the encryption key.
@@ -66,7 +66,7 @@ repository checks only, or pass \fB\-\-archives\-only\fP to run the archive chec
only.
.sp
The \fB\-\-max\-duration\fP option can be used to split a long\-running repository
-check into multiple partial checks. After the given number of seconds the check
+check into multiple partial checks. After the given number of seconds, the check
is interrupted. The next partial check will continue where the previous one
stopped, until the full repository has been checked. Assuming a complete check
would take 7 hours, then running a daily check with \fB\-\-max\-duration=3600\fP
@@ -77,31 +77,31 @@ archive checks, nor enable repair mode. Consequently, if you want to use
\fB\-\-max\-duration\fP you must also pass \fB\-\-repository\-only\fP, and must not pass
\fB\-\-archives\-only\fP, nor \fB\-\-repair\fP\&.
.sp
-\fBWarning:\fP Please note that partial repository checks (i.e. running it with
+\fBWarning:\fP Please note that partial repository checks (i.e., running with
\fB\-\-max\-duration\fP) can only perform non\-cryptographic checksum checks on the
-repository files. Enabling partial repository checks excepts archive checks
-for the same reason. Therefore partial checks may be useful with very large
-repositories only where a full check would take too long.
+repository files. Enabling partial repository checks excludes archive checks
+for the same reason. Therefore, partial checks may be useful only with very large
+repositories where a full check would take too long.
.sp
The \fB\-\-verify\-data\fP option will perform a full integrity verification (as
opposed to checking just the xxh64) of data, which means reading the
data from the repository, decrypting and decompressing it. It is a complete
-cryptographic verification and hence very time consuming, but will detect any
+cryptographic verification and hence very time\-consuming, but will detect any
accidental and malicious corruption. Tamper\-resistance is only guaranteed for
-encrypted repositories against attackers without access to the keys. You can
-not use \fB\-\-verify\-data\fP with \fB\-\-repository\-only\fP\&.
+encrypted repositories against attackers without access to the keys. You cannot
+use \fB\-\-verify\-data\fP with \fB\-\-repository\-only\fP\&.
.sp
The \fB\-\-find\-lost\-archives\fP option will also scan the whole repository, but
tells Borg to search for lost archive metadata. If Borg encounters any archive
-metadata that doesn\(aqt match with an archive directory entry (including
+metadata that does not match an archive directory entry (including
soft\-deleted archives), it means that an entry was lost.
Unless \fBborg compact\fP is called, these archives can be fully restored with
\fB\-\-repair\fP\&. Please note that \fB\-\-find\-lost\-archives\fP must read a lot of
-data from the repository and is thus very time consuming. You can not use
+data from the repository and is thus very time\-consuming. You cannot use
\fB\-\-find\-lost\-archives\fP with \fB\-\-repository\-only\fP\&.
.SS About repair mode
.sp
-The check command is a readonly task by default. If any corruption is found,
+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
@@ -124,7 +124,7 @@ It is highly recommended to create a backup of your repository before running
in repair mode (i.e. running it with \fB\-\-repair\fP).
.sp
Repair mode will attempt to fix any corruptions found. Fixing corruptions does
-not mean recovering lost data: Borg can not magically restore data lost due to
+not mean recovering lost data: Borg cannot magically restore data lost due to
e.g. a hardware failure. Repairing a repository means sacrificing some data
for the sake of the repository as a whole and the remaining data. Hence it is,
by definition, a potentially lossy task.
@@ -153,7 +153,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
only perform repository checks
.TP
.B \-\-archives\-only
-only perform archives checks
+only perform archive checks
.TP
.B \-\-verify\-data
perform cryptographic archive data integrity verification (conflicts with \fB\-\-repository\-only\fP)
@@ -165,34 +165,34 @@ attempt to repair any inconsistencies found
attempt to find lost archives
.TP
.BI \-\-max\-duration \ SECONDS
-do only a partial repo check for max. SECONDS seconds (Default: unlimited)
+perform only a partial repository check for at most SECONDS seconds (default: unlimited)
.UNINDENT
.SS Archive filters
.INDENT 0.0
.TP
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
-only consider archives matching all patterns. see \(dqborg help match\-archives\(dq.
+only consider archives matching all patterns. See \(dqborg help match\-archives\(dq.
.TP
.BI \-\-sort\-by \ KEYS
Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
.TP
.BI \-\-first \ N
-consider first N archives after other filters were applied
+consider the first N archives after other filters are applied
.TP
.BI \-\-last \ N
-consider last N archives after other filters were applied
+consider the last N archives after other filters are applied
.TP
.BI \-\-oldest \ TIMESPAN
-consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
+consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newest \ TIMESPAN
-consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m.
+consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-older \ TIMESPAN
-consider archives older than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newer \ TIMESPAN
-consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.UNINDENT
.SH SEE ALSO
.sp
diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1
index afa4cbb927..5bd73fb665 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" "2025-08-02" "" "borg backup tool"
+.TH "BORG-COMMON" "1" "2025-12-23" "" "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 8275db1253..44f48bd491 100644
--- a/docs/man/borg-compact.1
+++ b/docs/man/borg-compact.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-COMPACT" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-compact \- Collect garbage in repository
+borg-compact \- Collects garbage in the repository.
.SH SYNOPSIS
.sp
borg [common options] compact [options]
@@ -37,49 +37,47 @@ borg [common options] compact [options]
.sp
Free repository space by deleting unused chunks.
.sp
-borg compact analyzes all existing archives to find out which repository
+\fBborg compact\fP analyzes all existing archives to determine which repository
objects are actually used (referenced). It then deletes all unused objects
from the repository to free space.
.sp
Unused objects may result from:
.INDENT 0.0
.IP \(bu 2
-borg delete or prune usage
+use of \fBborg delete\fP or \fBborg prune\fP
.IP \(bu 2
-interrupted backups (maybe retry the backup first before running compact)
+interrupted backups (consider retrying the backup before running compact)
.IP \(bu 2
-backup of source files that had an I/O error in the middle of their contents
-and that were skipped due to this
+backups of source files that encountered an I/O error mid\-transfer and were skipped
.IP \(bu 2
-corruption of the repository (e.g. the archives directory having lost
-entries, see notes below)
+corruption of the repository (e.g., the archives directory lost entries; see notes below)
.UNINDENT
.sp
-You usually don\(aqt want to run \fBborg compact\fP after every write operation, but
-either regularly (e.g. once a month, possibly together with \fBborg check\fP) or
+You usually do not want to run \fBborg compact\fP after every write operation, but
+either regularly (e.g., once a month, possibly together with \fBborg check\fP) or
when disk space needs to be freed.
.sp
\fBImportant:\fP
.sp
-After compacting it is no longer possible to use \fBborg undelete\fP to recover
+After compacting, it is no longer possible to use \fBborg undelete\fP to recover
previously soft\-deleted archives.
.sp
\fBborg compact\fP might also delete data from archives that were \(dqlost\(dq due to
archives directory corruption. Such archives could potentially be restored with
\fBborg check \-\-find\-lost\-archives [\-\-repair]\fP, which is slow. You therefore
-might not want to do that unless there are signs of lost archives (e.g. when
+might not want to do that unless there are signs of lost archives (e.g., when
seeing fatal errors when creating backups or when archives are missing in
\fBborg repo\-list\fP).
.sp
-When giving the \fB\-\-stats\fP option, borg will internally list all repository
-objects to determine their existence AND stored size. It will build a fresh
+When using the \fB\-\-stats\fP option, borg will internally list all repository
+objects to determine their existence and stored size. It will build a fresh
chunks index from that information and cache it in the repository. For some
types of repositories, this might be very slow. It will tell you the sum of
stored object sizes, before and after compaction.
.sp
Without \fB\-\-stats\fP, borg will rely on the cached chunks index to determine
existing object IDs (but there is no stored size information in the index,
-thus it can\(aqt compute before/after compaction size statistics).
+thus it cannot compute before/after compaction size statistics).
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -87,7 +85,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.INDENT 0.0
.TP
.B \-n\fP,\fB \-\-dry\-run
-do nothing
+do not change the repository
.TP
.B \-s\fP,\fB \-\-stats
print statistics (might be much slower)
@@ -97,7 +95,7 @@ print statistics (might be much slower)
.INDENT 3.5
.sp
.EX
-# compact segments and free repo disk space
+# Compact segments and free repository disk space
$ borg compact
.EE
.UNINDENT
diff --git a/docs/man/borg-completion.1 b/docs/man/borg-completion.1
index 0b2f0783d5..1d6feaf58c 100644
--- a/docs/man/borg-completion.1
+++ b/docs/man/borg-completion.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-COMPLETION" "1" "2025-11-17" "" "borg backup tool"
+.TH "BORG-COMPLETION" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
borg-completion \- Output shell completion script for the given shell.
.SH SYNOPSIS
diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1
index 1f9b060132..1c7db62b2e 100644
--- a/docs/man/borg-compression.1
+++ b/docs/man/borg-compression.1
@@ -27,19 +27,19 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-COMPRESSION" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
borg-compression \- Details regarding compression
.SH DESCRIPTION
.sp
-It is no problem to mix different compression methods in one repo,
+It is no problem to mix different compression methods in one repository,
deduplication is done on the source data chunks (not on the compressed
or encrypted data).
.sp
-If some specific chunk was once compressed and stored into the repo, creating
+If some specific chunk was once compressed and stored into the repository, creating
another backup that also uses this chunk will not change the stored chunk.
So if you use different compression specs for the backups, whichever stores a
-chunk first determines its compression. See also borg recreate.
+chunk first determines its compression. See also \fBborg recreate\fP\&.
.sp
Compression is lz4 by default. If you want something else, you have to specify what you want.
.sp
diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1
index 7670cbd3f3..8493f09d3d 100644
--- a/docs/man/borg-create.1
+++ b/docs/man/borg-create.1
@@ -27,17 +27,17 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-CREATE" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-create \- Create new archive
+borg-create \- Creates a new archive.
.SH SYNOPSIS
.sp
borg [common options] create [options] NAME [PATH...]
.SH DESCRIPTION
.sp
This command creates a backup archive containing all files found while recursively
-traversing all paths specified. Paths are added to the archive as they are given,
-that means if relative paths are desired, the command has to be run from the correct
+traversing all specified paths. Paths are added to the archive as they are given,
+which means that if relative paths are desired, the command must be run from the correct
directory.
.sp
The slashdot hack in paths (recursion roots) is triggered by using \fB/./\fP:
@@ -45,23 +45,23 @@ The slashdot hack in paths (recursion roots) is triggered by using \fB/./\fP:
strip the prefix on the left side of \fB\&./\fP from the archived items (in this case,
\fBthis/gets/archived\fP will be the path in the archived item).
.sp
-When giving \(aq\-\(aq as path, borg will read data from standard input and create a
-file \(aqstdin\(aq in the created archive from that data. In some cases it\(aqs more
-appropriate to use \-\-content\-from\-command, however. See section \fIReading from
-stdin\fP below for details.
+When specifying \(aq\-\(aq as a path, borg will read data from standard input and create a
+file named \(aqstdin\(aq in the created archive from that data. In some cases, it is more
+appropriate to use \-\-content\-from\-command. See the section \fIReading from stdin\fP
+below for details.
.sp
The archive will consume almost no disk space for files or parts of files that
have already been stored in other archives.
.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)
+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.
.sp
Backup speed is increased by not reprocessing files that are already part of
-existing archives and weren\(aqt modified. The detection of unmodified files is
+existing archives and were not modified. The detection of unmodified files is
done by comparing multiple file metadata values with previous values kept in
the files cache.
.sp
@@ -96,15 +96,15 @@ ctime vs. mtime: safety vs. speed
.INDENT 0.0
.IP \(bu 2
ctime is a rather safe way to detect changes to a file (metadata and contents)
-as it can not be set from userspace. But, a metadata\-only change will already
+as it cannot be set from userspace. But a metadata\-only change will already
update the ctime, so there might be some unnecessary chunking/hashing even
without content changes. Some filesystems do not support ctime (change time).
E.g. doing a chown or chmod to a file will change its ctime.
.IP \(bu 2
mtime usually works and only updates if file contents were changed. But mtime
-can be arbitrarily set from userspace, e.g. to set mtime back to the same value
+can be arbitrarily set from userspace, e.g., to set mtime back to the same value
it had before a content change happened. This can be used maliciously as well as
-well\-meant, but in both cases mtime based cache modes can be problematic.
+well\-meant, but in both cases mtime\-based cache modes can be problematic.
.UNINDENT
.INDENT 0.0
.TP
@@ -161,7 +161,7 @@ do not create a backup archive
print statistics for the created archive
.TP
.B \-\-list
-output verbose list of items (files, dirs, ...)
+output a verbose list of items (files, dirs, ...)
.TP
.BI \-\-filter \ STATUSCHARS
only display items with the given status characters (see description)
@@ -182,7 +182,7 @@ set group GROUP in archive for stdin data (default: do not store group/gid)
set mode to M in archive for stdin data (default: 0660)
.TP
.B \-\-content\-from\-command
-interpret PATH as command and store its stdout. See also section Reading from stdin below.
+interpret PATH as a command and store its stdout. See also the section \(aqReading from stdin\(aq below.
.TP
.B \-\-paths\-from\-stdin
read DELIM\-separated list of paths to back up from stdin. All control is external: it will back up all files given \- no more, no less.
@@ -215,7 +215,7 @@ exclude directories that contain a CACHEDIR.TAG file ( /.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\-archive\(dq
-# use zlib compression (good, but slow) \- default is lz4 (fast, low compression ratio)
+# Back up 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\-archive /
# Backup into an archive name like FQDN\-root
$ borg create \(aq{fqdn}\-root\(aq /
-# Backup a remote host locally (\(dqpull\(dq style) using sshfs
+# Back up a remote host locally (\(dqpull\(dq style) using SSHFS
$ mkdir sshfs\-mount
$ sshfs root@example.com:/ sshfs\-mount
$ cd sshfs\-mount
@@ -310,8 +326,8 @@ $ borg create example.com\-root .
$ cd ..
$ fusermount \-u sshfs\-mount
-# Make a big effort in fine granular deduplication (big chunk management
-# overhead, needs a lot of RAM and disk space, see formula in internals docs):
+# Make a big effort in fine\-grained deduplication (big chunk management
+# overhead, needs a lot of RAM and disk space; see the formula in the internals docs):
$ borg create \-\-chunker\-params buzhash,10,23,16,4095 small /smallstuff
# Backup a raw device (must not be active/in use/mounted at that time)
@@ -335,16 +351,16 @@ $ 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 and user name as archive name
+# Use the short hostname and username as the archive name
$ borg create \(aq{hostname}\-{user}\(aq ~
-# Backing up relative paths by moving into the correct directory first
+# Back 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\(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
+# Use \-\-paths\-from\-stdin with find to back up only files less than 1 MB in size
$ 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
@@ -419,7 +435,7 @@ borg usually just stores their metadata:
.IP \(bu 2
\(aqc\(aq = char device
.IP \(bu 2
-\(aqh\(aq = regular file, hardlink (to already seen inodes)
+\(aqh\(aq = regular file, hard link (to already seen inodes)
.IP \(bu 2
\(aqs\(aq = symlink
.IP \(bu 2
diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1
index 7fe4402db0..ad20352d5a 100644
--- a/docs/man/borg-delete.1
+++ b/docs/man/borg-delete.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-DELETE" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-delete \- Delete archives
+borg-delete \- Deletes archives.
.SH SYNOPSIS
.sp
borg [common options] delete [options] [NAME]
@@ -49,9 +49,9 @@ you run \fBborg compact\fP\&.
.sp
When in doubt, use \fB\-\-dry\-run \-\-list\fP to see what would be deleted.
.sp
-You can delete multiple archives by specifying a matching pattern,
-using the \fB\-\-match\-archives PATTERN\fP option (for more info on these patterns,
-see \fIborg_patterns\fP).
+You can delete multiple archives by specifying a match pattern using
+the \fB\-\-match\-archives PATTERN\fP option (for more information on these
+patterns, see \fIborg_patterns\fP).
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -65,58 +65,58 @@ specify the archive name
.INDENT 0.0
.TP
.B \-n\fP,\fB \-\-dry\-run
-do not change repository
+do not change the repository
.TP
.B \-\-list
-output verbose list of archives
+output a verbose list of archives
.UNINDENT
.SS Archive filters
.INDENT 0.0
.TP
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
-only consider archives matching all patterns. see \(dqborg help match\-archives\(dq.
+only consider archives matching all patterns. See \(dqborg help match\-archives\(dq.
.TP
.BI \-\-sort\-by \ KEYS
Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
.TP
.BI \-\-first \ N
-consider first N archives after other filters were applied
+consider the first N archives after other filters are applied
.TP
.BI \-\-last \ N
-consider last N archives after other filters were applied
+consider the last N archives after other filters are applied
.TP
.BI \-\-oldest \ TIMESPAN
-consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
+consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newest \ TIMESPAN
-consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m.
+consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-older \ TIMESPAN
-consider archives older than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newer \ TIMESPAN
-consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.EX
-# delete all backup archives named \(dqkenny\-files\(dq:
+# Delete all backup archives named \(dqkenny\-files\(dq:
$ borg delete \-a kenny\-files
-# actually free disk space:
+# Actually free disk space:
$ borg compact
-# delete a specific backup archive using its unique archive ID prefix
+# 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
+# Delete all archives whose names begin with the machine\(aqs hostname followed by \(dq\-\(dq
$ borg delete \-a \(aqsh:{hostname}\-*\(aq
-# delete all archives whose names contain \(dq\-2012\-\(dq
+# Delete all archives whose names contain \(dq\-2012\-\(dq
$ borg delete \-a \(aqsh:*\-2012\-*\(aq
-# see what would be deleted if delete was run without \-\-dry\-run
+# See what would be deleted if delete was run without \-\-dry\-run
$ borg delete \-\-list \-\-dry\-run \-a \(aqsh:*\-May\-*\(aq
.EE
.UNINDENT
diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1
index 3264db1d9c..4fd5f0afe9 100644
--- a/docs/man/borg-diff.1
+++ b/docs/man/borg-diff.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-DIFF" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-diff \- Diff contents of two archives
+borg-diff \- Finds differences between two archives.
.SH SYNOPSIS
.sp
borg [common options] diff [options] ARCHIVE1 ARCHIVE2 [PATH...]
@@ -37,7 +37,7 @@ borg [common options] diff [options] ARCHIVE1 ARCHIVE2 [PATH...]
.sp
This command finds differences (file contents, metadata) between ARCHIVE1 and ARCHIVE2.
.sp
-For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
+For more help on include/exclude patterns, see the output of the \fIborg_patterns\fP command.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -51,7 +51,7 @@ ARCHIVE1 name
ARCHIVE2 name
.TP
.B PATH
-paths of items inside the archives to compare; patterns are supported
+paths of items inside the archives to compare; patterns are supported.
.UNINDENT
.SS options
.INDENT 0.0
@@ -60,10 +60,7 @@ paths of items inside the archives to compare; patterns are supported
only consider numeric user and group identifiers
.TP
.B \-\-same\-chunker\-params
-Override check of chunker parameters.
-.TP
-.B \-\-sort
-Sort the output lines by file path.
+override the check of chunker parameters
.TP
.BI \-\-format \ FORMAT
specify format for differences between archives (default: \(dq{change} {path}{NL}\(dq)
@@ -71,6 +68,9 @@ specify format for differences between archives (default: \(dq{change} {path}{NL
.B \-\-json\-lines
Format output as JSON Lines.
.TP
+.B \-\-sort\-by
+Sort output by comma\-separated fields (e.g., \(aq>size_added,path\(aq).
+.TP
.B \-\-content\-only
Only compare differences in content (exclude metadata differences)
.UNINDENT
@@ -105,13 +105,22 @@ $ borg diff archive1 archive2
{\(dqpath\(dq: \(dqfile2\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: 135, \(dqremoved\(dq: 252}]}
{\(dqpath\(dq: \(dqfile4\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqadded\(dq, \(dqsize\(dq: 0}]}
{\(dqpath\(dq: \(dqfile3\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqremoved\(dq, \(dqsize\(dq: 0}]}
+
+
+# Use \-\-sort\-by with a comma\-separated list; sorts apply stably from last to first.
+# Here: primary by net size change descending, tie\-breaker by path ascending
+$ borg diff \-\-sort\-by=\(dq>size_diff,path\(dq archive1 archive2
+ +17 B \-5 B [\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1
+removed 0 B file3
+added 0 B file4
+ +135 B \-252 B file2
.EE
.UNINDENT
.UNINDENT
.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:
@@ -187,6 +196,71 @@ isomtime: file modification time change (ISO 8601)
.IP \(bu 2
isoctime: file creation time change (ISO 8601)
.UNINDENT
+.SS What is compared
+.sp
+For each matching item in both archives, Borg reports:
+.INDENT 0.0
+.IP \(bu 2
+Content changes: total added/removed bytes within files. If chunker parameters are comparable,
+Borg compares chunk IDs quickly; otherwise, it compares the content.
+.IP \(bu 2
+Metadata changes: user, group, mode, and other metadata shown inline, like
+\(dq[old_mode \-> new_mode]\(dq for mode changes. Use \fB\-\-content\-only\fP to suppress metadata changes.
+.IP \(bu 2
+Added/removed items: printed as \(dqadded SIZE path\(dq or \(dqremoved SIZE path\(dq.
+.UNINDENT
+.SS Output formats
+.sp
+The default (text) output shows one line per changed path, e.g.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
++135 B \-252 B [ \-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x ] path/to/file
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+JSON Lines output (\fB\-\-json\-lines\fP) prints one JSON object per changed path, e.g.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+{\(dqpath\(dq: \(dqPATH\(dq, \(dqchanges\(dq: [
+ {\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: BYTES, \(dqremoved\(dq: BYTES},
+ {\(dqtype\(dq: \(dqmode\(dq, \(dqold_mode\(dq: \(dq\-rw\-r\-\-r\-\-\(dq, \(dqnew_mode\(dq: \(dq\-rwxr\-xr\-x\(dq},
+ {\(dqtype\(dq: \(dqadded\(dq, \(dqsize\(dq: SIZE},
+ {\(dqtype\(dq: \(dqremoved\(dq, \(dqsize\(dq: SIZE}
+]}
+.EE
+.UNINDENT
+.UNINDENT
+.SS Sorting
+.sp
+Use \fB\-\-sort\-by FIELDS\fP where FIELDS is a comma\-separated list of fields.
+Sorts are applied stably from last to first in the given list. Prepend \(dq>\(dq for
+descending, \(dq<\(dq (or no prefix) for ascending, for example \fB\-\-sort\-by=\(dq>size_added,path\(dq\fP\&.
+Supported fields include:
+.INDENT 0.0
+.IP \(bu 2
+path: the item path
+.IP \(bu 2
+size_added: total bytes added for the item content
+.IP \(bu 2
+size_removed: total bytes removed for the item content
+.IP \(bu 2
+size_diff: size_added \- size_removed (net content change)
+.IP \(bu 2
+size: size of the item as stored in ARCHIVE2 (0 for removed items)
+.IP \(bu 2
+user, group, uid, gid, ctime, mtime: taken from the item state in ARCHIVE2 when present
+.IP \(bu 2
+ctime_diff, mtime_diff: timestamp difference (ARCHIVE2 \- ARCHIVE1)
+.UNINDENT
+.SS Performance considerations
+.sp
+diff automatically detects whether the archives were created with the same chunker
+parameters. If so, only chunk IDs are compared, which is very fast.
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1
index 641d69fc3b..6e23804db0 100644
--- a/docs/man/borg-export-tar.1
+++ b/docs/man/borg-export-tar.1
@@ -28,7 +28,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" "2025-08-02" "" "borg backup tool"
+.TH "BORG-EXPORT-TAR" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
borg-export-tar \- Export archive contents as a tarball
.SH SYNOPSIS
@@ -60,7 +60,7 @@ Alternatively, a \fB\-\-tar\-filter\fP program may be explicitly specified. It s
read the uncompressed tar stream from stdin and write a compressed/filtered
tar stream to stdout.
.sp
-Depending on the \fB\-tar\-format\fP option, these formats are created:
+Depending on the \fB\-\-tar\-format\fP option, these formats are created:
.TS
box center;
l|l|l.
diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1
index 1fa25f9dc7..22099a4d54 100644
--- a/docs/man/borg-extract.1
+++ b/docs/man/borg-extract.1
@@ -27,24 +27,28 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-EXTRACT" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-extract \- Extract archive contents
+borg-extract \- Extracts archive contents.
.SH SYNOPSIS
.sp
borg [common options] extract [options] NAME [PATH...]
.SH DESCRIPTION
.sp
-This command extracts the contents of an archive. By default the entire
-archive is extracted but a subset of files and directories can be selected
-by passing a list of \fBPATHs\fP as arguments. The file selection can further
-be restricted by using the \fB\-\-exclude\fP option.
+This command extracts the contents of an archive.
.sp
+By default, the entire archive is extracted, but a subset of files and directories
+can be selected by passing a list of \fBPATH\fP arguments. The default interpretation
+for the paths to extract is \fIpp:\fP which is a literal path\-prefix match. If you want
+to use e.g. a wildcard, you must select a different pattern style such as \fIsh:\fP or
+\fIfm:\fP\&. See \fIborg_patterns\fP for more information.
+.sp
+The file selection can be further restricted by using the \fB\-\-exclude\fP option.
For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
.sp
By using \fB\-\-dry\-run\fP, you can do all extraction steps except actually writing the
-output data: reading metadata and data chunks from the repo, checking the hash/hmac,
-decrypting, decompressing.
+output data: reading metadata and data chunks from the repository, checking the hash/HMAC,
+decrypting, and decompressing.
.sp
\fB\-\-progress\fP can be slower than no progress display, since it makes one additional
pass over the archive metadata.
@@ -56,8 +60,8 @@ Currently, extract always writes into the current working directory (\(dq.\(dq),
so make sure you \fBcd\fP to the right place before calling \fBborg extract\fP\&.
.sp
When parent directories are not extracted (because of using file/directory selection
-or any other reason), borg can not restore parent directories\(aq metadata, e.g. owner,
-group, permission, etc.
+or any other reason), Borg cannot restore parent directories\(aq metadata, e.g., owner,
+group, permissions, etc.
.UNINDENT
.UNINDENT
.SH OPTIONS
@@ -76,13 +80,13 @@ paths to extract; patterns are supported
.INDENT 0.0
.TP
.B \-\-list
-output verbose list of items (files, dirs, ...)
+output a verbose list of items (files, dirs, ...)
.TP
.B \-n\fP,\fB \-\-dry\-run
do not actually change any files
.TP
.B \-\-numeric\-ids
-only obey numeric user and group identifiers
+only use numeric user and group identifiers
.TP
.B \-\-noflags
do not extract/set flags (e.g. NODUMP, IMMUTABLE)
@@ -97,10 +101,10 @@ do not extract/set xattrs
write all extracted data to stdout
.TP
.B \-\-sparse
-create holes in output sparse file from all\-zero chunks
+create holes in the output sparse file from all\-zero chunks
.TP
.B \-\-continue
-continue a previously interrupted extraction of same archive
+continue a previously interrupted extraction of the same archive
.UNINDENT
.SS Include/Exclude options
.INDENT 0.0
@@ -140,6 +144,9 @@ $ borg extract my\-files home/USERNAME/src
# Extract the \(dqsrc\(dq directory but exclude object files
$ borg extract my\-files home/USERNAME/src \-\-exclude \(aq*.o\(aq
+# Extract only the C files
+$ borg extract my\-files \(aqsh:home/USERNAME/src/*.c\(aq
+
# Restore a raw device (must not be active/in use/mounted at that time)
$ borg extract \-\-stdout my\-sdx | dd of=/dev/sdx bs=10M
.EE
diff --git a/docs/man/borg-import-tar.1 b/docs/man/borg-import-tar.1
index 4cab0693b1..76d999685c 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" "2025-08-02" "" "borg backup tool"
+.TH "BORG-IMPORT-TAR" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
borg-import-tar \- Create a backup archive from a tarball
.SH SYNOPSIS
@@ -137,25 +137,25 @@ select compression algorithm, see the output of the \(dqborg help compression\(d
.INDENT 3.5
.sp
.EX
-# export as uncompressed tar
+# Export as an uncompressed tar archive
$ borg export\-tar Monday Monday.tar
-# import an uncompressed tar
+# Import an uncompressed tar archive
$ borg import\-tar Monday Monday.tar
-# exclude some file types, compress using gzip
+# Exclude some file types and compress using gzip
$ borg export\-tar Monday Monday.tar.gz \-\-exclude \(aq*.so\(aq
-# use higher compression level with gzip
+# Use a higher compression level with gzip
$ borg export\-tar \-\-tar\-filter=\(dqgzip \-9\(dq Monday Monday.tar.gz
-# copy an archive from repoA to repoB
+# Copy an archive from repoA to repoB
$ borg \-r repoA export\-tar \-\-tar\-format=BORG archive \- | borg \-r repoB import\-tar archive \-
-# export a tar, but instead of storing it on disk, upload it to remote site using curl
+# Export a tar, but instead of storing it on disk, upload it to a remote site using curl
$ borg export\-tar Monday \- | curl \-\-data\-binary @\- https://somewhere/to/POST
-# remote extraction via \(dqtarpipe\(dq
+# Remote extraction via \(aqtarpipe\(aq
$ borg export\-tar Monday \- | ssh somewhere \(dqcd extracted; tar x\(dq
.EE
.UNINDENT
@@ -186,7 +186,7 @@ archive contents (all items with metadata and data)
Lost:
.INDENT 0.0
.IP \(bu 2
-some archive metadata (like the original commandline, execution time, etc.)
+some archive metadata (like the original command line, execution time, etc.)
.UNINDENT
.sp
Please note:
diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1
index 6a58dadd27..48848e3157 100644
--- a/docs/man/borg-info.1
+++ b/docs/man/borg-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-INFO" "1" "2025-08-02" "" "borg backup tool"
+.TH "BORG-INFO" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
borg-info \- Show archive details such as disk space used
.SH SYNOPSIS
@@ -39,11 +39,11 @@ This command displays detailed information about the specified archive.
.sp
Please note that the deduplicated sizes of the individual archives do not add
up to the deduplicated size of the repository (\(dqall archives\(dq), because the two
-are meaning different things:
+mean different things:
.sp
This archive / deduplicated size = amount of data stored ONLY for this archive
= unique chunks of this archive.
-All archives / deduplicated size = amount of data stored in the repo
+All archives / deduplicated size = amount of data stored in the repository
= all chunks in the repository.
.SH OPTIONS
.sp
@@ -64,28 +64,28 @@ format output as JSON
.INDENT 0.0
.TP
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
-only consider archives matching all patterns. see \(dqborg help match\-archives\(dq.
+only consider archives matching all patterns. See \(dqborg help match\-archives\(dq.
.TP
.BI \-\-sort\-by \ KEYS
Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
.TP
.BI \-\-first \ N
-consider first N archives after other filters were applied
+consider the first N archives after other filters are applied
.TP
.BI \-\-last \ N
-consider last N archives after other filters were applied
+consider the last N archives after other filters are applied
.TP
.BI \-\-oldest \ TIMESPAN
-consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
+consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newest \ TIMESPAN
-consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m.
+consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-older \ TIMESPAN
-consider archives older than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newer \ TIMESPAN
-consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
diff --git a/docs/man/borg-key-change-location.1 b/docs/man/borg-key-change-location.1
index 0c0e75a72f..7415101432 100644
--- a/docs/man/borg-key-change-location.1
+++ b/docs/man/borg-key-change-location.1
@@ -27,20 +27,20 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-LOCATION" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-key-change-location \- Change repository key location
+borg-key-change-location \- Changes the repository key location.
.SH SYNOPSIS
.sp
borg [common options] key change\-location [options] KEY_LOCATION
.SH DESCRIPTION
.sp
-Change the location of a borg key. The key can be stored at different locations:
+Change the location of a Borg key. The key can be stored at different locations:
.INDENT 0.0
.IP \(bu 2
keyfile: locally, usually in the home directory
.IP \(bu 2
-repokey: inside the repo (in the repo config)
+repokey: inside the repository (in the repository config)
.UNINDENT
.sp
Please note:
diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1
index f039a9c33b..43ad4afa62 100644
--- a/docs/man/borg-key-change-passphrase.1
+++ b/docs/man/borg-key-change-passphrase.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-PASSPHRASE" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-key-change-passphrase \- Change repository key file passphrase
+borg-key-change-passphrase \- Changes the repository key file passphrase.
.SH SYNOPSIS
.sp
borg [common options] key change\-passphrase [options]
diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1
index 8ffde93ef8..e0e1c0649d 100644
--- a/docs/man/borg-key-export.1
+++ b/docs/man/borg-key-export.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-KEY-EXPORT" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-key-export \- Export the repository key for backup
+borg-key-export \- Exports the repository key for backup.
.SH SYNOPSIS
.sp
borg [common options] key export [options] [PATH]
@@ -72,7 +72,7 @@ where to store the backup
Create an export suitable for printing and later type\-in
.TP
.B \-\-qr\-html
-Create an html file suitable for printing and later type\-in or qr scan
+Create an HTML file suitable for printing and later type\-in or QR scan
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1
index bc112b0436..948029bcff 100644
--- a/docs/man/borg-key-import.1
+++ b/docs/man/borg-key-import.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-KEY-IMPORT" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-key-import \- Import the repository key from backup
+borg-key-import \- Imports the repository key from backup.
.SH SYNOPSIS
.sp
borg [common options] key import [options] [PATH]
diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1
index 71ce9d476f..86c2290ac5 100644
--- a/docs/man/borg-key.1
+++ b/docs/man/borg-key.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-KEY" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-key \- Manage a keyfile or repokey of a repository
+borg-key \- Manage the keyfile or repokey of a repository
.SH SYNOPSIS
.nf
borg [common options] key export ...
diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1
index 3ca16dcbcd..a37d04c3cb 100644
--- a/docs/man/borg-list.1
+++ b/docs/man/borg-list.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-LIST" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-list \- List archive contents
+borg-list \- List archive contents.
.SH SYNOPSIS
.sp
borg [common options] list [options] NAME [PATH...]
@@ -37,7 +37,7 @@ borg [common options] list [options] NAME [PATH...]
.sp
This command lists the contents of an archive.
.sp
-For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
+For more help on include/exclude patterns, see the output of \fIborg_patterns\fP\&.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -63,7 +63,7 @@ specify format for file listing (default: \(dq{mode} {user:6} {group:6} {size:8}
Format output as JSON Lines. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text.
.TP
.BI \-\-depth \ N
-only list files up to the specified directory level depth
+only list files up to the specified directory depth
.UNINDENT
.SS Include/Exclude options
.INDENT 0.0
@@ -122,7 +122,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:
@@ -182,6 +182,8 @@ target: link target for symlinks
.IP \(bu 2
hlid: hard link identity (same if hardlinking same fs object)
.IP \(bu 2
+inode: inode number
+.IP \(bu 2
flags: file flags
.IP \(bu 2
size: file size
diff --git a/docs/man/borg-match-archives.1 b/docs/man/borg-match-archives.1
index 1b04a909a8..cb8a1de489 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" "2025-08-02" "" "borg backup tool"
+.TH "BORG-MATCH-ARCHIVES" "1" "2025-12-23" "" "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 c76874a213..71dbfa11c3 100644
--- a/docs/man/borg-mount.1
+++ b/docs/man/borg-mount.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-MOUNT" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-mount \- Mount archive or an entire repository as a FUSE filesystem
+borg-mount \- Mounts an archive or an entire repository as a FUSE filesystem.
.SH SYNOPSIS
.sp
borg [common options] mount [options] MOUNTPOINT [PATH...]
@@ -45,18 +45,18 @@ 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
-Unless the \fB\-\-foreground\fP option is given the command will run in the
-background until the filesystem is \fBumounted\fP\&.
+Unless the \fB\-\-foreground\fP option is given, the command will run in the
+background until the filesystem is \fBunmounted\fP\&.
.sp
Performance tips:
.INDENT 0.0
.IP \(bu 2
-when doing a \(dqwhole repository\(dq mount:
-do not enter archive dirs if not needed, this avoids on\-demand loading.
+When doing a \(dqwhole repository\(dq mount:
+do not enter archive directories if not needed; this avoids on\-demand loading.
.IP \(bu 2
-only mount a specific archive, not the whole repository.
+Only mount a specific archive, not the whole repository.
.IP \(bu 2
-only mount specific paths in a specific archive, not the complete archive.
+Only mount specific paths in a specific archive, not the complete archive.
.UNINDENT
.sp
The command \fBborgfs\fP provides a wrapper for \fBborg mount\fP\&. This can also be
@@ -69,39 +69,39 @@ To allow a regular user to use fstab entries, add the \fBuser\fP option:
For FUSE configuration and mount options, see the mount.fuse(8) manual page.
.sp
Borg\(aqs default behavior is to use the archived user and group names of each
-file and map them to the system\(aqs respective user and group ids.
+file and map them to the system\(aqs respective user and group IDs.
Alternatively, using \fBnumeric\-ids\fP will instead use the archived user and
-group ids without any mapping.
+group IDs without any mapping.
.sp
The \fBuid\fP and \fBgid\fP mount options (implemented by Borg) can be used to
-override the user and group ids of all files (i.e., \fBborg mount \-o
+override the user and group IDs of all files (i.e., \fBborg mount \-o
uid=1000,gid=1000\fP).
.sp
The man page references \fBuser_id\fP and \fBgroup_id\fP mount options
-(implemented by fuse) which specify the user and group id of the mount owner
-(aka, the user who does the mounting). It is set automatically by libfuse (or
+(implemented by FUSE) which specify the user and group ID of the mount owner
+(also known as the user who does the mounting). It is set automatically by libfuse (or
the filesystem if libfuse is not used). However, you should not specify these
-manually. Unlike the \fBuid\fP and \fBgid\fP mount options which affect all files,
-\fBuser_id\fP and \fBgroup_id\fP affect the user and group id of the mounted
+manually. Unlike the \fBuid\fP and \fBgid\fP mount options, which affect all files,
+\fBuser_id\fP and \fBgroup_id\fP affect the user and group ID of the mounted
(base) directory.
.sp
-Additional mount options supported by borg:
+Additional mount options supported by Borg:
.INDENT 0.0
.IP \(bu 2
\fBversions\fP: when used with a repository mount, this gives a merged, versioned
-view of the files in the archives. EXPERIMENTAL, layout may change in future.
+view of the files in the archives. EXPERIMENTAL; layout may change in the future.
.IP \(bu 2
-\fBallow_damaged_files\fP: by default damaged files (where chunks are missing)
+\fBallow_damaged_files\fP: by default, damaged files (where chunks are missing)
will return EIO (I/O error) when trying to read the related parts of the file.
Set this option to replace the missing parts with all\-zero bytes.
.IP \(bu 2
\fBignore_permissions\fP: for security reasons the \fBdefault_permissions\fP mount
-option is internally enforced by borg. \fBignore_permissions\fP can be given to
+option is internally enforced by Borg. \fBignore_permissions\fP can be given to
not enforce \fBdefault_permissions\fP\&.
.UNINDENT
.sp
-The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users
-to tweak the performance. It sets the number of cached data chunks; additional
+The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is intended for advanced users
+to tweak performance. It sets the number of cached data chunks; additional
memory usage can be up to ~8 MiB times this number. The default is the number
of CPU cores.
.sp
@@ -111,6 +111,13 @@ to delete data unintentionally.
.sp
When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
but other signals or crashes do not.
+.sp
+Debugging:
+.sp
+\fBborg mount\fP usually daemonizes and the daemon process sends stdout/stderr
+to /dev/null. Thus, you need to either use \fB\-f / \-\-foreground\fP to make it stay
+in the foreground and not daemonize, or use \fBBORG_LOGGING_CONF\fP to reconfigure
+the logger to output to a file.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -118,7 +125,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.INDENT 0.0
.TP
.B MOUNTPOINT
-where to mount filesystem
+where to mount the filesystem
.TP
.B PATH
paths to extract; patterns are supported
@@ -130,37 +137,37 @@ paths to extract; patterns are supported
stay in foreground, do not daemonize
.TP
.B \-o
-Extra mount options
+extra mount options
.TP
.B \-\-numeric\-ids
-use numeric user and group identifiers from archive(s)
+use numeric user and group identifiers from archives
.UNINDENT
.SS Archive filters
.INDENT 0.0
.TP
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
-only consider archives matching all patterns. see \(dqborg help match\-archives\(dq.
+only consider archives matching all patterns. See \(dqborg help match\-archives\(dq.
.TP
.BI \-\-sort\-by \ KEYS
Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
.TP
.BI \-\-first \ N
-consider first N archives after other filters were applied
+consider the first N archives after other filters are applied
.TP
.BI \-\-last \ N
-consider last N archives after other filters were applied
+consider the last N archives after other filters are applied
.TP
.BI \-\-oldest \ TIMESPAN
-consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
+consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newest \ TIMESPAN
-consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m.
+consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-older \ TIMESPAN
-consider archives older than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newer \ TIMESPAN
-consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.UNINDENT
.SS Include/Exclude options
.INDENT 0.0
diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1
index c956d78a93..82165f0cd1 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" "2025-08-02" "" "borg backup tool"
+.TH "BORG-PATTERNS" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
borg-patterns \- Details regarding patterns
.SH DESCRIPTION
@@ -49,20 +49,32 @@ in the file given with \fB\-\-patterns\-from\fP option and
for \fBPATH\fP arguments that explicitly support them.
.UNINDENT
.sp
-Borg always stores all file paths normalized and relative to the
-current recursion root. The recursion root is also named \fBPATH\fP in
-Borg commands like \fIborg create\fP that do a file discovery, so do not
-confuse the root with the \fBPATH\fP argument of e.g. \fIborg extract\fP\&.
+The path/filenames used as input for the pattern matching start with the
+currently active recursion root. You usually give the recursion root(s)
+when invoking borg and these can be either relative or absolute paths.
.sp
-Starting with Borg 1.2, paths that are matched against patterns always
-appear relative. If you give \fB/absolute/\fP as root, the paths going
-into the matcher will start with \fBabsolute/\fP\&.
-If you give \fB\&../../relative\fP as root, the paths will be normalized
-as \fBrelative/\fP\&.
+Be careful, your patterns must match the archived paths:
+.INDENT 0.0
+.IP \(bu 2
+Archived paths never start with a leading slash (\(aq/\(aq), nor with \(aq.\(aq, nor with \(aq..\(aq.
+.INDENT 2.0
+.IP \(bu 2
+When you back up absolute paths like \fB/home/user\fP, the archived
+paths start with \fBhome/user\fP\&.
+.IP \(bu 2
+When you back up relative paths like \fB\&./src\fP, the archived paths
+start with \fBsrc\fP\&.
+.IP \(bu 2
+When you back up relative paths like \fB\&../../src\fP, the archived paths
+start with \fBsrc\fP\&.
+.UNINDENT
+.UNINDENT
.sp
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
+The default pattern style for \fB\-\-exclude\fP differs from \fB\-\-pattern\fP, see below.
.INDENT 0.0
.TP
.B Fnmatch
@@ -99,13 +111,13 @@ 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.
.TP
.B Path prefix, selector \fBpp:\fP
-This pattern style is useful to match whole sub\-directories. The pattern
+This pattern style is useful to match whole subdirectories. The pattern
\fBpp:root/somedir\fP matches \fBroot/somedir\fP and everything therein.
A leading path separator is always removed.
.TP
.B Path full\-match, selector \fBpf:\fP
This pattern style is (only) useful to match full paths.
-This is kind of a pseudo pattern as it can not have any variable or
+This is kind of a pseudo pattern as it cannot have any variable or
unspecified parts \- the full path must be given. \fBpf:root/file.ext\fP
matches \fBroot/file.ext\fP only. A leading path separator is always
removed.
@@ -136,7 +148,7 @@ Exclusions can be passed via the command line option \fB\-\-exclude\fP\&. When u
from within a shell, the patterns should be quoted to protect them from
expansion.
.sp
-Patterns matching special characters, e.g. white space, within a shell may
+Patterns matching special characters, e.g. whitespace, within a shell may
require adjustments, such as putting quotation marks around the arguments.
Example:
Using bash, the following command line option would match and exclude \(dqitem name\(dq:
@@ -160,6 +172,17 @@ Examples:
.INDENT 3.5
.sp
.EX
+# Exclude a directory anywhere in the tree named \(ga\(gasteamapps/common\(ga\(ga
+# (and everything below it), regardless of where it appears:
+$ borg create \-e \(aqsh:**/steamapps/common/**\(aq archive /
+
+# Exclude the contents of \(ga\(ga/home/user/.cache\(ga\(ga:
+$ borg create \-e \(aqsh:home/user/.cache/**\(aq archive /home/user
+$ borg create \-e home/user/.cache/ archive /home/user
+
+# The file \(aq/home/user/.cache/important\(aq is *not* backed up:
+$ borg create \-e home/user/.cache/ archive / /home/user/.cache/important
+
# Exclude \(aq/home/user/file.o\(aq but not \(aq/home/user/file.odt\(aq:
$ borg create \-e \(aq*.o\(aq archive /
@@ -167,11 +190,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 /
-# Exclude the contents of \(aq/home/user/cache\(aq but not the directory itself:
-$ borg create \-e home/user/cache/ archive /
-
-# The file \(aq/home/user/cache/important\(aq is *not* backed up:
-$ borg create \-e home/user/cache/ archive / /home/user/cache/important
# The contents of directories in \(aq/home\(aq are not backed up when their name
# ends in \(aq.tmp\(aq
@@ -204,11 +222,13 @@ A recursion root path starts with the prefix \fBR\fP, followed by a path
(a plain path, not a file pattern). Use this prefix to have the root
paths in the patterns file rather than as command line arguments.
.TP
-.B Pattern style prefix \fBP\fP
+.B Pattern style prefix \fBP\fP (only useful within patterns files)
To change the default pattern style, use the \fBP\fP prefix, followed by
the pattern style abbreviation (\fBfm\fP, \fBpf\fP, \fBpp\fP, \fBre\fP, \fBsh\fP).
-All patterns following this line will use this style until another style
-is specified.
+All patterns following this line in the same patterns file will use this
+style until another style is specified or the end of the file is reached.
+When the current patterns file is finished, the default pattern style will
+reset.
.TP
.B Exclude pattern prefix \fB\-\fP
Use the prefix \fB\-\fP, followed by a pattern, to define an exclusion.
@@ -272,7 +292,7 @@ character that indicates the action (e.g. \(aqx\(aq for excluding, see
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
-It\(aqs possible that a sub\-directory/file is matched while parent
+It is possible that a subdirectory or file is matched while its parent
directories are not. In that case, parent directories are not backed
up and thus their user, group, permission, etc. cannot be restored.
.UNINDENT
diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1
index 2412070e52..a8612b3d04 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" "2025-08-02" "" "borg backup tool"
+.TH "BORG-PLACEHOLDERS" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
borg-placeholders \- Details regarding placeholders
.SH DESCRIPTION
@@ -47,12 +47,12 @@ 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
+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
+You can also supply your own format string
, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S}
.TP
.B {user}
diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1
index 50549b32a0..2f75c5804a 100644
--- a/docs/man/borg-prune.1
+++ b/docs/man/borg-prune.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-PRUNE" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-prune \- Prune repository archives according to specified rules
+borg-prune \- Prune archives according to specified rules.
.SH SYNOPSIS
.sp
borg [common options] prune [options] [NAME]
@@ -111,10 +111,10 @@ specify the archive name
.INDENT 0.0
.TP
.B \-n\fP,\fB \-\-dry\-run
-do not change repository
+do not change the repository
.TP
.B \-\-list
-output verbose list of archives it keeps/prunes
+output a verbose list of archives it keeps/prunes
.TP
.B \-\-short
use a less wide archive part format
@@ -162,41 +162,41 @@ number of yearly archives to keep
.INDENT 0.0
.TP
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
-only consider archives matching all patterns. see \(dqborg help match\-archives\(dq.
+only consider archives matching all patterns. See \(dqborg help match\-archives\(dq.
.TP
.BI \-\-oldest \ TIMESPAN
-consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
+consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newest \ TIMESPAN
-consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m.
+consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-older \ TIMESPAN
-consider archives older than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newer \ TIMESPAN
-consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.UNINDENT
.SH EXAMPLES
.sp
-Be careful, prune is a potentially dangerous command, it will remove backup
+Be careful: prune is a potentially dangerous command that removes 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.
+By default, prune applies to \fBall archives in the repository\fP unless 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.
+that name to prune as well, so it operates only 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
+Alternatively, you can use \fB\-a\fP/\fB\-\-match\-archives\fP to match archive names
+and select a subset of them.
+When using \fB\-a\fP, be careful to choose a good pattern — for example, 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.
+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.
+Do not forget to run \fBborg compact \-v\fP after prune to actually free disk space.
.INDENT 0.0
.INDENT 3.5
.sp
@@ -205,11 +205,11 @@ Don\(aqt forget to run \fBborg compact \-v\fP after prune to actually free disk
# Do a dry\-run without actually deleting anything.
$ borg prune \-v \-\-list \-\-dry\-run \-\-keep\-daily=7 \-\-keep\-weekly=4
-# Similar as above but only apply to the archive series named \(aq{hostname}\(aq:
+# Similar to the 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:
+# Similar to the above, but apply to archive names starting with the hostname
+# of the machine followed by a \(aq\-\(aq character:
$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-a \(aqsh:{hostname}\-*\(aq
# Keep 7 end of day, 4 additional end of week archives,
diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1
index 75061fb228..4f4e32ba0f 100644
--- a/docs/man/borg-recreate.1
+++ b/docs/man/borg-recreate.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-RECREATE" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-recreate \- Re-create archives
+borg-recreate \- Recreate archives.
.SH SYNOPSIS
.sp
borg [common options] recreate [options] [PATH...]
@@ -37,15 +37,15 @@ borg [common options] recreate [options] [PATH...]
.sp
Recreate the contents of existing archives.
.sp
-recreate is a potentially dangerous function and might lead to data loss
+Recreate is a potentially dangerous function and might lead to data loss
(if used wrongly). BE VERY CAREFUL!
.sp
Important: Repository disk space is \fBnot\fP freed until you run \fBborg compact\fP\&.
.sp
\fB\-\-exclude\fP, \fB\-\-exclude\-from\fP, \fB\-\-exclude\-if\-present\fP, \fB\-\-keep\-exclude\-tags\fP
and PATH have the exact same semantics as in \(dqborg create\(dq, but they only check
-for files in the archives and not in the local file system. If PATHs are specified,
-the resulting archives will only contain files from these PATHs.
+files in the archives and not in the local filesystem. If paths are specified,
+the resulting archives will contain only files from those paths.
.sp
Note that all paths in an archive are relative, therefore absolute patterns/paths
will \fInot\fP match (\fB\-\-exclude\fP, \fB\-\-exclude\-from\fP, PATHs).
@@ -54,9 +54,9 @@ will \fInot\fP match (\fB\-\-exclude\fP, \fB\-\-exclude\-from\fP, PATHs).
used to have upgraded Borg 0.xx archives deduplicate with Borg 1.x archives.
.sp
\fBUSE WITH CAUTION.\fP
-Depending on the PATHs and patterns given, recreate can be used to
+Depending on the paths and patterns given, recreate can be used to
delete files from archives permanently.
-When in doubt, use \fB\-\-dry\-run \-\-verbose \-\-list\fP to see how patterns/PATHS are
+When in doubt, use \fB\-\-dry\-run \-\-verbose \-\-list\fP to see how patterns/paths are
interpreted. See \fIlist_item_flags\fP in \fBborg create\fP for details.
.sp
The archive being recreated is only removed after the operation completes. The
@@ -71,8 +71,8 @@ chunker params.
.sp
If your most recent borg check found missing chunks, please first run another
backup for the same data, before doing any rechunking. If you are lucky, that
-will re\-create the missing chunks. Optionally, do another borg check, to see
-if the chunks are still missing).
+will recreate the missing chunks. Optionally, do another borg check to see
+if the chunks are still missing.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -119,34 +119,34 @@ exclude directories that contain a CACHEDIR.TAG file ( /config
+# repokey: stores the encrypted key in /config
$ borg repo\-create \-\-encryption=repokey\-aes\-ocb
-# keyfile: stores the (encrypted) key into ~/.config/borg/keys/
+# keyfile: stores the encrypted key in ~/.config/borg/keys/
$ borg repo\-create \-\-encryption=keyfile\-aes\-ocb
.EE
.UNINDENT
diff --git a/docs/man/borg-repo-delete.1 b/docs/man/borg-repo-delete.1
index 7a2d359af7..cd86043278 100644
--- a/docs/man/borg-repo-delete.1
+++ b/docs/man/borg-repo-delete.1
@@ -27,15 +27,15 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-REPO-DELETE" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-repo-delete \- Delete a repository
+borg-repo-delete \- Deletes a repository.
.SH SYNOPSIS
.sp
borg [common options] repo\-delete [options]
.SH DESCRIPTION
.sp
-This command deletes the complete repository.
+This command deletes a complete repository.
.sp
When you delete a complete repository, the security info and local cache for it
(if any) are also deleted. Alternatively, you can delete just the local cache
@@ -50,13 +50,13 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.INDENT 0.0
.TP
.B \-n\fP,\fB \-\-dry\-run
-do not change repository
+do not change the repository
.TP
.B \-\-list
-output verbose list of archives
+output a verbose list of archives
.TP
.B \-\-force
-force deletion of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work.
+force deletion of corrupted archives; use \fB\-\-force \-\-force\fP if a single \fB\-\-force\fP does not work.
.TP
.B \-\-cache\-only
delete only the local cache for the given repository
diff --git a/docs/man/borg-repo-info.1 b/docs/man/borg-repo-info.1
index 127fa9cc9e..8a78b693b8 100644
--- a/docs/man/borg-repo-info.1
+++ b/docs/man/borg-repo-info.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-REPO-INFO" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-repo-info \- Show repository infos
+borg-repo-info \- Show repository information.
.SH SYNOPSIS
.sp
borg [common options] repo\-info [options]
diff --git a/docs/man/borg-repo-list.1 b/docs/man/borg-repo-list.1
index c8f9978e31..e351a6d235 100644
--- a/docs/man/borg-repo-list.1
+++ b/docs/man/borg-repo-list.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-REPO-LIST" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-repo-list \- List the archives contained in a repository
+borg-repo-list \- List the archives contained in a repository.
.SH SYNOPSIS
.sp
borg [common options] repo\-list [options]
@@ -55,28 +55,28 @@ Format output as JSON. The form of \fB\-\-format\fP is ignored, but keys used in
.INDENT 0.0
.TP
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
-only consider archives matching all patterns. see \(dqborg help match\-archives\(dq.
+only consider archives matching all patterns. See \(dqborg help match\-archives\(dq.
.TP
.BI \-\-sort\-by \ KEYS
Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
.TP
.BI \-\-first \ N
-consider first N archives after other filters were applied
+consider the first N archives after other filters are applied
.TP
.BI \-\-last \ N
-consider last N archives after other filters were applied
+consider the last N archives after other filters are applied
.TP
.BI \-\-oldest \ TIMESPAN
-consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
+consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newest \ TIMESPAN
-consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m.
+consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-older \ TIMESPAN
-consider archives older than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newer \ TIMESPAN
-consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.B \-\-deleted
consider only soft\-deleted archives.
@@ -100,7 +100,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:
diff --git a/docs/man/borg-repo-space.1 b/docs/man/borg-repo-space.1
index cf8adedbe9..4c58da83b0 100644
--- a/docs/man/borg-repo-space.1
+++ b/docs/man/borg-repo-space.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-REPO-SPACE" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-repo-space \- Manage reserved space in repository
+borg-repo-space \- Manages reserved space in the repository.
.SH SYNOPSIS
.sp
borg [common options] repo\-space [options]
@@ -37,15 +37,14 @@ borg [common options] repo\-space [options]
.sp
This command manages reserved space in a repository.
.sp
-Borg can not work in disk\-full conditions (can not lock a repo and thus can
-not run prune/delete or compact operations to free disk space).
+Borg cannot work in disk\-full conditions (it cannot lock a repository and thus cannot
+run prune/delete or compact operations to free disk space).
.sp
-To avoid running into dead\-end situations like that, you can put some objects
-into a repository that take up some disk space. If you ever run into a
-disk\-full situation, you can free that space and then borg will be able to
-run normally, so you can free more disk space by using prune/delete/compact.
-After that, don\(aqt forget to reserve space again, in case you run into that
-situation again at a later time.
+To avoid running into such dead\-end situations, you can put some objects into a
+repository that take up disk space. If you ever run into a disk\-full situation, you
+can free that space, and then Borg will be able to run normally so you can free more
+disk space by using \fBborg prune\fP/\fBborg delete\fP/\fBborg compact\fP\&. After that, do
+not forget to reserve space again, in case you run into that situation again later.
.sp
Examples:
.INDENT 0.0
@@ -54,10 +53,10 @@ Examples:
.EX
# Create a new repository:
$ borg repo\-create ...
-# Reserve approx. 1GB of space for emergencies:
+# Reserve approx. 1 GiB of space for emergencies:
$ borg repo\-space \-\-reserve 1G
-# Check amount of reserved space in the repository:
+# Check the amount of reserved space in the repository:
$ borg repo\-space
# EMERGENCY! Free all reserved space to get things back to normal:
@@ -70,7 +69,7 @@ $ borg repo\-space \-\-reserve 1G # reserve space again for next time
.UNINDENT
.UNINDENT
.sp
-Reserved space is always rounded up to use full reservation blocks of 64MiB.
+Reserved space is always rounded up to full reservation blocks of 64 MiB.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -81,7 +80,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
Amount of space to reserve (e.g. 100M, 1G). Default: 0.
.TP
.B \-\-free
-Free all reserved space. Don\(aqt forget to reserve space later again.
+Free all reserved space. Do not forget to reserve space again later.
.UNINDENT
.SH SEE ALSO
.sp
diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1
index b5f3890edb..e427f9ee3d 100644
--- a/docs/man/borg-serve.1
+++ b/docs/man/borg-serve.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-SERVE" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-serve \- Start in server mode. This command is usually not used manually.
+borg-serve \- Starts in server mode. This command is usually not used manually.
.SH SYNOPSIS
.sp
borg [common options] serve [options]
@@ -37,36 +37,36 @@ borg [common options] serve [options]
.sp
This command starts a repository server process.
.sp
-borg serve can currently support:
+\fIborg serve\fP currently supports:
.INDENT 0.0
.IP \(bu 2
-Getting automatically started via ssh when the borg client uses a \&...
-remote repository. In this mode, \fIborg serve\fP will live until that ssh connection
-gets terminated.
+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
-Getting started by some other means (not by the borg client) as a long\-running socket
+Being started by some other means (not by the borg client) as a long\-running socket
server to be used for borg clients using a socket://... repository (see the \fI\-\-socket\fP
-option if you do not want to use the default path for the socket and pid file).
+option if you do not want to use the default path for the socket and PID file).
.UNINDENT
.sp
-Please note that \fIborg serve\fP does not support giving a specific repository via the
-\fI\-\-repo\fP option or \fIBORG_REPO\fP environment variable. It is always the borg client which
-specifies the repo to use when talking to \fIborg serve\fP\&.
+Please note that \fIborg serve\fP does not support providing a specific repository via the
+\fI\-\-repo\fP option or the \fIBORG_REPO\fP environment variable. It is always the borg client that
+specifies the repository to use when communicating with \fIborg serve\fP\&.
.sp
-The \-\-permissions option allows enforcing repository permissions:
+The \-\-permissions option enforces repository permissions:
.INDENT 0.0
.IP \(bu 2
-\fIall\fP: All permissions are granted (default, permissions system is not used)
+\fIall\fP: All permissions are granted. (Default; the permissions system is not used.)
.IP \(bu 2
-\fIno\-delete\fP: Allow reading and writing, disallow deleting and overwriting data.
-New archives can be created, existing archives can not be deleted. New chunks can
-be added, existing chunks can not be deleted or overwritten.
+\fIno\-delete\fP: Allow reading and writing; disallow deleting and overwriting data.
+New archives can be created; existing archives cannot be deleted. New chunks can
+be added; existing chunks cannot be deleted or overwritten.
.IP \(bu 2
-\fIwrite\-only\fP: Allow writing, disallow reading data.
-New archives can be created, existing archives can not be read.
-New chunks can be added, existing chunks can not be read, deleted or overwritten.
+\fIwrite\-only\fP: Allow writing; disallow reading data.
+New archives can be created; existing archives cannot be read.
+New chunks can be added; existing chunks cannot be read, deleted, or overwritten.
.IP \(bu 2
-\fIread\-only\fP: Allow reading, disallow writing or deleting data.
+\fIread\-only\fP: Allow reading; disallow writing or deleting data.
Existing archives can be read, but no archives can be created or deleted.
.UNINDENT
.SH OPTIONS
@@ -76,10 +76,10 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.INDENT 0.0
.TP
.BI \-\-restrict\-to\-path \ PATH
-restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub\-directories is granted implicitly; PATH doesn\(aqt need to point directly to a repository.
+Restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all subdirectories is granted implicitly; PATH does not need to point directly to a repository.
.TP
.BI \-\-restrict\-to\-repository \ PATH
-restrict repository access. Only the repository located at PATH (no sub\-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike \fB\-\-restrict\-to\-path\fP sub\-directories are not accessible; PATH needs to point directly at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
+Restrict repository access. Only the repository located at PATH (no subdirectories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike \fB\-\-restrict\-to\-path\fP, subdirectories are not accessible; PATH must point directly to a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
.TP
.B \-\-permissions
Set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable.
@@ -130,12 +130,12 @@ command=\(dqBORG_XXX=value borg serve [...]\(dq,restrict ssh\-rsa [...]
.INDENT 3.5
The examples above use the \fBrestrict\fP directive and assume a POSIX
compliant shell set as the user\(aqs login shell.
-This does automatically block potential dangerous ssh features, even when
+This automatically blocks potentially dangerous SSH features, even when
they are added in a future update. Thus, this option should be preferred.
.sp
-If you\(aqre using openssh\-server < 7.2, however, you have to specify explicitly
-the ssh features to restrict and cannot simply use the restrict option as it
-has been introduced in v7.2. We recommend to use
+If you are using OpenSSH server < 7.2, however, you must explicitly
+specify the SSH features to restrict and cannot simply use the \fBrestrict\fP option, as it
+was introduced in v7.2. We recommend using
\fBno\-port\-forwarding,no\-X11\-forwarding,no\-pty,no\-agent\-forwarding,no\-user\-rc\fP
in this case.
.UNINDENT
@@ -147,9 +147,9 @@ Details about sshd usage: sshd(8)
+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,
diff --git a/docs/man/borg-tag.1 b/docs/man/borg-tag.1
index 3e641f05fd..fd3fb6d7b4 100644
--- a/docs/man/borg-tag.1
+++ b/docs/man/borg-tag.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-TAG" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-tag \- Manage tags
+borg-tag \- Manage tags.
.SH SYNOPSIS
.sp
borg [common options] tag [options] [NAME]
@@ -42,13 +42,13 @@ Borg archives can have a set of tags which can be used for matching archives.
You can set the tags to a specific set of tags or you can add or remove
tags from the current set of tags.
.sp
-User defined tags must not start with \fI@\fP because such tags are considered
+User\-defined tags must not start with \fI@\fP because such tags are considered
special and users are only allowed to use known special tags:
.sp
\fB@PROT\fP: protects archives against archive deletion or pruning.
.sp
-Pre\-existing special tags can not be removed via \fB\-\-set\fP\&. You can still use
-\fB\-\-set\fP, but you must give pre\-existing special tags also (so they won\(aqt be
+Pre\-existing special tags cannot be removed via \fB\-\-set\fP\&. You can still use
+\fB\-\-set\fP, but you must also give pre\-existing special tags (so they won\(aqt be
removed).
.SH OPTIONS
.sp
@@ -75,28 +75,28 @@ remove tags (can be given multiple times)
.INDENT 0.0
.TP
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
-only consider archives matching all patterns. see \(dqborg help match\-archives\(dq.
+only consider archives matching all patterns. See \(dqborg help match\-archives\(dq.
.TP
.BI \-\-sort\-by \ KEYS
Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
.TP
.BI \-\-first \ N
-consider first N archives after other filters were applied
+consider the first N archives after other filters are applied
.TP
.BI \-\-last \ N
-consider last N archives after other filters were applied
+consider the last N archives after other filters are applied
.TP
.BI \-\-oldest \ TIMESPAN
-consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
+consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newest \ TIMESPAN
-consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m.
+consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-older \ TIMESPAN
-consider archives older than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newer \ TIMESPAN
-consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.UNINDENT
.SH SEE ALSO
.sp
diff --git a/docs/man/borg-transfer.1 b/docs/man/borg-transfer.1
index d9cbf74306..f50f0f0f52 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" "2025-08-02" "" "borg backup tool"
+.TH "BORG-TRANSFER" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
borg-transfer \- archives transfer from other repository, optionally upgrade data format
.SH SYNOPSIS
@@ -125,45 +125,45 @@ rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH
.INDENT 0.0
.TP
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
-only consider archives matching all patterns. see \(dqborg help match\-archives\(dq.
+only consider archives matching all patterns. See \(dqborg help match\-archives\(dq.
.TP
.BI \-\-sort\-by \ KEYS
Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
.TP
.BI \-\-first \ N
-consider first N archives after other filters were applied
+consider the first N archives after other filters are applied
.TP
.BI \-\-last \ N
-consider last N archives after other filters were applied
+consider the last N archives after other filters are applied
.TP
.BI \-\-oldest \ TIMESPAN
-consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
+consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newest \ TIMESPAN
-consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m.
+consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-older \ TIMESPAN
-consider archives older than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newer \ TIMESPAN
-consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.EX
-# 0. Have borg 2.0 installed on client AND server, have a b12 repo copy for testing.
+# 0. Have Borg 2.0 installed on the client AND server; have a b12 repository copy for testing.
# 1. Create a new \(dqrelated\(dq repository:
-# here, the existing borg 1.2 repo used repokey\-blake2 (and aes\-ctr mode),
-# thus we use repokey\-blake2\-aes\-ocb for the new borg 2.0 repo.
-# staying with the same chunk id algorithm (blake2) and with the same
+# Here, the existing Borg 1.2 repository used repokey\-blake2 (and AES\-CTR mode),
+# thus we use repokey\-blake2\-aes\-ocb for the new Borg 2.0 repository.
+# Staying with the same chunk ID algorithm (BLAKE2) and with the same
# key material (via \-\-other\-repo ) will make deduplication work
# between old archives (copied with borg transfer) and future ones.
-# the AEAD cipher does not matter (everything must be re\-encrypted and
-# re\-authenticated anyway), you could also choose repokey\-blake2\-chacha20\-poly1305.
-# in case your old borg repo did not use blake2, just remove the \(dq\-blake2\(dq.
+# The AEAD cipher does not matter (everything must be re\-encrypted and
+# re\-authenticated anyway); you could also choose repokey\-blake2\-chacha20\-poly1305.
+# In case your old Borg repository did not use BLAKE2, just remove the \(dq\-blake2\(dq.
$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 repo\-create \e
\-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-e repokey\-blake2\-aes\-ocb
@@ -171,11 +171,11 @@ $ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 repo\-create \e
$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=From12To20 \e
\-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-\-dry\-run
-# 3. Transfer (copy) archives from old repo into new repo (takes time and space!):
+# 3. Transfer (copy) archives from the old repository into the new repository (takes time and space!):
$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=From12To20 \e
\-\-other\-repo ssh://borg2@borgbackup/./tests/b12
-# 4. Check if we have everything (same as 2.):
+# 4. Check whether we have everything (same as step 2):
$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=From12To20 \e
\-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-\-dry\-run
.EE
diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1
index c954818976..df0eab8d29 100644
--- a/docs/man/borg-umount.1
+++ b/docs/man/borg-umount.1
@@ -27,15 +27,15 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-UMOUNT" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-umount \- un-mount the FUSE filesystem
+borg-umount \- Unmounts the FUSE filesystem.
.SH SYNOPSIS
.sp
borg [common options] umount [options] MOUNTPOINT
.SH DESCRIPTION
.sp
-This command un\-mounts a FUSE filesystem that was mounted with \fBborg mount\fP\&.
+This command unmounts a FUSE filesystem that was mounted with \fBborg mount\fP\&.
.sp
This is a convenience wrapper that just calls the platform\-specific shell
command \- usually this is either umount or fusermount \-u.
@@ -46,7 +46,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.INDENT 0.0
.TP
.B MOUNTPOINT
-mountpoint of the filesystem to umount
+mountpoint of the filesystem to unmount
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
@@ -90,7 +90,7 @@ $ borg mount \-\-exclude \(aq...\(aq /tmp/mymountpoint
$ echo \(aq/mnt/backup /tmp/myrepo fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab
$ mount /tmp/myrepo
$ ls /tmp/myrepo
-root\-2016\-02\-01 root\-2016\-02\-2015
+root\-2016\-02\-01 root\-2016\-02\-15
.EE
.UNINDENT
.UNINDENT
diff --git a/docs/man/borg-undelete.1 b/docs/man/borg-undelete.1
index 921886eb92..29bed74ed6 100644
--- a/docs/man/borg-undelete.1
+++ b/docs/man/borg-undelete.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-UNDELETE" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-undelete \- Undelete archives
+borg-undelete \- Undeletes archives.
.SH SYNOPSIS
.sp
borg [common options] undelete [options] [NAME]
@@ -39,14 +39,15 @@ This command undeletes archives in the repository.
.sp
Important: Undeleting archives is only possible before compacting.
Once \fBborg compact\fP has run, all disk space occupied only by the
-soft\-deleted archives will be freed and undelete is not possible
-anymore.
+soft\-deleted archives will be freed, and undeleting is no longer
+possible.
.sp
-When in doubt, use \fB\-\-dry\-run \-\-list\fP to see what would be undeleted.
+When in doubt, use \fB\-\-dry\-run \-\-list\fP to see what would be
+undeleted.
.sp
-You can undelete multiple archives by specifying a matching pattern,
-using the \fB\-\-match\-archives PATTERN\fP option (for more info on these patterns,
-see \fIborg_patterns\fP).
+You can undelete multiple archives by specifying a match pattern using
+the \fB\-\-match\-archives PATTERN\fP option (for more information on these
+patterns, see \fIborg_patterns\fP).
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -60,37 +61,37 @@ specify the archive name
.INDENT 0.0
.TP
.B \-n\fP,\fB \-\-dry\-run
-do not change repository
+do not change the repository
.TP
.B \-\-list
-output verbose list of archives
+output a verbose list of archives
.UNINDENT
.SS Archive filters
.INDENT 0.0
.TP
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
-only consider archives matching all patterns. see \(dqborg help match\-archives\(dq.
+only consider archives matching all patterns. See \(dqborg help match\-archives\(dq.
.TP
.BI \-\-sort\-by \ KEYS
Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
.TP
.BI \-\-first \ N
-consider first N archives after other filters were applied
+consider the first N archives after other filters are applied
.TP
.BI \-\-last \ N
-consider last N archives after other filters were applied
+consider the last N archives after other filters are applied
.TP
.BI \-\-oldest \ TIMESPAN
-consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
+consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newest \ TIMESPAN
-consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m.
+consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-older \ TIMESPAN
-consider archives older than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newer \ TIMESPAN
-consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.UNINDENT
.SH SEE ALSO
.sp
diff --git a/docs/man/borg-version.1 b/docs/man/borg-version.1
index 6c56b92211..78569db9be 100644
--- a/docs/man/borg-version.1
+++ b/docs/man/borg-version.1
@@ -27,20 +27,20 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-VERSION" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-version \- Display the borg client / borg server version
+borg-version \- Displays the Borg client and server versions.
.SH SYNOPSIS
.sp
borg [common options] version [options]
.SH DESCRIPTION
.sp
-This command displays the borg client version / borg server version.
+This command displays the Borg client and server versions.
.sp
-If a local repo is given, the client code directly accesses the repository,
-thus we show the client version also as the server version.
+If a local repository is given, the client code directly accesses the repository,
+so the client version is also shown as the server version.
.sp
-If a remote repo is given (e.g. ssh:), the remote borg is queried and
+If a remote repository is given (e.g., ssh:), the remote Borg is queried, and
its version is displayed as the server version.
.sp
Examples:
@@ -48,21 +48,21 @@ Examples:
.INDENT 3.5
.sp
.EX
-# local repo (client uses 1.4.0 alpha version)
+# local repository (client uses 1.4.0 alpha version)
$ borg version /mnt/backup
1.4.0a / 1.4.0a
-# remote repo (client uses 1.4.0 alpha, server uses 1.2.7 release)
+# remote repository (client uses 1.4.0 alpha, server uses 1.2.7 release)
$ borg version ssh://borg@borgbackup:repo
1.4.0a / 1.2.7
.EE
.UNINDENT
.UNINDENT
.sp
-Due to the version tuple format used in borg client/server negotiation, only
+Due to the version tuple format used in Borg client/server negotiation, only
a simplified version is displayed (as provided by borg.version.format_version).
.sp
-There is also borg \-\-version to display a potentially more precise client version.
+You can also use \fBborg \-\-version\fP to display a potentially more precise client version.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1
index 3c1a6e9719..408da7c32a 100644
--- a/docs/man/borg-with-lock.1
+++ b/docs/man/borg-with-lock.1
@@ -27,9 +27,9 @@ 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-08-02" "" "borg backup tool"
+.TH "BORG-WITH-LOCK" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borg-with-lock \- run a user specified command with the repository lock held
+borg-with-lock \- Runs a user-specified command with the repository lock held.
.SH SYNOPSIS
.sp
borg [common options] with\-lock [options] COMMAND [ARGS...]
@@ -45,17 +45,17 @@ $ BORG_REPO=/mnt/borgrepo borg with\-lock rsync \-av /mnt/borgrepo /somewhere/el
.UNINDENT
.UNINDENT
.sp
-It will first try to acquire the lock (make sure that no other operation is
-running in the repo), then execute the given command as a subprocess and wait
-for its termination, release the lock and return the user command\(aqs return
-code as borg\(aqs return code.
+It first tries to acquire the lock (make sure that no other operation is
+running in the repository), then executes the given command as a subprocess and waits
+for its termination, releases the lock, and returns the user command\(aqs return
+code as Borg\(aqs return code.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you copy a repository with the lock held, the lock will be present in
-the copy. Thus, before using borg on the copy from a different host,
-you need to use \(dqborg break\-lock\(dq on the copied repository, because
+the copy. Before using Borg on the copy from a different host,
+you need to run \fBborg break\-lock\fP on the copied repository, because
Borg is cautious and does not automatically remove stale locks made by a different host.
.UNINDENT
.UNINDENT
diff --git a/docs/man/borg.1 b/docs/man/borg.1
index 8ece15b78b..2c0d418240 100644
--- a/docs/man/borg.1
+++ b/docs/man/borg.1
@@ -28,7 +28,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" "2025-08-02" "" "borg backup tool"
+.TH "BORG" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
borg \- deduplicating and encrypting backup tool
.SH SYNOPSIS
@@ -41,7 +41,7 @@ borg [common options] [options] [arguments]
BorgBackup (short: Borg) is a deduplicating backup program.
Optionally, it supports compression and authenticated encryption.
.sp
-The main goal of Borg is to provide an efficient and secure way to back data up.
+The main goal of Borg is to provide an efficient and secure way to back up data.
The data deduplication technique used makes Borg suitable for daily backups
since only changes are stored.
The authenticated encryption technique makes it suitable for backups to targets not
@@ -50,7 +50,7 @@ fully trusted.
Borg stores a set of files in an \fIarchive\fP\&. A \fIrepository\fP is a collection
of \fIarchives\fP\&. The format of repositories is Borg\-specific. Borg does not
distinguish archives from each other in any way other than their name,
-it does not matter when or where archives were created (e.g. different hosts).
+it does not matter when or where archives were created (e.g., different hosts).
.SH EXAMPLES
.SS A step\-by\-step example
.INDENT 0.0
@@ -76,7 +76,7 @@ $ borg \-r /path/to/repo create docs ~/src ~/Documents
.UNINDENT
.UNINDENT
.IP 3. 3
-The next day create a new archive using the same archive name:
+The next day, create a new archive using the same archive name:
.INDENT 3.0
.INDENT 3.5
.sp
@@ -86,8 +86,8 @@ $ borg \-r /path/to/repo create \-\-stats docs ~/src ~/Documents
.UNINDENT
.UNINDENT
.sp
-This backup will be a lot quicker and a lot smaller since only new, never
-before seen data is stored. The \fB\-\-stats\fP option causes Borg to
+This backup will be much quicker and much smaller, since only new,
+never\-before\-seen data is stored. The \fB\-\-stats\fP option causes Borg to
output statistics about the newly created archive such as the deduplicated
size (the amount of unique data not shared with other archives):
.INDENT 3.0
@@ -100,7 +100,7 @@ Archive fingerprint: bcd1b53f9b4991b7afc2b339f851b7ffe3c6d030688936fe4552eccc187
Time (start): Sat, 2022\-06\-25 20:21:43
Time (end): Sat, 2022\-06\-25 20:21:43
Duration: 0.07 seconds
-Utilization of max. archive size: 0%
+Utilization of maximum archive size: 0%
Number of files: 699
Original size: 31.14 MB
Deduplicated size: 502 B
@@ -143,7 +143,7 @@ $ borg \-r /path/to/repo extract aid:b80e24d2
.UNINDENT
.UNINDENT
.IP 7. 3
-Delete the first archive (please note that this does \fBnot\fP free repo disk space):
+Delete the first archive (please note that this does \fBnot\fP free repository disk space):
.INDENT 3.0
.INDENT 3.5
.sp
@@ -153,10 +153,10 @@ $ borg \-r /path/to/repo delete aid:b80e24d2
.UNINDENT
.UNINDENT
.sp
-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!
+Be careful if you use an archive NAME (and not an archive ID), as it might match multiple archives.
+Always use \fB\-\-dry\-run\fP and \fB\-\-list\fP first!
.IP 8. 3
-Recover disk space by compacting the segment files in the repo:
+Recover disk space by compacting the segment files in the repository:
.INDENT 3.0
.INDENT 3.5
.sp
@@ -181,7 +181,7 @@ get other informational messages.
.SS Positional Arguments and Options: Order matters
.sp
Borg only supports taking options (\fB\-s\fP and \fB\-\-progress\fP in the example)
-to the left or right of all positional arguments (\fBrepo::archive\fP and \fBpath\fP
+either to the left or to the right of all positional arguments (\fBrepo::archive\fP and \fBpath\fP
in the example), but not in between them:
.INDENT 0.0
.INDENT 3.5
@@ -200,43 +200,43 @@ This is due to a problem in the argparse module: :
+\fBRemote repositories\fP accessed via SSH :
.sp
-\fBssh://user@host:port//abs/path/to/repo\fP \- absolute path
+\fBssh://user@host:port//abs/path/to/repo\fP — absolute path
.sp
-\fBssh://user@host:port/rel/path/to/repo\fP \- path relative to current directory
+\fBssh://user@host:port/rel/path/to/repo\fP — path relative to the current directory
.sp
-\fBRemote repositories\fP accessed via sftp:
+\fBRemote repositories\fP accessed via SFTP:
.sp
-\fBsftp://user@host:port//abs/path/to/repo\fP \- absolute path
+\fBsftp://user@host:port//abs/path/to/repo\fP — absolute path
.sp
-\fBsftp://user@host:port/rel/path/to/repo\fP \- path relative to current directory
+\fBsftp://user@host:port/rel/path/to/repo\fP — path relative to the current directory
.sp
-For ssh and sftp URLs, the \fBuser@\fP and \fB:port\fP parts are optional.
+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 \- see the rclone docs for more details about remote:path.
+\fBrclone:remote:path\fP — see the rclone docs for more details about \fBremote:path\fP\&.
.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 the credentials.
+\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.
.sp
-If you\(aqre connecting to AWS S3, \fB[schema://hostname[:port]]\fP is optional, but \fBbucket\fP and \fBpath\fP are always required.
+If you are connecting to AWS S3, \fB[schema://hostname[:port]]\fP is optional, but \fBbucket\fP and \fBpath\fP are always required.
.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.
+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
-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:
+If you frequently need the same repository URL, it is a good idea to set the
+\fBBORG_REPO\fP environment variable to set a default repository URL:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -246,27 +246,26 @@ export BORG_REPO=\(aqssh://user@host:port/rel/path/to/repo\(aq
.UNINDENT
.UNINDENT
.sp
-Then just leave away the \fB\-\-repo\fP option if you want
-to use the default \- it will be read from BORG_REPO then.
-.SS Repository Locations / Archive names
+Then simply omit the \fB\-\-repo\fP option when you want
+to use the default — it will be read from BORG_REPO.
+.SS Repository Locations / Archive Names
.sp
-Many commands need to know the repository location, give it via \fB\-r\fP / \fB\-\-repo\fP
+Many commands need to know the repository location; specify it via \fB\-r\fP/\fB\-\-repo\fP
or use the \fBBORG_REPO\fP environment variable.
.sp
-Commands needing one or two archive names usually get them as positional argument.
+Commands that need one or two archive names usually take them as positional arguments.
.sp
-Commands working with an arbitrary amount of archives, usually take \fB\-a ARCH_GLOB\fP\&.
+Commands that work with an arbitrary number of archives usually accept \fB\-a ARCH_GLOB\fP\&.
.sp
Archive names must not contain the \fB/\fP (slash) character. For simplicity,
-maybe also avoid blanks or other characters that have special meaning on the
-shell or in a filesystem (borg mount will use the archive name as directory
+also avoid spaces or other characters that have special meaning to the
+shell or in a filesystem (\fBborg mount\fP uses the archive name as a directory
name).
.SS Logging
.sp
-Borg writes all log output to stderr by default. But please note that something
-showing up on stderr does \fInot\fP indicate an error condition just because it is
-on stderr. Please check the log levels of the messages and the return code of
-borg for determining error, warning or success conditions.
+Borg writes all log output to stderr by default. However, output on stderr does
+not necessarily indicate an error. Check the log levels of the messages and the
+return code of borg to determine error, warning, or success conditions.
.sp
If you want to capture the log output to a file, just redirect it:
.INDENT 0.0
@@ -280,30 +279,30 @@ borg create \-\-repo repo archive myfiles 2>> logfile
.sp
Custom logging configurations can be implemented via BORG_LOGGING_CONF.
.sp
-The log level of the builtin logging configuration defaults to WARNING.
+The log level of the built\-in logging configuration defaults to WARNING.
This is because we want Borg to be mostly silent and only output
-warnings, errors and critical messages, unless output has been requested
-by supplying an option that implies output (e.g. \fB\-\-list\fP or \fB\-\-progress\fP).
+warnings, errors, and critical messages unless output has been requested
+by supplying an option that implies output (e.g., \fB\-\-list\fP or \fB\-\-progress\fP).
.sp
Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
.sp
-Use \fB\-\-debug\fP to set DEBUG log level \-
-to get debug, info, warning, error and critical level output.
+Use \fB\-\-debug\fP to set the DEBUG log level —
+this prints debug, info, warning, error, and critical messages.
.sp
-Use \fB\-\-info\fP (or \fB\-v\fP or \fB\-\-verbose\fP) to set INFO log level \-
-to get info, warning, error and critical level output.
+Use \fB\-\-info\fP (or \fB\-v\fP or \fB\-\-verbose\fP) to set the INFO log level —
+this prints info, warning, error, and critical messages.
.sp
-Use \fB\-\-warning\fP (default) to set WARNING log level \-
-to get warning, error and critical level output.
+Use \fB\-\-warning\fP (default) to set the WARNING log level —
+this prints warning, error, and critical messages.
.sp
-Use \fB\-\-error\fP to set ERROR log level \-
-to get error and critical level output.
+Use \fB\-\-error\fP to set the ERROR log level —
+this prints error and critical messages.
.sp
-Use \fB\-\-critical\fP to set CRITICAL log level \-
-to get critical level output.
+Use \fB\-\-critical\fP to set the CRITICAL log level —
+this prints only critical messages.
.sp
-While you can set misc. log levels, do not expect that every command will
-give different output on different log levels \- it\(aqs just a possibility.
+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
.INDENT 0.0
@@ -333,15 +332,15 @@ _
T{
1
T} T{
-generic warning (operation reached its normal end, but there were warnings \-\-
-you should check the log, logged as WARNING)
+generic warning (operation reached its normal end, but there were warnings —
+you should check the log; logged as WARNING)
T}
_
T{
2
T} T{
-generic error (like a fatal error, a local or remote exception, the operation
-did not reach its normal end, logged as ERROR)
+generic error (like a fatal error or a local/remote exception; the operation
+did not reach its normal end; logged as ERROR)
T}
_
T{
@@ -366,7 +365,7 @@ T}
If you use \fB\-\-show\-rc\fP, the return code is also logged at the indicated
level as the last log entry.
.sp
-The modern exit codes (return codes, \(dqrc\(dq) are documented there: \fImsgid\fP
+The modern exit codes (return codes, \(dqrc\(dq) are documented here: see \fImsgid\fP\&.
.SS Environment Variables
.sp
Borg uses some environment variables for automation:
@@ -409,7 +408,7 @@ If BORG_PASSPHRASE or BORG_PASSCOMMAND are also set, they take precedence.
When set, use the value to answer the passphrase question when a \fBnew\fP passphrase is asked for.
This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also
be checked.
-Main usecase for this is to automate fully \fBborg change\-passphrase\fP\&.
+Main use case for this is to fully automate \fBborg change\-passphrase\fP\&.
.TP
.B BORG_DISPLAY_PASSPHRASE
When set, use the value to answer the \(dqdisplay the passphrase for verification\(dq question when defining a new passphrase for encrypted repositories.
@@ -426,13 +425,13 @@ Default is \(dqmodern\(dq.
Borg usually computes a host id from the FQDN plus the results of \fBuuid.getnode()\fP (which usually returns
a unique id based on the MAC address of the network interface. Except if that MAC happens to be all\-zero \- in
that case it returns a random value, which is not what we want (because it kills automatic stale lock removal).
-So, if you have a all\-zero MAC address or other reasons to control better externally the host id, just set this
+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 commandline option.
+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
@@ -442,11 +441,11 @@ A basic example conf can be found at \fBdocs/misc/logging.conf\fP\&.
.B BORG_RSH
When set, use this command instead of \fBssh\fP\&. This can be used to specify ssh options, such as
a custom identity file \fBssh \-i /path/to/private/key\fP\&. See \fBman ssh\fP for other options. Using
-the \fB\-\-rsh CMD\fP commandline option overrides the environment variable.
+the \fB\-\-rsh CMD\fP command line option overrides the environment variable.
.TP
.B BORG_REMOTE_PATH
When set, use the given path as borg executable on the remote (defaults to \(dqborg\(dq if unset).
-Using \fB\-\-remote\-path PATH\fP commandline option overrides the environment variable.
+Using the \fB\-\-remote\-path PATH\fP command line option overrides the environment variable.
.TP
.B BORG_REPO_PERMISSIONS
Set repository permissions, see also: \fIborg_serve\fP
@@ -469,16 +468,24 @@ When set to no (default: yes), system information (like OS, Python version, ...)
exceptions is not shown.
Please only use for good reasons as it makes issues harder to analyze.
.TP
+.B BORG_MSGPACK_VERSION_CHECK
+Controls whether Borg checks the \fBmsgpack\fP version.
+The default is \fByes\fP (strict check). Set to \fBno\fP to disable the version check and
+allow any installed \fBmsgpack\fP version. Use this at your own risk; malfunctioning or
+incompatible \fBmsgpack\fP versions may cause subtle bugs or repository data corruption.
+.TP
.B BORG_FUSE_IMPL
-Choose the lowlevel FUSE implementation borg shall use for \fBborg mount\fP\&.
+Choose the low\-level FUSE implementation borg shall use for \fBborg mount\fP\&.
This is a comma\-separated list of implementation names, they are tried in the
given order, e.g.:
.INDENT 7.0
.IP \(bu 2
-\fBpyfuse3,llfuse\fP: default, first try to load pyfuse3, then try to load llfuse.
+\fBmfusepy,pyfuse3,llfuse\fP: default, first try to load mfusepy, then pyfuse3, then llfuse.
.IP \(bu 2
\fBllfuse,pyfuse3\fP: first try to load llfuse, then try to load pyfuse3.
.IP \(bu 2
+\fBmfusepy\fP: only try to load mfusepy
+.IP \(bu 2
\fBpyfuse3\fP: only try to load pyfuse3
.IP \(bu 2
\fBllfuse\fP: only try to load llfuse
@@ -487,16 +494,16 @@ given order, e.g.:
.UNINDENT
.TP
.B BORG_SELFTEST
-This can be used to influence borg\(aqs builtin self\-tests. The default is to execute the tests
+This can be used to influence borg\(aqs built\-in self\-tests. The default is to execute the tests
at the beginning of each borg command invocation.
.sp
BORG_SELFTEST=disabled can be used to switch off the tests and rather save some time.
Disabling is not recommended for normal borg users, but large scale borg storage providers can
use this to optimize production servers after at least doing a one\-time test borg (with
-selftests not disabled) when installing or upgrading machines / OS / borg.
+self\-tests not disabled) when installing or upgrading machines/OS/Borg.
.TP
.B BORG_WORKAROUNDS
-A list of comma separated strings that trigger workarounds in borg,
+A list of comma\-separated strings that trigger workarounds in borg,
e.g. to work around bugs in other software.
.sp
Currently known strings are:
@@ -507,7 +514,7 @@ Use the more simple BaseSyncFile code to avoid issues with sync_file_range.
You might need this to run borg on WSL (Windows Subsystem for Linux) or
in systemd.nspawn containers on some architectures (e.g. ARM).
Using this does not affect data safety, but might result in a more bursty
-write to disk behaviour (not continuously streaming to disk).
+write\-to\-disk behavior (not continuously streaming to disk).
.TP
.B retry_erofs
Retry opening a file without O_NOATIME if opening a file with O_NOATIME
@@ -684,30 +691,30 @@ mode 600, root:root).
.SS File systems
.sp
We recommend using a reliable, scalable journaling filesystem for the
-repository, e.g. zfs, btrfs, ext4, apfs.
+repository, e.g., zfs, btrfs, ext4, apfs.
.sp
Borg now uses the \fBborgstore\fP package to implement the key/value store it
uses for the repository.
.sp
-It currently uses the \fBfile:\fP Store (posixfs backend) either with a local
-directory or via ssh and a remote \fBborg serve\fP agent using borgstore on the
+It currently uses the \fBfile:\fP store (posixfs backend) either with a local
+directory or via SSH and a remote \fBborg serve\fP agent using borgstore on the
remote side.
.sp
This means that it will store each chunk into a separate filesystem file
(for more details, see the \fBborgstore\fP project).
.sp
-This has some pros and cons (compared to legacy borg 1.x\(aqs segment files):
+This has some pros and cons (compared to legacy Borg 1.x segment files):
.sp
Pros:
.INDENT 0.0
.IP \(bu 2
-Simplicity and better maintainability of the borg code.
+Simplicity and better maintainability of the Borg code.
.IP \(bu 2
-Sometimes faster, less I/O, better scalability: e.g. borg compact can just
+Sometimes faster, less I/O, better scalability: e.g., borg compact can just
remove unused chunks by deleting a single file and does not need to read
-and re\-write segment files to free space.
+and rewrite segment files to free space.
.IP \(bu 2
-In future, easier to adapt to other kinds of storage:
+In the future, easier to adapt to other kinds of storage:
borgstore\(aqs backends are quite simple to implement.
\fBsftp:\fP and \fBrclone:\fP backends already exist, others might be easy to add.
.IP \(bu 2
@@ -717,14 +724,14 @@ Parallel repository access with less locking is easier to implement.
Cons:
.INDENT 0.0
.IP \(bu 2
-The repository filesystem will have to deal with a big amount of files (there
+The repository filesystem will have to deal with a large number of files (there
are provisions in borgstore against having too many files in a single directory
by using a nested directory structure).
.IP \(bu 2
-Bigger fs space usage overhead (will depend on allocation block size \- modern
-filesystems like zfs are rather clever here using a variable block size).
+Greater filesystem space overhead (depends on the allocation block size — modern
+filesystems like zfs are rather clever here, using a variable block size).
.IP \(bu 2
-Sometimes slower, due to less sequential / more random access operations.
+Sometimes slower, due to less sequential and more random access operations.
.UNINDENT
.SS Units
.sp
@@ -738,10 +745,10 @@ indicated using the IEC binary prefixes
+For more information, see:
.sp
Unless otherwise noted, we display local date and time.
Internally, we store and process date and time as UTC.
@@ -749,44 +756,44 @@ TIMESPAN
.sp
Some options accept a TIMESPAN parameter, which can be given as a number of
years (e.g. \fB2y\fP), months (e.g. \fB12m\fP), weeks (e.g. \fB2w\fP),
-days (e.g. \fB7d\fP), hours (e.g. \fB8H\fP), minutes (e.g. \fB30M\fP),
+days (e.g. \fB7d\fP), hours (e.g. \fB8H\fP), minutes (e.g. \fB30M\fP),
or seconds (e.g. \fB150S\fP).
.SS Resource Usage
.sp
-Borg might use a lot of resources depending on the size of the data set it is dealing with.
+Borg might use significant resources depending on the size of the data set it is dealing with.
.sp
-If one uses Borg in a client/server way (with a ssh: repository),
-the resource usage occurs in part on the client and in another part on the
+If you use Borg in a client/server way (with an SSH repository),
+the resource usage occurs partly on the client and partly on the
server.
.sp
-If one uses Borg as a single process (with a filesystem repo),
-all the resource usage occurs in that one process, so just add up client +
+If you use Borg as a single process (with a filesystem repository),
+all resource usage occurs in that one process, so add up client and
server to get the approximate resource usage.
.INDENT 0.0
.TP
.B CPU client:
.INDENT 7.0
.IP \(bu 2
-\fBborg create:\fP does chunking, hashing, compression, crypto (high CPU usage)
+\fBborg create:\fP chunking, hashing, compression, encryption (high CPU usage)
.IP \(bu 2
-\fBchunks cache sync:\fP quite heavy on CPU, doing lots of hashtable operations.
+\fBchunks cache sync:\fP quite heavy on CPU, doing lots of hash table operations
.IP \(bu 2
-\fBborg extract:\fP crypto, decompression (medium to high CPU usage)
+\fBborg extract:\fP decryption, decompression (medium to high CPU usage)
.IP \(bu 2
-\fBborg check:\fP similar to extract, but depends on options given.
+\fBborg check:\fP similar to extract, but depends on options given
.IP \(bu 2
-\fBborg prune / borg delete archive:\fP low to medium CPU usage
+\fBborg prune/borg delete archive:\fP low to medium CPU usage
.IP \(bu 2
\fBborg delete repo:\fP done on the server
.UNINDENT
.sp
-It won\(aqt go beyond 100% of 1 core as the code is currently single\-threaded.
+It will not use more than 100% of one CPU core as the code is currently single\-threaded.
Especially higher zlib and lzma compression levels use significant amounts
-of CPU cycles. Crypto might be cheap on the CPU (if hardware accelerated) or
+of CPU cycles. Crypto might be cheap on the CPU (if hardware\-accelerated) or
expensive (if not).
.TP
.B CPU server:
-It usually doesn\(aqt need much CPU, it just deals with the key/value store
+It usually does not need much CPU; it just deals with the key/value store
(repository) and uses the repository index for that.
.sp
borg check: the repository check computes the checksums of all chunks
@@ -794,15 +801,15 @@ borg check: the repository check computes the checksums of all chunks
borg delete repo: low CPU usage
.TP
.B CPU (only for client/server operation):
-When using borg in a client/server way with a repo, the ssh
+When using Borg in a client/server way with an ssh\-type repository, the SSH
processes used for the transport layer will need some CPU on the client and
-on the server due to the crypto they are doing \- esp. if you are pumping
-big amounts of data.
+on the server due to the crypto they are doing — especially if you are pumping
+large amounts of data.
.TP
.B Memory (RAM) client:
The chunks index and the files index are read into memory for performance
-reasons. Might need big amounts of memory (see below).
-Compression, esp. lzma compression with high levels might need substantial
+reasons. Might need large amounts of memory (see below).
+Compression, especially lzma compression with high levels, might need substantial
amounts of memory.
.TP
.B Memory (RAM) server:
@@ -810,47 +817,47 @@ The server process will load the repository index into memory. Might need
considerable amounts of memory, but less than on the client (see below).
.TP
.B Chunks index (client only):
-Proportional to the amount of data chunks in your repo. Lots of chunks
+Proportional to the number of data chunks in your repo. Lots of chunks
in your repo imply a big chunks index.
-It is possible to tweak the chunker params (see create options).
+It is possible to tweak the chunker parameters (see create options).
.TP
.B Files index (client only):
-Proportional to the amount of files in your last backups. Can be switched
-off (see create options), but next backup might be much slower if you do.
+Proportional to the number of files in your last backups. Can be switched
+off (see create options), but the next backup might be much slower if you do.
The speed benefit of using the files cache is proportional to file size.
.TP
.B Repository index (server only):
-Proportional to the amount of data chunks in your repo. Lots of chunks
+Proportional to the number of data chunks in your repo. Lots of chunks
in your repo imply a big repository index.
-It is possible to tweak the chunker params (see create options) to
-influence the amount of chunks being created.
+It is possible to tweak the chunker parameters (see create options) to
+influence the number of chunks created.
.TP
.B Temporary files (client):
-Reading data and metadata from a FUSE mounted repository will consume up to
+Reading data and metadata from a FUSE\-mounted repository will consume up to
the size of all deduplicated, small chunks in the repository. Big chunks
-won\(aqt be locally cached.
+will not be locally cached.
.TP
.B Temporary files (server):
-A non\-trivial amount of data will be stored on the remote temp directory
+A non\-trivial amount of data will be stored in the remote temporary directory
for each client that connects to it. For some remotes, this can fill the
-default temporary directory at /tmp. This can be remediated by ensuring the
+default temporary directory in /tmp. This can be mitigated by ensuring the
$TMPDIR, $TEMP, or $TMP environment variable is properly set for the sshd
process.
-For some OSes, this can be done just by setting the correct value in the
-\&.bashrc (or equivalent login config file for other shells), however in
+For some OSes, this can be done by setting the correct value in the
+\&.bashrc (or equivalent login config file for other shells); however, in
other cases it may be necessary to first enable \fBPermitUserEnvironment yes\fP
in your \fBsshd_config\fP file, then add \fBenvironment=\(dqTMPDIR=/my/big/tmpdir\(dq\fP
-at the start of the public key to be used in the \fBauthorized_hosts\fP file.
+at the start of the public key to be used in the \fBauthorized_keys\fP file.
.TP
.B Cache files (client only):
Contains the chunks index and files index (plus a collection of single\-
-archive chunk indexes which might need huge amounts of disk space,
-depending on archive count and size \- see FAQ about how to reduce).
+archive chunk indexes), which might need huge amounts of disk space
+depending on archive count and size — see the FAQ for how to reduce this.
.TP
.B Network (only for client/server operation):
If your repository is remote, all deduplicated (and optionally compressed/
-encrypted) data of course has to go over the connection (\fBssh://\fP repo url).
-If you use a locally mounted network filesystem, additionally some copy
+encrypted) data has to go over the connection (\fBssh://\fP repository URL).
+If you use a locally mounted network filesystem, some additional copy
operations used for transaction support also go over the connection. If
you back up multiple sources to one target repository, additional traffic
happens for cache resynchronization.
@@ -860,22 +867,22 @@ happens for cache resynchronization.
Besides regular file and directory structures, Borg can preserve
.INDENT 0.0
.IP \(bu 2
-symlinks (stored as symlink, the symlink is not followed)
+symlinks (stored as a symlink; the symlink is not followed)
.IP \(bu 2
special files:
.INDENT 2.0
.IP \(bu 2
-character and block device files (restored via mknod)
+character and block device files (restored via mknod(2))
.IP \(bu 2
FIFOs (\(dqnamed pipes\(dq)
.IP \(bu 2
special file \fIcontents\fP can be backed up in \fB\-\-read\-special\fP mode.
-By default the metadata to create them with mknod(2), mkfifo(2) etc. is stored.
+By default, the metadata to create them with mknod(2), mkfifo(2), etc. is stored.
.UNINDENT
.IP \(bu 2
-hardlinked regular files, devices, symlinks, FIFOs (considering all items in the same archive)
+hard\-linked regular files, devices, symlinks, FIFOs (considering all items in the same archive)
.IP \(bu 2
-timestamps in nanosecond precision: mtime, atime, ctime
+timestamps with nanosecond precision: mtime, atime, ctime
.IP \(bu 2
other timestamps: birthtime (on platforms supporting it)
.IP \(bu 2
@@ -980,10 +987,10 @@ No
T}
.TE
.sp
-Other Unix\-like operating systems may work as well, but have not been tested at all.
+Other Unix\-like operating systems may work as well, but have not been tested yet.
.sp
-Note that most of the platform\-dependent features also depend on the file system.
-For example, ntfs\-3g on Linux isn\(aqt able to convey NTFS ACLs.
+Note that most platform\-dependent features also depend on the filesystem.
+For example, ntfs\-3g on Linux is not able to convey NTFS ACLs.
.IP [1] 5
Only \(dqnodump\(dq, \(dqimmutable\(dq, \(dqcompressed\(dq and \(dqappend\(dq are supported.
Feature request #618 for more flags.
@@ -995,12 +1002,12 @@ Feature request #1337
Cygwin tries to map NTFS ACLs to permissions with varying degrees of success.
.IP [5] 5
The native access control list mechanism of the OS. This normally limits access to
-non\-native ACLs. For example, NTFS ACLs aren\(aqt completely accessible on Linux with ntfs\-3g.
+non\-native ACLs. For example, NTFS ACLs are not completely accessible on Linux with ntfs\-3g.
.IP [6] 5
-extended attributes; key\-value pairs attached to a file, mainly used by the OS.
-This includes resource forks on Mac OS X.
+Extended attributes; key\-value pairs attached to a file, mainly used by the OS.
+This includes resource forks on macOS.
.IP [7] 5
-aka \fIBSD flags\fP\&. The Linux set of flags [1] is portable across platforms.
+Also known as \fIBSD flags\fP\&. The Linux set of flags [1] is portable across platforms.
The BSDs define additional flags.
.SH SEE ALSO
.sp
diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1
index b536d972eb..0f94c1fab3 100644
--- a/docs/man/borgfs.1
+++ b/docs/man/borgfs.1
@@ -27,9 +27,9 @@ 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" "2025-08-02" "" "borg backup tool"
+.TH "BORGFS" "1" "2025-12-23" "" "borg backup tool"
.SH NAME
-borgfs \- Mount archive or an entire repository as a FUSE filesystem
+borgfs \- Mounts an archive or an entire repository as a FUSE filesystem.
.SH SYNOPSIS
.sp
borgfs [options] MOUNTPOINT [PATH...]
@@ -43,7 +43,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.INDENT 0.0
.TP
.B MOUNTPOINT
-where to mount filesystem
+where to mount the filesystem
.TP
.B PATH
paths to extract; patterns are supported
@@ -54,41 +54,44 @@ paths to extract; patterns are supported
.B \-V\fP,\fB \-\-version
show version number and exit
.TP
+.B \-\-cockpit
+Start the Borg TUI
+.TP
.B \-f\fP,\fB \-\-foreground
stay in foreground, do not daemonize
.TP
.B \-o
-Extra mount options
+extra mount options
.TP
.B \-\-numeric\-ids
-use numeric user and group identifiers from archive(s)
+use numeric user and group identifiers from archives
.UNINDENT
.SS Archive filters
.INDENT 0.0
.TP
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
-only consider archives matching all patterns. see \(dqborg help match\-archives\(dq.
+only consider archives matching all patterns. See \(dqborg help match\-archives\(dq.
.TP
.BI \-\-sort\-by \ KEYS
Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
.TP
.BI \-\-first \ N
-consider first N archives after other filters were applied
+consider the first N archives after other filters are applied
.TP
.BI \-\-last \ N
-consider last N archives after other filters were applied
+consider the last N archives after other filters are applied
.TP
.BI \-\-oldest \ TIMESPAN
-consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
+consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newest \ TIMESPAN
-consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m.
+consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-older \ TIMESPAN
-consider archives older than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newer \ TIMESPAN
-consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
+consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.UNINDENT
.SS Include/Exclude options
.INDENT 0.0
diff --git a/docs/usage/analyze.rst.inc b/docs/usage/analyze.rst.inc
index f8c9474387..7b548dcc1c 100644
--- a/docs/usage/analyze.rst.inc
+++ b/docs/usage/analyze.rst.inc
@@ -19,21 +19,21 @@ borg analyze
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. see "borg help match-archives". |
+ | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--first N`` | consider first N archives after other filters were applied |
+ | | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--last N`` | consider last N archives after other filters were applied |
+ | | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+ | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+ | | ``--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. |
+ | | ``--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. |
+ | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -52,14 +52,14 @@ borg analyze
|
Archive filters
- -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. see "borg help match-archives".
+ -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. See "borg help match-archives".
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
- --first N consider first N archives after other filters were applied
- --last N consider last N archives after other filters were applied
- --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
- --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.
+ --first N consider the first N archives after other filters are applied
+ --last N consider the last N archives after other filters are applied
+ --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
+ --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.
Description
@@ -67,18 +67,18 @@ Description
Analyze archives to find "hot spots".
-Borg analyze relies on the usual archive matching options to select the
+``borg analyze`` relies on the usual archive matching options to select the
archives that should be considered for analysis (e.g. ``-a series_name``).
-Then it iterates over all matching archives, over all contained files and
-collects information about chunks stored in all directories it encountered.
+Then it iterates over all matching archives, over all contained files, and
+collects information about chunks stored in all directories it encounters.
-It considers chunk IDs and their plaintext sizes (we don't have the compressed
-size in the repository easily available) and adds up added/removed chunks'
-sizes per direct parent directory and outputs a list of "directory: size".
+It considers chunk IDs and their plaintext sizes (we do not have the compressed
+size in the repository easily available) and adds up the sizes of added and removed
+chunks per direct parent directory, and outputs a list of "directory: size".
-You can use that list to find directories with a lot of "activity" - maybe
-some of these are temporary or cache directories you did forget to exclude.
+You can use that list to find directories with a lot of "activity" — maybe
+some of these are temporary or cache directories you forgot to exclude.
-To not have these unwanted directories in your backups, you could carefully
-exclude these in ``borg create`` (for future backups) or use ``borg recreate``
-to re-create existing archives without these.
\ No newline at end of file
+To avoid including these unwanted directories in your backups, you can carefully
+exclude them in ``borg create`` (for future backups) or use ``borg recreate``
+to recreate existing archives without them.
\ No newline at end of file
diff --git a/docs/usage/benchmark_cpu.rst.inc b/docs/usage/benchmark_cpu.rst.inc
index c52705cb0c..6e9ee93ac9 100644
--- a/docs/usage/benchmark_cpu.rst.inc
+++ b/docs/usage/benchmark_cpu.rst.inc
@@ -36,7 +36,7 @@ borg benchmark cpu
Description
~~~~~~~~~~~
-This command benchmarks misc. CPU bound borg operations.
+This command benchmarks miscellaneous CPU-bound Borg operations.
It creates input data in memory, runs the operation and then displays throughput.
To reduce outside influence on the timings, please make sure to run this with:
diff --git a/docs/usage/benchmark_crud.rst.inc b/docs/usage/benchmark_crud.rst.inc
index d8e41aba59..bddcd2e13a 100644
--- a/docs/usage/benchmark_crud.rst.inc
+++ b/docs/usage/benchmark_crud.rst.inc
@@ -12,15 +12,15 @@ borg benchmark crud
.. class:: borg-options-table
- +-------------------------------------------------------+----------+------------------------------------------+
- | **positional arguments** |
- +-------------------------------------------------------+----------+------------------------------------------+
- | | ``PATH`` | path were to create benchmark input data |
- +-------------------------------------------------------+----------+------------------------------------------+
- | .. class:: borg-common-opt-ref |
- | |
- | :ref:`common_options` |
- +-------------------------------------------------------+----------+------------------------------------------+
+ +-------------------------------------------------------+----------+-------------------------------------------+
+ | **positional arguments** |
+ +-------------------------------------------------------+----------+-------------------------------------------+
+ | | ``PATH`` | path where to create benchmark input data |
+ +-------------------------------------------------------+----------+-------------------------------------------+
+ | .. class:: borg-common-opt-ref |
+ | |
+ | :ref:`common_options` |
+ +-------------------------------------------------------+----------+-------------------------------------------+
.. raw:: html
@@ -33,7 +33,7 @@ borg benchmark crud
.. only:: latex
PATH
- path were to create benchmark input data
+ path where to create benchmark input data
:ref:`common_options`
@@ -44,11 +44,11 @@ Description
This command benchmarks borg CRUD (create, read, update, delete) operations.
-It creates input data below the given PATH and backups this data into the given REPO.
+It creates input data below the given PATH and backs up this data into the given REPO.
The REPO must already exist (it could be a fresh empty repo or an existing repo, the
command will create / read / update / delete some archives named borg-benchmark-crud\* there.
-Make sure you have free space there, you'll need about 1GB each (+ overhead).
+Make sure you have free space there; you will need about 1 GB each (+ overhead).
If your repository is encrypted and borg needs a passphrase to unlock the key, use::
diff --git a/docs/usage/break-lock.rst.inc b/docs/usage/break-lock.rst.inc
index bdc47c5390..e8fbad88b1 100644
--- a/docs/usage/break-lock.rst.inc
+++ b/docs/usage/break-lock.rst.inc
@@ -37,5 +37,5 @@ Description
~~~~~~~~~~~
This command breaks the repository and cache locks.
-Please use carefully and only while no borg process (on any machine) is
-trying to access the Cache or the Repository.
\ No newline at end of file
+Use with care and only when no Borg process (on any machine) is
+trying to access the cache or the repository.
\ No newline at end of file
diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc
index 9b50786ece..a1c56f94f8 100644
--- a/docs/usage/check.rst.inc
+++ b/docs/usage/check.rst.inc
@@ -17,7 +17,7 @@ borg check
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--repository-only`` | only perform repository checks |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--archives-only`` | only perform archives checks |
+ | | ``--archives-only`` | only perform archive checks |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--verify-data`` | perform cryptographic archive data integrity verification (conflicts with ``--repository-only``) |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
@@ -25,7 +25,7 @@ borg check
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--find-lost-archives`` | attempt to find lost archives |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--max-duration SECONDS`` | do only a partial repo check for max. SECONDS seconds (Default: unlimited) |
+ | | ``--max-duration SECONDS`` | perform only a partial repository check for at most SECONDS seconds (default: unlimited) |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
@@ -33,21 +33,21 @@ borg check
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. see "borg help match-archives". |
+ | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--first N`` | consider first N archives after other filters were applied |
+ | | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--last N`` | consider last N archives after other filters were applied |
+ | | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+ | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+ | | ``--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. |
+ | | ``--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. |
+ | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -64,25 +64,25 @@ borg check
options
--repository-only only perform repository checks
- --archives-only only perform archives checks
+ --archives-only only perform archive checks
--verify-data perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)
--repair attempt to repair any inconsistencies found
--find-lost-archives attempt to find lost archives
- --max-duration SECONDS do only a partial repo check for max. SECONDS seconds (Default: unlimited)
+ --max-duration SECONDS perform only a partial repository check for at most SECONDS seconds (default: unlimited)
:ref:`common_options`
|
Archive filters
- -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. see "borg help match-archives".
+ -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. See "borg help match-archives".
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
- --first N consider first N archives after other filters were applied
- --last N consider last N archives after other filters were applied
- --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
- --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.
+ --first N consider the first N archives after other filters are applied
+ --last N consider the last N archives after other filters are applied
+ --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
+ --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.
Description
@@ -96,7 +96,7 @@ It consists of two major steps:
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 ``--max-duration``.
- When checking a ssh:// remote repository, please note that the checks run on
+ When checking an ssh:// remote repository, please note that the checks run on
the server and do not cause significant network traffic.
2. Checking consistency and correctness of the archive metadata and optionally
@@ -105,9 +105,9 @@ It consists of two major steps:
all chunks referencing files (items) in the archive exist. This requires
reading archive and file metadata, but not data. To scan for archives whose
entries were lost from the archive directory, pass ``--find-lost-archives``.
- It requires reading all data and is hence very time consuming.
+ It requires reading all data and is hence very time-consuming.
To additionally cryptographically verify the file (content) data integrity,
- pass ``--verify-data``, which is even more time consuming.
+ pass ``--verify-data``, which is even more time-consuming.
When checking archives of a remote repository, archive checks run on the client
machine because they require decrypting data and therefore the encryption key.
@@ -117,7 +117,7 @@ repository checks only, or pass ``--archives-only`` to run the archive checks
only.
The ``--max-duration`` option can be used to split a long-running repository
-check into multiple partial checks. After the given number of seconds the check
+check into multiple partial checks. After the given number of seconds, the check
is interrupted. The next partial check will continue where the previous one
stopped, until the full repository has been checked. Assuming a complete check
would take 7 hours, then running a daily check with ``--max-duration=3600``
@@ -128,33 +128,33 @@ archive checks, nor enable repair mode. Consequently, if you want to use
``--max-duration`` you must also pass ``--repository-only``, and must not pass
``--archives-only``, nor ``--repair``.
-**Warning:** Please note that partial repository checks (i.e. running it with
+**Warning:** Please note that partial repository checks (i.e., running with
``--max-duration``) can only perform non-cryptographic checksum checks on the
-repository files. Enabling partial repository checks excepts archive checks
-for the same reason. Therefore partial checks may be useful with very large
-repositories only where a full check would take too long.
+repository files. Enabling partial repository checks excludes archive checks
+for the same reason. Therefore, partial checks may be useful only with very large
+repositories where a full check would take too long.
The ``--verify-data`` option will perform a full integrity verification (as
opposed to checking just the xxh64) of data, which means reading the
data from the repository, decrypting and decompressing it. It is a complete
-cryptographic verification and hence very time consuming, but will detect any
+cryptographic verification and hence very time-consuming, but will detect any
accidental and malicious corruption. Tamper-resistance is only guaranteed for
-encrypted repositories against attackers without access to the keys. You can
-not use ``--verify-data`` with ``--repository-only``.
+encrypted repositories against attackers without access to the keys. You cannot
+use ``--verify-data`` with ``--repository-only``.
The ``--find-lost-archives`` option will also scan the whole repository, but
tells Borg to search for lost archive metadata. If Borg encounters any archive
-metadata that doesn't match with an archive directory entry (including
+metadata that does not match an archive directory entry (including
soft-deleted archives), it means that an entry was lost.
Unless ``borg compact`` is called, these archives can be fully restored with
``--repair``. Please note that ``--find-lost-archives`` must read a lot of
-data from the repository and is thus very time consuming. You can not use
+data from the repository and is thus very time-consuming. You cannot use
``--find-lost-archives`` with ``--repository-only``.
About repair mode
+++++++++++++++++
-The check command is a readonly task by default. If any corruption is found,
+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 ``--repair``.
@@ -174,7 +174,7 @@ It is highly recommended to create a backup of your repository before running
in repair mode (i.e. running it with ``--repair``).
Repair mode will attempt to fix any corruptions found. Fixing corruptions does
-not mean recovering lost data: Borg can not magically restore data lost due to
+not mean recovering lost data: Borg cannot magically restore data lost due to
e.g. a hardware failure. Repairing a repository means sacrificing some data
for the sake of the repository as a whole and the remaining data. Hence it is,
by definition, a potentially lossy task.
diff --git a/docs/usage/common-options.rst.inc b/docs/usage/common-options.rst.inc
index b3aa1b7592..31a9df8657 100644
--- a/docs/usage/common-options.rst.inc
+++ b/docs/usage/common-options.rst.inc
@@ -13,9 +13,9 @@
--show-rc show/log the return code (rc)
--umask M set umask to M (local only, default: 0077)
--remote-path PATH use PATH as borg executable on the remote (default: "borg")
---upload-ratelimit RATE set network upload rate limit in KiB/s (default: 0=unlimited)
+--upload-ratelimit RATE set network upload rate limit in kiByte/s (default: 0=unlimited)
--upload-buffer UPLOAD_BUFFER set network upload buffer size in MiB. (default: 0=no buffer)
--debug-profile FILE Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof".
--rsh RSH Use this command to connect to the 'borg serve' process (default: 'ssh')
---socket PATH Use UNIX domain (IPC) socket at PATH for client/server communication with the socket: protocol.
+--socket PATH Use UNIX DOMAIN (IPC) socket at PATH for client/server communication with socket: protocol.
-r REPO, --repo REPO repository to use
diff --git a/docs/usage/compact.rst.inc b/docs/usage/compact.rst.inc
index 6bfffb7c0c..f71d951c85 100644
--- a/docs/usage/compact.rst.inc
+++ b/docs/usage/compact.rst.inc
@@ -15,7 +15,7 @@ borg compact
+-------------------------------------------------------+-----------------------+-----------------------------------------+
| **options** |
+-------------------------------------------------------+-----------------------+-----------------------------------------+
- | | ``-n``, ``--dry-run`` | do nothing |
+ | | ``-n``, ``--dry-run`` | do not change the repository |
+-------------------------------------------------------+-----------------------+-----------------------------------------+
| | ``-s``, ``--stats`` | print statistics (might be much slower) |
+-------------------------------------------------------+-----------------------+-----------------------------------------+
@@ -37,7 +37,7 @@ borg compact
options
- -n, --dry-run do nothing
+ -n, --dry-run do not change the repository
-s, --stats print statistics (might be much slower)
@@ -49,41 +49,39 @@ Description
Free repository space by deleting unused chunks.
-borg compact analyzes all existing archives to find out which repository
+``borg compact`` analyzes all existing archives to determine which repository
objects are actually used (referenced). It then deletes all unused objects
from the repository to free space.
Unused objects may result from:
-- borg delete or prune usage
-- interrupted backups (maybe retry the backup first before running compact)
-- backup of source files that had an I/O error in the middle of their contents
- and that were skipped due to this
-- corruption of the repository (e.g. the archives directory having lost
- entries, see notes below)
+- use of ``borg delete`` or ``borg prune``
+- interrupted backups (consider retrying the backup before running compact)
+- backups of source files that encountered an I/O error mid-transfer and were skipped
+- corruption of the repository (e.g., the archives directory lost entries; see notes below)
-You usually don't want to run ``borg compact`` after every write operation, but
-either regularly (e.g. once a month, possibly together with ``borg check``) or
+You usually do not want to run ``borg compact`` after every write operation, but
+either regularly (e.g., once a month, possibly together with ``borg check``) or
when disk space needs to be freed.
**Important:**
-After compacting it is no longer possible to use ``borg undelete`` to recover
+After compacting, it is no longer possible to use ``borg undelete`` to recover
previously soft-deleted archives.
``borg compact`` might also delete data from archives that were "lost" due to
archives directory corruption. Such archives could potentially be restored with
``borg check --find-lost-archives [--repair]``, which is slow. You therefore
-might not want to do that unless there are signs of lost archives (e.g. when
+might not want to do that unless there are signs of lost archives (e.g., when
seeing fatal errors when creating backups or when archives are missing in
``borg repo-list``).
-When giving the ``--stats`` option, borg will internally list all repository
-objects to determine their existence AND stored size. It will build a fresh
+When using the ``--stats`` option, borg will internally list all repository
+objects to determine their existence and stored size. It will build a fresh
chunks index from that information and cache it in the repository. For some
types of repositories, this might be very slow. It will tell you the sum of
stored object sizes, before and after compaction.
Without ``--stats``, borg will rely on the cached chunks index to determine
existing object IDs (but there is no stored size information in the index,
-thus it can't compute before/after compaction size statistics).
\ No newline at end of file
+thus it cannot compute before/after compaction size statistics).
\ No newline at end of file
diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc
index 11153186c4..a2385cefe4 100644
--- a/docs/usage/create.rst.inc
+++ b/docs/usage/create.rst.inc
@@ -25,7 +25,7 @@ borg create
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics for the created archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--list`` | output verbose list of items (files, dirs, ...) |
+ | | ``--list`` | output a verbose list of items (files, dirs, ...) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--filter STATUSCHARS`` | only display items with the given status characters (see description) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -39,7 +39,7 @@ borg create
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--stdin-mode M`` | set mode to M in archive for stdin data (default: 0660) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--content-from-command`` | interpret PATH as command and store its stdout. See also section Reading from stdin below. |
+ | | ``--content-from-command`` | interpret PATH as a command and store its stdout. See also the section 'Reading from stdin' below. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--paths-from-stdin`` | read DELIM-separated list of paths to back up from stdin. All control is external: it will back up all files given - no more, no less. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -65,7 +65,7 @@ borg create
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-if-present NAME`` | exclude directories that are tagged by containing a filesystem object with the given NAME |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--keep-exclude-tags`` | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive |
+ | | ``--keep-exclude-tags`` | if tag objects are specified with ``--exclude-if-present``, do not omit the tag objects themselves from the backup archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Filesystem options** |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -123,14 +123,14 @@ borg create
options
-n, --dry-run do not create a backup archive
-s, --stats print statistics for the created archive
- --list output verbose list of items (files, dirs, ...)
+ --list output a 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``.
--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)
--stdin-mode M set mode to M in archive for stdin data (default: 0660)
- --content-from-command interpret PATH as command and store its stdout. See also section Reading from stdin below.
+ --content-from-command interpret PATH as a command and store its stdout. See also the section 'Reading from stdin' below.
--paths-from-stdin read DELIM-separated list of paths to back up from stdin. All control is external: it will back up all files given - no more, no less.
--paths-from-command interpret PATH as command and treat its output as ``--paths-from-stdin``
--paths-delimiter DELIM set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``)
@@ -146,7 +146,7 @@ borg create
--patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line
--exclude-caches exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)
--exclude-if-present NAME exclude directories that are tagged by containing a filesystem object with the given NAME
- --keep-exclude-tags if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
+ --keep-exclude-tags if tag objects are specified with ``--exclude-if-present``, do not omit the tag objects themselves from the backup archive
Filesystem options
@@ -175,8 +175,8 @@ Description
~~~~~~~~~~~
This command creates a backup archive containing all files found while recursively
-traversing all paths specified. Paths are added to the archive as they are given,
-that means if relative paths are desired, the command has to be run from the correct
+traversing all specified paths. Paths are added to the archive as they are given,
+which means that if relative paths are desired, the command must be run from the correct
directory.
The slashdot hack in paths (recursion roots) is triggered by using ``/./``:
@@ -184,23 +184,23 @@ The slashdot hack in paths (recursion roots) is triggered by using ``/./``:
strip the prefix on the left side of ``./`` from the archived items (in this case,
``this/gets/archived`` will be the path in the archived item).
-When giving '-' as path, borg will read data from standard input and create a
-file 'stdin' in the created archive from that data. In some cases it's more
-appropriate to use --content-from-command, however. See section *Reading from
-stdin* below for details.
+When specifying '-' as a path, borg will read data from standard input and create a
+file named 'stdin' in the created archive from that data. In some cases, it is more
+appropriate to use --content-from-command. See the section *Reading from stdin*
+below for details.
The archive will consume almost no disk space for files or parts of files that
have already been stored in other archives.
-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)
+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.
Backup speed is increased by not reprocessing files that are already part of
-existing archives and weren't modified. The detection of unmodified files is
+existing archives and were not modified. The detection of unmodified files is
done by comparing multiple file metadata values with previous values kept in
the files cache.
@@ -226,14 +226,14 @@ improve performance, but reliability of change detection might be reduced.
ctime vs. mtime: safety vs. speed
- ctime is a rather safe way to detect changes to a file (metadata and contents)
- as it can not be set from userspace. But, a metadata-only change will already
+ as it cannot be set from userspace. But a metadata-only change will already
update the ctime, so there might be some unnecessary chunking/hashing even
without content changes. Some filesystems do not support ctime (change time).
E.g. doing a chown or chmod to a file will change its ctime.
- mtime usually works and only updates if file contents were changed. But mtime
- can be arbitrarily set from userspace, e.g. to set mtime back to the same value
+ can be arbitrarily set from userspace, e.g., to set mtime back to the same value
it had before a content change happened. This can be used maliciously as well as
- well-meant, but in both cases mtime based cache modes can be problematic.
+ well-meant, but in both cases mtime-based cache modes can be problematic.
The ``--files-changed`` option controls how Borg detects if a file has changed during backup:
- ctime (default): Use ctime to detect changes. This is the safest option.
@@ -319,7 +319,7 @@ borg usually just stores their metadata:
- 'd' = directory
- 'b' = block device
- 'c' = char device
-- 'h' = regular file, hardlink (to already seen inodes)
+- 'h' = regular file, hard link (to already seen inodes)
- 's' = symlink
- 'f' = fifo
diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc
index 5f45d325d6..455e60a397 100644
--- a/docs/usage/delete.rst.inc
+++ b/docs/usage/delete.rst.inc
@@ -19,9 +19,9 @@ borg delete
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``-n``, ``--dry-run`` | do not change repository |
+ | | ``-n``, ``--dry-run`` | do not change the repository |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--list`` | output verbose list of archives |
+ | | ``--list`` | output a verbose list of archives |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
@@ -29,21 +29,21 @@ borg delete
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. see "borg help match-archives". |
+ | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--first N`` | consider first N archives after other filters were applied |
+ | | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--last N`` | consider last N archives after other filters were applied |
+ | | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+ | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+ | | ``--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. |
+ | | ``--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. |
+ | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -61,22 +61,22 @@ borg delete
options
- -n, --dry-run do not change repository
- --list output verbose list of archives
+ -n, --dry-run do not change the repository
+ --list output a verbose list of archives
:ref:`common_options`
|
Archive filters
- -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. see "borg help match-archives".
+ -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. See "borg help match-archives".
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
- --first N consider first N archives after other filters were applied
- --last N consider last N archives after other filters were applied
- --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
- --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.
+ --first N consider the first N archives after other filters are applied
+ --last N consider the last N archives after other filters are applied
+ --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
+ --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.
Description
@@ -93,6 +93,6 @@ Important:
When in doubt, use ``--dry-run --list`` to see what would be deleted.
-You can delete multiple archives by specifying a matching pattern,
-using the ``--match-archives PATTERN`` option (for more info on these patterns,
-see :ref:`borg_patterns`).
\ No newline at end of file
+You can delete multiple archives by specifying a match pattern using
+the ``--match-archives PATTERN`` option (for more information on these
+patterns, see :ref:`borg_patterns`).
\ No newline at end of file
diff --git a/docs/usage/diff.rst.inc b/docs/usage/diff.rst.inc
index b7f166b964..899ceacae1 100644
--- a/docs/usage/diff.rst.inc
+++ b/docs/usage/diff.rst.inc
@@ -19,20 +19,20 @@ borg diff
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``ARCHIVE2`` | ARCHIVE2 name |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
- | | ``PATH`` | paths of items inside the archives to compare; patterns are supported |
+ | | ``PATH`` | paths of items inside the archives to compare; patterns are supported. |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--numeric-ids`` | only consider numeric user and group identifiers |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
- | | ``--same-chunker-params`` | Override check of chunker parameters. |
- +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
- | | ``--sort`` | Sort the output lines by file path. |
+ | | ``--same-chunker-params`` | override the check of chunker parameters |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--format FORMAT`` | specify format for differences between archives (default: "{change} {path}{NL}") |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--json-lines`` | Format output as JSON Lines. |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
+ | | ``--sort-by`` | Sort output by comma-separated fields (e.g., '>size_added,path'). |
+ +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--content-only`` | Only compare differences in content (exclude metadata differences) |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
@@ -65,15 +65,15 @@ borg diff
ARCHIVE2
ARCHIVE2 name
PATH
- paths of items inside the archives to compare; patterns are supported
+ paths of items inside the archives to compare; patterns are supported.
options
--numeric-ids only consider numeric user and group identifiers
- --same-chunker-params Override check of chunker parameters.
- --sort Sort the output lines by file path.
+ --same-chunker-params override the check of chunker parameters
--format FORMAT specify format for differences between archives (default: "{change} {path}{NL}")
- --json-lines Format output as JSON Lines.
+ --json-lines Format output as JSON Lines.
+ --sort-by Sort output by comma-separated fields (e.g., '>size_added,path').
--content-only Only compare differences in content (exclude metadata differences)
@@ -92,15 +92,15 @@ Description
This command finds differences (file contents, metadata) between ARCHIVE1 and ARCHIVE2.
-For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
+For more help on include/exclude patterns, see the output of the :ref:`borg_patterns` command.
.. man NOTES
The FORMAT specifier syntax
+++++++++++++++++++++++++++
-The ``--format`` option uses python's `format string syntax
-`_.
+The ``--format`` option uses Python's `format string syntax
+`_.
Examples:
::
@@ -148,3 +148,49 @@ Keys available only when showing differences between archives:
- ctime: file change time change
- isomtime: file modification time change (ISO 8601)
- isoctime: file creation time change (ISO 8601)
+
+
+What is compared
++++++++++++++++++
+For each matching item in both archives, Borg reports:
+
+- Content changes: total added/removed bytes within files. If chunker parameters are comparable,
+ Borg compares chunk IDs quickly; otherwise, it compares the content.
+- Metadata changes: user, group, mode, and other metadata shown inline, like
+ "[old_mode -> new_mode]" for mode changes. Use ``--content-only`` to suppress metadata changes.
+- Added/removed items: printed as "added SIZE path" or "removed SIZE path".
+
+Output formats
+++++++++++++++
+The default (text) output shows one line per changed path, e.g.::
+
+ +135 B -252 B [ -rw-r--r-- -> -rwxr-xr-x ] path/to/file
+
+JSON Lines output (``--json-lines``) prints one JSON object per changed path, e.g.::
+
+ {"path": "PATH", "changes": [
+ {"type": "modified", "added": BYTES, "removed": BYTES},
+ {"type": "mode", "old_mode": "-rw-r--r--", "new_mode": "-rwxr-xr-x"},
+ {"type": "added", "size": SIZE},
+ {"type": "removed", "size": SIZE}
+ ]}
+
+Sorting
+++++++++
+Use ``--sort-by FIELDS`` where FIELDS is a comma-separated list of fields.
+Sorts are applied stably from last to first in the given list. Prepend ">" for
+descending, "<" (or no prefix) for ascending, for example ``--sort-by=">size_added,path"``.
+Supported fields include:
+
+- path: the item path
+- size_added: total bytes added for the item content
+- size_removed: total bytes removed for the item content
+- size_diff: size_added - size_removed (net content change)
+- size: size of the item as stored in ARCHIVE2 (0 for removed items)
+- user, group, uid, gid, ctime, mtime: taken from the item state in ARCHIVE2 when present
+- ctime_diff, mtime_diff: timestamp difference (ARCHIVE2 - ARCHIVE1)
+
+Performance considerations
+++++++++++++++++++++++++++
+diff automatically detects whether the archives were created with the same chunker
+parameters. If so, only chunk IDs are compared, which is very fast.
diff --git a/docs/usage/export-tar.rst.inc b/docs/usage/export-tar.rst.inc
index ab2109c6f2..ad1f6a635c 100644
--- a/docs/usage/export-tar.rst.inc
+++ b/docs/usage/export-tar.rst.inc
@@ -102,7 +102,7 @@ Alternatively, a ``--tar-filter`` program may be explicitly specified. It should
read the uncompressed tar stream from stdin and write a compressed/filtered
tar stream to stdout.
-Depending on the ``-tar-format`` option, these formats are created:
+Depending on the ``--tar-format`` option, these formats are created:
+--------------+---------------------------+----------------------------+
| --tar-format | Specification | Metadata |
diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc
index b99dd03dd6..febbdab655 100644
--- a/docs/usage/extract.rst.inc
+++ b/docs/usage/extract.rst.inc
@@ -21,11 +21,11 @@ borg extract
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
- | | ``--list`` | output verbose list of items (files, dirs, ...) |
+ | | ``--list`` | output a verbose list of items (files, dirs, ...) |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not actually change any files |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
- | | ``--numeric-ids`` | only obey numeric user and group identifiers |
+ | | ``--numeric-ids`` | only use numeric user and group identifiers |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--noflags`` | do not extract/set flags (e.g. NODUMP, IMMUTABLE) |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -35,9 +35,9 @@ borg extract
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--stdout`` | write all extracted data to stdout |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
- | | ``--sparse`` | create holes in output sparse file from all-zero chunks |
+ | | ``--sparse`` | create holes in the output sparse file from all-zero chunks |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
- | | ``--continue`` | continue a previously interrupted extraction of same archive |
+ | | ``--continue`` | continue a previously interrupted extraction of the same archive |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
@@ -73,15 +73,15 @@ borg extract
options
- --list output verbose list of items (files, dirs, ...)
+ --list output a verbose list of items (files, dirs, ...)
-n, --dry-run do not actually change any files
- --numeric-ids only obey numeric user and group identifiers
+ --numeric-ids only use numeric user and group identifiers
--noflags do not extract/set flags (e.g. NODUMP, IMMUTABLE)
--noacls do not extract/set ACLs
--noxattrs do not extract/set xattrs
--stdout write all extracted data to stdout
- --sparse create holes in output sparse file from all-zero chunks
- --continue continue a previously interrupted extraction of same archive
+ --sparse create holes in the output sparse file from all-zero chunks
+ --continue continue a previously interrupted extraction of the same archive
:ref:`common_options`
@@ -98,16 +98,20 @@ borg extract
Description
~~~~~~~~~~~
-This command extracts the contents of an archive. By default the entire
-archive is extracted but a subset of files and directories can be selected
-by passing a list of ``PATHs`` as arguments. The file selection can further
-be restricted by using the ``--exclude`` option.
+This command extracts the contents of an archive.
+By default, the entire archive is extracted, but a subset of files and directories
+can be selected by passing a list of ``PATH`` arguments. The default interpretation
+for the paths to extract is `pp:` which is a literal path-prefix match. If you want
+to use e.g. a wildcard, you must select a different pattern style such as `sh:` or
+`fm:`. See :ref:`borg_patterns` for more information.
+
+The file selection can be further restricted by using the ``--exclude`` option.
For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
By using ``--dry-run``, you can do all extraction steps except actually writing the
-output data: reading metadata and data chunks from the repo, checking the hash/hmac,
-decrypting, decompressing.
+output data: reading metadata and data chunks from the repository, checking the hash/HMAC,
+decrypting, and decompressing.
``--progress`` can be slower than no progress display, since it makes one additional
pass over the archive metadata.
@@ -118,5 +122,5 @@ pass over the archive metadata.
so make sure you ``cd`` to the right place before calling ``borg extract``.
When parent directories are not extracted (because of using file/directory selection
- or any other reason), borg can not restore parent directories' metadata, e.g. owner,
- group, permission, etc.
\ No newline at end of file
+ or any other reason), Borg cannot restore parent directories' metadata, e.g., owner,
+ group, permissions, etc.
\ No newline at end of file
diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc
index b8bc22954e..0a471b1dd8 100644
--- a/docs/usage/help.rst.inc
+++ b/docs/usage/help.rst.inc
@@ -17,21 +17,27 @@ unwanted ones. Patterns can be used
- in the file given with ``--patterns-from`` option and
- for ``PATH`` arguments that explicitly support them.
-Borg always stores all file paths normalized and relative to the
-current recursion root. The recursion root is also named ``PATH`` in
-Borg commands like `borg create` that do a file discovery, so do not
-confuse the root with the ``PATH`` argument of e.g. `borg extract`.
+The path/filenames used as input for the pattern matching start with the
+currently active recursion root. You usually give the recursion root(s)
+when invoking borg and these can be either relative or absolute paths.
-Starting with Borg 1.2, paths that are matched against patterns always
-appear relative. If you give ``/absolute/`` as root, the paths going
-into the matcher will start with ``absolute/``.
-If you give ``../../relative`` as root, the paths will be normalized
-as ``relative/``.
+Be careful, your patterns must match the archived paths:
+
+- Archived paths never start with a leading slash ('/'), nor with '.', nor with '..'.
+
+ - When you back up absolute paths like ``/home/user``, the archived
+ paths start with ``home/user``.
+ - When you back up relative paths like ``./src``, the archived paths
+ start with ``src``.
+ - When you back up relative paths like ``../../src``, the archived paths
+ start with ``src``.
Borg supports different pattern styles. To define a non-default
style for a specific pattern, prefix it with two characters followed
by a colon ':' (i.e. ``fm:path/*``, ``sh:path/**``).
+The default pattern style for ``--exclude`` differs from ``--pattern``, see below.
+
`Fnmatch `_, selector ``fm:``
This is the default style for ``--exclude`` and ``--exclude-from``.
These patterns use a variant of shell pattern syntax, with '\*' matching
@@ -64,13 +70,13 @@ Shell-style patterns, selector ``sh:``
always normalized to a forward slash '/' before applying a pattern.
Path prefix, selector ``pp:``
- This pattern style is useful to match whole sub-directories. The pattern
+ This pattern style is useful to match whole subdirectories. The pattern
``pp:root/somedir`` matches ``root/somedir`` and everything therein.
A leading path separator is always removed.
Path full-match, selector ``pf:``
This pattern style is (only) useful to match full paths.
- This is kind of a pseudo pattern as it can not have any variable or
+ This is kind of a pseudo pattern as it cannot have any variable or
unspecified parts - the full path must be given. ``pf:root/file.ext``
matches ``root/file.ext`` only. A leading path separator is always
removed.
@@ -97,13 +103,13 @@ Exclusions can be passed via the command line option ``--exclude``. When used
from within a shell, the patterns should be quoted to protect them from
expansion.
-Patterns matching special characters, e.g. white space, within a shell may
+Patterns matching special characters, e.g. whitespace, within a shell may
require adjustments, such as putting quotation marks around the arguments.
-Example:
+Example:
Using bash, the following command line option would match and exclude "item name":
``--pattern='-path/item name'``
-Note that when patterns are used within a pattern file directly read by borg,
-e.g. when using ``--exclude-from`` or ``--patterns-from``, there is no shell
+Note that when patterns are used within a pattern file directly read by borg,
+e.g. when using ``--exclude-from`` or ``--patterns-from``, there is no shell
involved and thus no quotation marks are required.
The ``--exclude-from`` option permits loading exclusion patterns from a text
@@ -118,6 +124,17 @@ run ``borg create --list --dry-run ...``.
Examples::
+ # Exclude a directory anywhere in the tree named ``steamapps/common``
+ # (and everything below it), regardless of where it appears:
+ $ borg create -e 'sh:**/steamapps/common/**' archive /
+
+ # Exclude the contents of ``/home/user/.cache``:
+ $ borg create -e 'sh:home/user/.cache/**' archive /home/user
+ $ borg create -e home/user/.cache/ archive /home/user
+
+ # The file '/home/user/.cache/important' is *not* backed up:
+ $ borg create -e home/user/.cache/ archive / /home/user/.cache/important
+
# Exclude '/home/user/file.o' but not '/home/user/file.odt':
$ borg create -e '*.o' archive /
@@ -125,11 +142,6 @@ Examples::
# not '/home/user/importantjunk' or '/etc/junk':
$ borg create -e 'home/*/junk' archive /
- # Exclude the contents of '/home/user/cache' but not the directory itself:
- $ borg create -e home/user/cache/ archive /
-
- # The file '/home/user/cache/important' is *not* backed up:
- $ borg create -e home/user/cache/ archive / /home/user/cache/important
# The contents of directories in '/home' are not backed up when their name
# ends in '.tmp'
@@ -158,11 +170,13 @@ Root path prefix ``R``
(a plain path, not a file pattern). Use this prefix to have the root
paths in the patterns file rather than as command line arguments.
-Pattern style prefix ``P``
+Pattern style prefix ``P`` (only useful within patterns files)
To change the default pattern style, use the ``P`` prefix, followed by
the pattern style abbreviation (``fm``, ``pf``, ``pp``, ``re``, ``sh``).
- All patterns following this line will use this style until another style
- is specified.
+ All patterns following this line in the same patterns file will use this
+ style until another style is specified or the end of the file is reached.
+ When the current patterns file is finished, the default pattern style will
+ reset.
Exclude pattern prefix ``-``
Use the prefix ``-``, followed by a pattern, to define an exclusion.
@@ -212,7 +226,7 @@ character that indicates the action (e.g. 'x' for excluding, see
.. note::
- It's possible that a sub-directory/file is matched while parent
+ It is possible that a subdirectory or file is matched while its parent
directories are not. In that case, parent directories are not backed
up and thus their user, group, permission, etc. cannot be restored.
@@ -340,11 +354,11 @@ and ``--remote-path`` values support these placeholders:
{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}
{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}
{user}
The user name (or UID, if no name is available) of the user running borg.
@@ -390,14 +404,14 @@ borg help compression
~~~~~~~~~~~~~~~~~~~~~
-It is no problem to mix different compression methods in one repo,
+It is no problem to mix different compression methods in one repository,
deduplication is done on the source data chunks (not on the compressed
or encrypted data).
-If some specific chunk was once compressed and stored into the repo, creating
+If some specific chunk was once compressed and stored into the repository, creating
another backup that also uses this chunk will not change the stored chunk.
So if you use different compression specs for the backups, whichever stores a
-chunk first determines its compression. See also borg recreate.
+chunk first determines its compression. See also ``borg recreate``.
Compression is lz4 by default. If you want something else, you have to specify what you want.
diff --git a/docs/usage/info.rst.inc b/docs/usage/info.rst.inc
index c09e788fd7..17e72e94e5 100644
--- a/docs/usage/info.rst.inc
+++ b/docs/usage/info.rst.inc
@@ -27,21 +27,21 @@ borg info
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. see "borg help match-archives". |
+ | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--first N`` | consider first N archives after other filters were applied |
+ | | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--last N`` | consider last N archives after other filters were applied |
+ | | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+ | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+ | | ``--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. |
+ | | ``--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. |
+ | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -66,14 +66,14 @@ borg info
|
Archive filters
- -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. see "borg help match-archives".
+ -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. See "borg help match-archives".
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
- --first N consider first N archives after other filters were applied
- --last N consider last N archives after other filters were applied
- --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
- --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.
+ --first N consider the first N archives after other filters are applied
+ --last N consider the last N archives after other filters are applied
+ --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
+ --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.
Description
@@ -83,9 +83,9 @@ This command displays detailed information about the specified archive.
Please note that the deduplicated sizes of the individual archives do not add
up to the deduplicated size of the repository ("all archives"), because the two
-are meaning different things:
+mean different things:
This archive / deduplicated size = amount of data stored ONLY for this archive
= unique chunks of this archive.
-All archives / deduplicated size = amount of data stored in the repo
+All archives / deduplicated size = amount of data stored in the repository
= all chunks in the repository.
\ No newline at end of file
diff --git a/docs/usage/key_change-location.rst.inc b/docs/usage/key_change-location.rst.inc
index 956c5cb228..99010e90d0 100644
--- a/docs/usage/key_change-location.rst.inc
+++ b/docs/usage/key_change-location.rst.inc
@@ -50,10 +50,10 @@ borg key change-location
Description
~~~~~~~~~~~
-Change the location of a borg key. The key can be stored at different locations:
+Change the location of a Borg key. The key can be stored at different locations:
- keyfile: locally, usually in the home directory
-- repokey: inside the repo (in the repo config)
+- repokey: inside the repository (in the repository config)
Please note:
diff --git a/docs/usage/key_export.rst.inc b/docs/usage/key_export.rst.inc
index e50af3c84d..bdf8ddc091 100644
--- a/docs/usage/key_export.rst.inc
+++ b/docs/usage/key_export.rst.inc
@@ -21,7 +21,7 @@ borg key export
+-------------------------------------------------------+---------------+------------------------------------------------------------------------+
| | ``--paper`` | Create an export suitable for printing and later type-in |
+-------------------------------------------------------+---------------+------------------------------------------------------------------------+
- | | ``--qr-html`` | Create an html file suitable for printing and later type-in or qr scan |
+ | | ``--qr-html`` | Create an HTML file suitable for printing and later type-in or QR scan |
+-------------------------------------------------------+---------------+------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
@@ -44,7 +44,7 @@ borg key export
options
--paper Create an export suitable for printing and later type-in
- --qr-html Create an html file suitable for printing and later type-in or qr scan
+ --qr-html Create an HTML file suitable for printing and later type-in or QR scan
:ref:`common_options`
diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc
index fec6aa32e5..f2490c666c 100644
--- a/docs/usage/list.rst.inc
+++ b/docs/usage/list.rst.inc
@@ -27,7 +27,7 @@ borg list
+-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--json-lines`` | Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. |
+-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--depth N`` | only list files up to the specified directory level depth |
+ | | ``--depth N`` | only list files up to the specified directory depth |
+-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
@@ -64,7 +64,7 @@ borg list
--short only print file/directory names, nothing else
--format FORMAT specify format for file listing (default: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}")
--json-lines Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text.
- --depth N only list files up to the specified directory level depth
+ --depth N only list files up to the specified directory depth
:ref:`common_options`
@@ -82,15 +82,15 @@ Description
This command lists the contents of an archive.
-For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
+For more help on include/exclude patterns, see the output of :ref:`borg_patterns`.
.. man NOTES
The FORMAT specifier syntax
+++++++++++++++++++++++++++
-The ``--format`` option uses python's `format string syntax
-`_.
+The ``--format`` option uses Python's `format string syntax
+`_.
Examples:
::
@@ -127,6 +127,7 @@ Keys available only when listing files in an archive:
- path: file path
- target: link target for symlinks
- hlid: hard link identity (same if hardlinking same fs object)
+- inode: inode number
- flags: file flags
- size: file size
diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc
index db480fa38c..78c67d1775 100644
--- a/docs/usage/mount.rst.inc
+++ b/docs/usage/mount.rst.inc
@@ -15,7 +15,7 @@ borg mount
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``MOUNTPOINT`` | where to mount filesystem |
+ | | ``MOUNTPOINT`` | where to mount the filesystem |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to extract; patterns are supported |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
@@ -23,9 +23,9 @@ borg mount
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``-f``, ``--foreground`` | stay in foreground, do not daemonize |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``-o`` | Extra mount options |
+ | | ``-o`` | extra mount options |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--numeric-ids`` | use numeric user and group identifiers from archive(s) |
+ | | ``--numeric-ids`` | use numeric user and group identifiers from archives |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
@@ -33,21 +33,21 @@ borg mount
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. see "borg help match-archives". |
+ | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--first N`` | consider first N archives after other filters were applied |
+ | | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--last N`` | consider last N archives after other filters were applied |
+ | | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+ | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+ | | ``--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. |
+ | | ``--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. |
+ | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| **Include/Exclude options** |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
@@ -73,29 +73,29 @@ borg mount
.. only:: latex
MOUNTPOINT
- where to mount filesystem
+ where to mount the filesystem
PATH
paths to extract; patterns are supported
options
-f, --foreground stay in foreground, do not daemonize
- -o Extra mount options
- --numeric-ids use numeric user and group identifiers from archive(s)
+ -o extra mount options
+ --numeric-ids use numeric user and group identifiers from archives
:ref:`common_options`
|
Archive filters
- -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. see "borg help match-archives".
+ -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. See "borg help match-archives".
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
- --first N consider first N archives after other filters were applied
- --last N consider last N archives after other filters were applied
- --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
- --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.
+ --first N consider the first N archives after other filters are applied
+ --last N consider the last N archives after other filters are applied
+ --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
+ --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.
Include/Exclude options
@@ -119,15 +119,15 @@ 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.
-Unless the ``--foreground`` option is given the command will run in the
-background until the filesystem is ``umounted``.
+Unless the ``--foreground`` option is given, the command will run in the
+background until the filesystem is ``unmounted``.
Performance tips:
-- when doing a "whole repository" mount:
- do not enter archive dirs if not needed, this avoids on-demand loading.
-- only mount a specific archive, not the whole repository.
-- only mount specific paths in a specific archive, not the complete archive.
+- When doing a "whole repository" mount:
+ do not enter archive directories if not needed; this avoids on-demand loading.
+- Only mount a specific archive, not the whole repository.
+- Only mount specific paths in a specific archive, not the complete archive.
The command ``borgfs`` provides a wrapper for ``borg mount``. This can also be
used in fstab entries:
@@ -139,35 +139,35 @@ To allow a regular user to use fstab entries, add the ``user`` option:
For FUSE configuration and mount options, see the mount.fuse(8) manual page.
Borg's default behavior is to use the archived user and group names of each
-file and map them to the system's respective user and group ids.
+file and map them to the system's respective user and group IDs.
Alternatively, using ``numeric-ids`` will instead use the archived user and
-group ids without any mapping.
+group IDs without any mapping.
The ``uid`` and ``gid`` mount options (implemented by Borg) can be used to
-override the user and group ids of all files (i.e., ``borg mount -o
+override the user and group IDs of all files (i.e., ``borg mount -o
uid=1000,gid=1000``).
The man page references ``user_id`` and ``group_id`` mount options
-(implemented by fuse) which specify the user and group id of the mount owner
-(aka, the user who does the mounting). It is set automatically by libfuse (or
+(implemented by FUSE) which specify the user and group ID of the mount owner
+(also known as the user who does the mounting). It is set automatically by libfuse (or
the filesystem if libfuse is not used). However, you should not specify these
-manually. Unlike the ``uid`` and ``gid`` mount options which affect all files,
-``user_id`` and ``group_id`` affect the user and group id of the mounted
+manually. Unlike the ``uid`` and ``gid`` mount options, which affect all files,
+``user_id`` and ``group_id`` affect the user and group ID of the mounted
(base) directory.
-Additional mount options supported by borg:
+Additional mount options supported by Borg:
- ``versions``: when used with a repository mount, this gives a merged, versioned
- view of the files in the archives. EXPERIMENTAL, layout may change in future.
-- ``allow_damaged_files``: by default damaged files (where chunks are missing)
+ view of the files in the archives. EXPERIMENTAL; layout may change in the future.
+- ``allow_damaged_files``: by default, damaged files (where chunks are missing)
will return EIO (I/O error) when trying to read the related parts of the file.
Set this option to replace the missing parts with all-zero bytes.
- ``ignore_permissions``: for security reasons the ``default_permissions`` mount
- option is internally enforced by borg. ``ignore_permissions`` can be given to
+ option is internally enforced by Borg. ``ignore_permissions`` can be given to
not enforce ``default_permissions``.
-The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users
-to tweak the performance. It sets the number of cached data chunks; additional
+The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is intended for advanced users
+to tweak performance. It sets the number of cached data chunks; additional
memory usage can be up to ~8 MiB times this number. The default is the number
of CPU cores.
@@ -176,4 +176,11 @@ Unmounting in these cases could cause an active rsync or similar process
to delete data unintentionally.
When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
-but other signals or crashes do not.
\ No newline at end of file
+but other signals or crashes do not.
+
+Debugging:
+
+``borg mount`` usually daemonizes and the daemon process sends stdout/stderr
+to /dev/null. Thus, you need to either use ``-f / --foreground`` to make it stay
+in the foreground and not daemonize, or use ``BORG_LOGGING_CONF`` to reconfigure
+the logger to output to a file.
\ No newline at end of file
diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc
index a781e9619d..00c048a90a 100644
--- a/docs/usage/prune.rst.inc
+++ b/docs/usage/prune.rst.inc
@@ -12,61 +12,61 @@ borg prune
.. class:: borg-options-table
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | **positional arguments** |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``NAME`` | specify the archive name |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | **options** |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``-n``, ``--dry-run`` | do not change repository |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``--list`` | output verbose list of archives it keeps/prunes |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``--short`` | use a less wide archive part format |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``--list-pruned`` | output verbose list of archives it prunes |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``--list-kept`` | output verbose list of archives it keeps |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``--format FORMAT`` | specify format for the archive part (default: "{archive:<36} {time} [{id}]") |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``--keep-within INTERVAL`` | keep all archives within this time interval |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``--keep-last``, ``--keep-secondly`` | number of secondly archives to keep |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``--keep-minutely`` | number of minutely archives to keep |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``-H``, ``--keep-hourly`` | number of hourly archives to keep |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``-d``, ``--keep-daily`` | number of daily archives to keep |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``-w``, ``--keep-weekly`` | number of weekly archives to keep |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``-m``, ``--keep-monthly`` | number of monthly archives to keep |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``--keep-13weekly`` | number of quarterly archives to keep (13 week strategy) |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``--keep-3monthly`` | number of quarterly archives to keep (3 month strategy) |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``-y``, ``--keep-yearly`` | number of yearly archives to keep |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | .. class:: borg-common-opt-ref |
- | |
- | :ref:`common_options` |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | **Archive filters** — Archive filters can be applied to repository targets. |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. see "borg help match-archives". |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
- | | ``--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. |
- +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | **positional arguments** |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``NAME`` | specify the archive name |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | **options** |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``-n``, ``--dry-run`` | do not change the repository |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``--list`` | output a verbose list of archives it keeps/prunes |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``--short`` | use a less wide archive part format |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``--list-pruned`` | output verbose list of archives it prunes |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``--list-kept`` | output verbose list of archives it keeps |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``--format FORMAT`` | specify format for the archive part (default: "{archive:<36} {time} [{id}]") |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``--keep-within INTERVAL`` | keep all archives within this time interval |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``--keep-last``, ``--keep-secondly`` | number of secondly archives to keep |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``--keep-minutely`` | number of minutely archives to keep |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``-H``, ``--keep-hourly`` | number of hourly archives to keep |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``-d``, ``--keep-daily`` | number of daily archives to keep |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``-w``, ``--keep-weekly`` | number of weekly archives to keep |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``-m``, ``--keep-monthly`` | number of monthly archives to keep |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``--keep-13weekly`` | number of quarterly archives to keep (13 week strategy) |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``--keep-3monthly`` | number of quarterly archives to keep (3 month strategy) |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``-y``, ``--keep-yearly`` | number of yearly archives to keep |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | .. class:: borg-common-opt-ref |
+ | |
+ | :ref:`common_options` |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | **Archive filters** — Archive filters can be applied to repository targets. |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
+ | | ``--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. |
+ +-----------------------------------------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -83,8 +83,8 @@ borg prune
options
- -n, --dry-run do not change repository
- --list output verbose list of archives it keeps/prunes
+ -n, --dry-run do not change the repository
+ --list output a verbose list of archives it keeps/prunes
--short use a less wide archive part format
--list-pruned output verbose list of archives it prunes
--list-kept output verbose list of archives it keeps
@@ -105,11 +105,11 @@ borg prune
|
Archive filters
- -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. see "borg help match-archives".
- --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
- --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.
+ -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. See "borg help match-archives".
+ --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
+ --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.
Description
diff --git a/docs/usage/recreate.rst.inc b/docs/usage/recreate.rst.inc
index 728360c59e..00b4bf3e6c 100644
--- a/docs/usage/recreate.rst.inc
+++ b/docs/usage/recreate.rst.inc
@@ -45,25 +45,25 @@ borg recreate
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-if-present NAME`` | exclude directories that are tagged by containing a filesystem object with the given NAME |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--keep-exclude-tags`` | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive |
+ | | ``--keep-exclude-tags`` | if tag objects are specified with ``--exclude-if-present``, do not omit the tag objects themselves from the backup archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. see "borg help match-archives". |
+ | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--first N`` | consider first N archives after other filters were applied |
+ | | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--last N`` | consider last N archives after other filters were applied |
+ | | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+ | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+ | | ``--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. |
+ | | ``--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. |
+ | | ``--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 |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -107,18 +107,18 @@ borg recreate
--patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line
--exclude-caches exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)
--exclude-if-present NAME exclude directories that are tagged by containing a filesystem object with the given NAME
- --keep-exclude-tags if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
+ --keep-exclude-tags if tag objects are specified with ``--exclude-if-present``, do not omit the tag objects themselves from the backup archive
Archive filters
- -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. see "borg help match-archives".
+ -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. See "borg help match-archives".
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
- --first N consider first N archives after other filters were applied
- --last N consider last N archives after other filters were applied
- --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
- --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.
+ --first N consider the first N archives after other filters are applied
+ --last N consider the last N archives after other filters are applied
+ --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
+ --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
--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.
@@ -131,15 +131,15 @@ Description
Recreate the contents of existing archives.
-recreate is a potentially dangerous function and might lead to data loss
+Recreate is a potentially dangerous function and might lead to data loss
(if used wrongly). BE VERY CAREFUL!
Important: Repository disk space is **not** freed until you run ``borg compact``.
``--exclude``, ``--exclude-from``, ``--exclude-if-present``, ``--keep-exclude-tags``
and PATH have the exact same semantics as in "borg create", but they only check
-for files in the archives and not in the local file system. If PATHs are specified,
-the resulting archives will only contain files from these PATHs.
+files in the archives and not in the local filesystem. If paths are specified,
+the resulting archives will contain only files from those paths.
Note that all paths in an archive are relative, therefore absolute patterns/paths
will *not* match (``--exclude``, ``--exclude-from``, PATHs).
@@ -148,9 +148,9 @@ will *not* match (``--exclude``, ``--exclude-from``, PATHs).
used to have upgraded Borg 0.xx archives deduplicate with Borg 1.x archives.
**USE WITH CAUTION.**
-Depending on the PATHs and patterns given, recreate can be used to
+Depending on the paths and patterns given, recreate can be used to
delete files from archives permanently.
-When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHS are
+When in doubt, use ``--dry-run --verbose --list`` to see how patterns/paths are
interpreted. See :ref:`list_item_flags` in ``borg create`` for details.
The archive being recreated is only removed after the operation completes. The
@@ -165,5 +165,5 @@ chunker params.
If your most recent borg check found missing chunks, please first run another
backup for the same data, before doing any rechunking. If you are lucky, that
-will re-create the missing chunks. Optionally, do another borg check, to see
-if the chunks are still missing).
\ No newline at end of file
+will recreate the missing chunks. Optionally, do another borg check to see
+if the chunks are still missing.
\ No newline at end of file
diff --git a/docs/usage/rename.rst.inc b/docs/usage/rename.rst.inc
index 96cb62066c..7405a7fc86 100644
--- a/docs/usage/rename.rst.inc
+++ b/docs/usage/rename.rst.inc
@@ -12,17 +12,17 @@ borg rename
.. class:: borg-options-table
- +-------------------------------------------------------+-------------+------------------------------+
- | **positional arguments** |
- +-------------------------------------------------------+-------------+------------------------------+
- | | ``OLDNAME`` | specify the archive name |
- +-------------------------------------------------------+-------------+------------------------------+
- | | ``NEWNAME`` | specify the new archive name |
- +-------------------------------------------------------+-------------+------------------------------+
- | .. class:: borg-common-opt-ref |
- | |
- | :ref:`common_options` |
- +-------------------------------------------------------+-------------+------------------------------+
+ +-------------------------------------------------------+-------------+----------------------------------+
+ | **positional arguments** |
+ +-------------------------------------------------------+-------------+----------------------------------+
+ | | ``OLDNAME`` | specify the current archive name |
+ +-------------------------------------------------------+-------------+----------------------------------+
+ | | ``NEWNAME`` | specify the new archive name |
+ +-------------------------------------------------------+-------------+----------------------------------+
+ | .. class:: borg-common-opt-ref |
+ | |
+ | :ref:`common_options` |
+ +-------------------------------------------------------+-------------+----------------------------------+
.. raw:: html
@@ -35,7 +35,7 @@ borg rename
.. only:: latex
OLDNAME
- specify the archive name
+ specify the current archive name
NEWNAME
specify the new archive name
diff --git a/docs/usage/repo-create.rst.inc b/docs/usage/repo-create.rst.inc
index 965a5e84b9..50bdfdb67e 100644
--- a/docs/usage/repo-create.rst.inc
+++ b/docs/usage/repo-create.rst.inc
@@ -12,21 +12,21 @@ borg repo-create
.. class:: borg-options-table
- +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------+
- | **options** |
- +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------+
- | | ``--other-repo SRC_REPOSITORY`` | reuse the key material from the other repository |
- +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------+
- | | ``--from-borg1`` | other repository is borg 1.x |
- +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------+
- | | ``-e MODE``, ``--encryption MODE`` | select encryption key mode **(required)** |
- +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------+
- | | ``--copy-crypt-key`` | copy the crypt_key (used for authenticated encryption) from the key of the other repo (default: new random key). |
- +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------+
- | .. class:: borg-common-opt-ref |
- | |
- | :ref:`common_options` |
- +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------+
+ +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------------+
+ | **options** |
+ +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------------+
+ | | ``--other-repo SRC_REPOSITORY`` | reuse the key material from the other repository |
+ +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------------+
+ | | ``--from-borg1`` | other repository is Borg 1.x |
+ +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------------+
+ | | ``-e MODE``, ``--encryption MODE`` | select encryption key mode **(required)** |
+ +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------------+
+ | | ``--copy-crypt-key`` | copy the crypt_key (used for authenticated encryption) from the key of the other repository (default: new random key). |
+ +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------------+
+ | .. class:: borg-common-opt-ref |
+ | |
+ | :ref:`common_options` |
+ +-------------------------------------------------------+------------------------------------+------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -42,9 +42,9 @@ borg repo-create
options
--other-repo SRC_REPOSITORY reuse the key material from the other repository
- --from-borg1 other repository is borg 1.x
+ --from-borg1 other repository is Borg 1.x
-e MODE, --encryption MODE select encryption key mode **(required)**
- --copy-crypt-key copy the crypt_key (used for authenticated encryption) from the key of the other repo (default: new random key).
+ --copy-crypt-key copy the crypt_key (used for authenticated encryption) from the key of the other repository (default: new random key).
:ref:`common_options`
@@ -60,8 +60,8 @@ Repository creation can be quite slow for some kinds of stores (e.g. for ``sftp:
this is due to borgstore pre-creating all directories needed, making usage of the
store faster.
-Encryption mode TLDR
-++++++++++++++++++++
+Encryption mode TL;DR
++++++++++++++++++++++
The encryption mode can only be configured when creating a new repository - you can
neither configure it on a per-archive basis nor change the mode of an existing repository.
@@ -86,7 +86,7 @@ Borg will:
"leaving your keys inside your car" (see :ref:`borg_key_export`).
The encryption is done locally - if you use a remote repository, the remote machine
never sees your passphrase, your unencrypted key or your unencrypted files.
- Chunking and id generation are also based on your key to improve
+ Chunking and ID generation are also based on your key to improve
your privacy.
7. Use the key when extracting files to decrypt them and to verify that the contents of
the backups have not been accidentally or maliciously altered.
@@ -96,27 +96,27 @@ Picking a passphrase
Make sure you use a good passphrase. Not too short, not too simple. The real
encryption / decryption key is encrypted with / locked by your passphrase.
-If an attacker gets your key, he can't unlock and use it without knowing the
+If an attacker gets your key, they cannot unlock and use it without knowing the
passphrase.
-Be careful with special or non-ascii characters in your passphrase:
+Be careful with special or non-ASCII characters in your passphrase:
-- Borg processes the passphrase as unicode (and encodes it as utf-8),
+- Borg processes the passphrase as Unicode (and encodes it as UTF-8),
so it does not have problems dealing with even the strangest characters.
-- BUT: that does not necessarily apply to your OS / VM / keyboard configuration.
+- BUT: that does not necessarily apply to your OS/VM/keyboard configuration.
-So better use a long passphrase made from simple ascii chars than one that
-includes non-ascii stuff or characters that are hard/impossible to enter on
+So better use a long passphrase made from simple ASCII characters than one that
+includes non-ASCII stuff or characters that are hard or impossible to enter on
a different keyboard layout.
-You can change your passphrase for existing repos at any time, it won't affect
+You can change your passphrase for existing repositories at any time; it will not affect
the encryption/decryption key or other secrets.
Choosing an encryption mode
+++++++++++++++++++++++++++
Depending on your hardware, hashing and crypto performance may vary widely.
-The easiest way to find out about what's fastest is to run ``borg benchmark cpu``.
+The easiest way to find out what is fastest is to run ``borg benchmark cpu``.
`repokey` modes: if you want ease-of-use and "passphrase" security is good enough -
the key will be stored in the repository (in ``repo_dir/config``).
@@ -149,14 +149,14 @@ in the upper part of the table, in the lower part is the old and/or unsafe(r) st
.. nanorst: inline-replace
-`none` mode uses no encryption and no authentication. You're advised NOT to use this mode
+`none` mode uses no encryption and no authentication. You are advised NOT to use this mode
as it would expose you to all sorts of issues (DoS, confidentiality, tampering, ...) in
case of malicious activity in the repository.
If you do **not** want to encrypt the contents of your backups, but still want to detect
-malicious tampering use an `authenticated` mode. It's like `repokey` minus encryption.
-To normally work with ``authenticated`` repos, you will need the passphrase, but
-there is an emergency workaround, see ``BORG_WORKAROUNDS=authenticated_no_key`` docs.
+malicious tampering, use an `authenticated` mode. It is like `repokey` minus encryption.
+To normally work with ``authenticated`` repositories, you will need the passphrase, but
+there is an emergency workaround; see ``BORG_WORKAROUNDS=authenticated_no_key`` docs.
Creating a related repository
+++++++++++++++++++++++++++++
@@ -168,12 +168,12 @@ By default, only the ID key and chunker secret will be the same (these are impor
for deduplication) and the AE crypto keys will be newly generated random keys.
Optionally, if you use ``--copy-crypt-key`` you can also keep the same crypt_key
-(used for authenticated encryption). Might be desired e.g. if you want to have less
+(used for authenticated encryption). This might be desired, for example, if you want to have fewer
keys to manage.
-Creating related repositories is useful e.g. if you want to use ``borg transfer`` later.
+Creating related repositories is useful, for example, if you want to use ``borg transfer`` later.
-Creating a related repository for data migration from borg 1.2 or 1.4
+Creating a related repository for data migration from Borg 1.2 or 1.4
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
You can use ``borg repo-create --other-repo ORIG_REPO --from-borg1 ...`` to create a related
diff --git a/docs/usage/repo-delete.rst.inc b/docs/usage/repo-delete.rst.inc
index f27afbeae2..0dc3a890df 100644
--- a/docs/usage/repo-delete.rst.inc
+++ b/docs/usage/repo-delete.rst.inc
@@ -12,23 +12,23 @@ borg repo-delete
.. class:: borg-options-table
- +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
- | **options** |
- +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
- | | ``-n``, ``--dry-run`` | do not change repository |
- +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
- | | ``--list`` | output verbose list of archives |
- +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
- | | ``--force`` | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. |
- +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
- | | ``--cache-only`` | delete only the local cache for the given repository |
- +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
- | | ``--keep-security-info`` | keep the local security info when deleting a repository |
- +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
- | .. class:: borg-common-opt-ref |
- | |
- | :ref:`common_options` |
- +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
+ +-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
+ | **options** |
+ +-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
+ | | ``-n``, ``--dry-run`` | do not change the repository |
+ +-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
+ | | ``--list`` | output a verbose list of archives |
+ +-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
+ | | ``--force`` | force deletion of corrupted archives; use ``--force --force`` if a single ``--force`` does not work. |
+ +-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
+ | | ``--cache-only`` | delete only the local cache for the given repository |
+ +-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
+ | | ``--keep-security-info`` | keep the local security info when deleting a repository |
+ +-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
+ | .. class:: borg-common-opt-ref |
+ | |
+ | :ref:`common_options` |
+ +-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -43,9 +43,9 @@ borg repo-delete
options
- -n, --dry-run do not change repository
- --list output verbose list of archives
- --force force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
+ -n, --dry-run do not change the repository
+ --list output a verbose list of archives
+ --force force deletion of corrupted archives; use ``--force --force`` if a single ``--force`` does not work.
--cache-only delete only the local cache for the given repository
--keep-security-info keep the local security info when deleting a repository
@@ -56,7 +56,7 @@ borg repo-delete
Description
~~~~~~~~~~~
-This command deletes the complete repository.
+This command deletes a complete repository.
When you delete a complete repository, the security info and local cache for it
(if any) are also deleted. Alternatively, you can delete just the local cache
diff --git a/docs/usage/repo-list.rst.inc b/docs/usage/repo-list.rst.inc
index 778980b4e9..15633512f6 100644
--- a/docs/usage/repo-list.rst.inc
+++ b/docs/usage/repo-list.rst.inc
@@ -27,21 +27,21 @@ borg repo-list
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. see "borg help match-archives". |
+ | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--first N`` | consider first N archives after other filters were applied |
+ | | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--last N`` | consider last N archives after other filters were applied |
+ | | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+ | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+ | | ``--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. |
+ | | ``--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. |
+ | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--deleted`` | consider only soft-deleted archives. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -68,14 +68,14 @@ borg repo-list
|
Archive filters
- -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. see "borg help match-archives".
+ -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. See "borg help match-archives".
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
- --first N consider first N archives after other filters were applied
- --last N consider last N archives after other filters were applied
- --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
- --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.
+ --first N consider the first N archives after other filters are applied
+ --last N consider the last N archives after other filters are applied
+ --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
+ --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.
--deleted consider only soft-deleted archives.
@@ -89,8 +89,8 @@ This command lists the archives contained in a repository.
The FORMAT specifier syntax
+++++++++++++++++++++++++++
-The ``--format`` option uses python's `format string syntax
-`_.
+The ``--format`` option uses Python's `format string syntax
+`_.
Examples:
::
diff --git a/docs/usage/repo-space.rst.inc b/docs/usage/repo-space.rst.inc
index 836442cb39..002f8a0ba6 100644
--- a/docs/usage/repo-space.rst.inc
+++ b/docs/usage/repo-space.rst.inc
@@ -12,17 +12,17 @@ borg repo-space
.. class:: borg-options-table
- +-------------------------------------------------------+---------------------+---------------------------------------------------------------------+
- | **options** |
- +-------------------------------------------------------+---------------------+---------------------------------------------------------------------+
- | | ``--reserve SPACE`` | Amount of space to reserve (e.g. 100M, 1G). Default: 0. |
- +-------------------------------------------------------+---------------------+---------------------------------------------------------------------+
- | | ``--free`` | Free all reserved space. Don't forget to reserve space later again. |
- +-------------------------------------------------------+---------------------+---------------------------------------------------------------------+
- | .. class:: borg-common-opt-ref |
- | |
- | :ref:`common_options` |
- +-------------------------------------------------------+---------------------+---------------------------------------------------------------------+
+ +-------------------------------------------------------+---------------------+----------------------------------------------------------------------+
+ | **options** |
+ +-------------------------------------------------------+---------------------+----------------------------------------------------------------------+
+ | | ``--reserve SPACE`` | Amount of space to reserve (e.g. 100M, 1G). Default: 0. |
+ +-------------------------------------------------------+---------------------+----------------------------------------------------------------------+
+ | | ``--free`` | Free all reserved space. Do not forget to reserve space again later. |
+ +-------------------------------------------------------+---------------------+----------------------------------------------------------------------+
+ | .. class:: borg-common-opt-ref |
+ | |
+ | :ref:`common_options` |
+ +-------------------------------------------------------+---------------------+----------------------------------------------------------------------+
.. raw:: html
@@ -38,7 +38,7 @@ borg repo-space
options
--reserve SPACE Amount of space to reserve (e.g. 100M, 1G). Default: 0.
- --free Free all reserved space. Don't forget to reserve space later again.
+ --free Free all reserved space. Do not forget to reserve space again later.
:ref:`common_options`
@@ -49,24 +49,23 @@ Description
This command manages reserved space in a repository.
-Borg can not work in disk-full conditions (can not lock a repo and thus can
-not run prune/delete or compact operations to free disk space).
+Borg cannot work in disk-full conditions (it cannot lock a repository and thus cannot
+run prune/delete or compact operations to free disk space).
-To avoid running into dead-end situations like that, you can put some objects
-into a repository that take up some disk space. If you ever run into a
-disk-full situation, you can free that space and then borg will be able to
-run normally, so you can free more disk space by using prune/delete/compact.
-After that, don't forget to reserve space again, in case you run into that
-situation again at a later time.
+To avoid running into such dead-end situations, you can put some objects into a
+repository that take up disk space. If you ever run into a disk-full situation, you
+can free that space, and then Borg will be able to run normally so you can free more
+disk space by using ``borg prune``/``borg delete``/``borg compact``. After that, do
+not forget to reserve space again, in case you run into that situation again later.
Examples::
# Create a new repository:
$ borg repo-create ...
- # Reserve approx. 1GB of space for emergencies:
+ # Reserve approx. 1 GiB of space for emergencies:
$ borg repo-space --reserve 1G
- # Check amount of reserved space in the repository:
+ # Check the amount of reserved space in the repository:
$ borg repo-space
# EMERGENCY! Free all reserved space to get things back to normal:
@@ -77,4 +76,4 @@ Examples::
$ borg repo-space --reserve 1G # reserve space again for next time
-Reserved space is always rounded up to use full reservation blocks of 64MiB.
\ No newline at end of file
+Reserved space is always rounded up to full reservation blocks of 64 MiB.
\ No newline at end of file
diff --git a/docs/usage/serve.rst.inc b/docs/usage/serve.rst.inc
index eadc7f32f1..1a8b7384d3 100644
--- a/docs/usage/serve.rst.inc
+++ b/docs/usage/serve.rst.inc
@@ -12,19 +12,19 @@ borg serve
.. class:: borg-options-table
- +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | **options** |
- +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--restrict-to-path PATH`` | restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to point directly to a repository. |
- +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--restrict-to-repository PATH`` | restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to point directly at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. |
- +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--permissions`` | Set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable. |
- +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | .. class:: borg-common-opt-ref |
- | |
- | :ref:`common_options` |
- +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ +-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | **options** |
+ +-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | | ``--restrict-to-path PATH`` | Restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all subdirectories is granted implicitly; PATH does not need to point directly to a repository. |
+ +-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | | ``--restrict-to-repository PATH`` | Restrict repository access. Only the repository located at PATH (no subdirectories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path``, subdirectories are not accessible; PATH must point directly to a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. |
+ +-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | | ``--permissions`` | Set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable. |
+ +-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | .. class:: borg-common-opt-ref |
+ | |
+ | :ref:`common_options` |
+ +-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -39,8 +39,8 @@ borg serve
options
- --restrict-to-path PATH restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to point directly to a repository.
- --restrict-to-repository PATH restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to point directly at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
+ --restrict-to-path PATH Restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all subdirectories is granted implicitly; PATH does not need to point directly to a repository.
+ --restrict-to-repository PATH Restrict repository access. Only the repository located at PATH (no subdirectories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path``, subdirectories are not accessible; PATH must point directly to a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
--permissions Set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable.
@@ -52,28 +52,28 @@ Description
This command starts a repository server process.
-borg serve can currently support:
+`borg serve` currently supports:
-- Getting automatically started via ssh when the borg client uses a ssh://...
- remote repository. In this mode, `borg serve` will live until that ssh connection
- gets terminated.
+- Being automatically started via SSH when the borg client uses an ssh://...
+ remote repository. In this mode, `borg serve` will run until that SSH connection
+ is terminated.
-- Getting started by some other means (not by the borg client) as a long-running socket
+- Being started by some other means (not by the borg client) as a long-running socket
server to be used for borg clients using a socket://... repository (see the `--socket`
- option if you do not want to use the default path for the socket and pid file).
-
-Please note that `borg serve` does not support giving a specific repository via the
-`--repo` option or `BORG_REPO` environment variable. It is always the borg client which
-specifies the repo to use when talking to `borg serve`.
-
-The --permissions option allows enforcing repository permissions:
-
-- `all`: All permissions are granted (default, permissions system is not used)
-- `no-delete`: Allow reading and writing, disallow deleting and overwriting data.
- New archives can be created, existing archives can not be deleted. New chunks can
- be added, existing chunks can not be deleted or overwritten.
-- `write-only`: Allow writing, disallow reading data.
- New archives can be created, existing archives can not be read.
- New chunks can be added, existing chunks can not be read, deleted or overwritten.
-- `read-only`: Allow reading, disallow writing or deleting data.
+ option if you do not want to use the default path for the socket and PID file).
+
+Please note that `borg serve` does not support providing a specific repository via the
+`--repo` option or the `BORG_REPO` environment variable. It is always the borg client that
+specifies the repository to use when communicating with `borg serve`.
+
+The --permissions option enforces repository permissions:
+
+- `all`: All permissions are granted. (Default; the permissions system is not used.)
+- `no-delete`: Allow reading and writing; disallow deleting and overwriting data.
+ New archives can be created; existing archives cannot be deleted. New chunks can
+ be added; existing chunks cannot be deleted or overwritten.
+- `write-only`: Allow writing; disallow reading data.
+ New archives can be created; existing archives cannot be read.
+ New chunks can be added; existing chunks cannot be read, deleted, or overwritten.
+- `read-only`: Allow reading; disallow writing or deleting data.
Existing archives can be read, but no archives can be created or deleted.
\ No newline at end of file
diff --git a/docs/usage/tag.rst.inc b/docs/usage/tag.rst.inc
index a95e5a6893..3e7a244e5c 100644
--- a/docs/usage/tag.rst.inc
+++ b/docs/usage/tag.rst.inc
@@ -31,21 +31,21 @@ borg tag
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. see "borg help match-archives". |
+ | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--first N`` | consider first N archives after other filters were applied |
+ | | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--last N`` | consider last N archives after other filters were applied |
+ | | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+ | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+ | | ``--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. |
+ | | ``--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. |
+ | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -72,14 +72,14 @@ borg tag
|
Archive filters
- -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. see "borg help match-archives".
+ -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. See "borg help match-archives".
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
- --first N consider first N archives after other filters were applied
- --last N consider last N archives after other filters were applied
- --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
- --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.
+ --first N consider the first N archives after other filters are applied
+ --last N consider the last N archives after other filters are applied
+ --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
+ --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.
Description
@@ -92,11 +92,11 @@ Borg archives can have a set of tags which can be used for matching archives.
You can set the tags to a specific set of tags or you can add or remove
tags from the current set of tags.
-User defined tags must not start with `@` because such tags are considered
+User-defined tags must not start with `@` because such tags are considered
special and users are only allowed to use known special tags:
``@PROT``: protects archives against archive deletion or pruning.
-Pre-existing special tags can not be removed via ``--set``. You can still use
-``--set``, but you must give pre-existing special tags also (so they won't be
+Pre-existing special tags cannot be removed via ``--set``. You can still use
+``--set``, but you must also give pre-existing special tags (so they won't be
removed).
\ No newline at end of file
diff --git a/docs/usage/transfer.rst.inc b/docs/usage/transfer.rst.inc
index 21720988e3..9f684ab495 100644
--- a/docs/usage/transfer.rst.inc
+++ b/docs/usage/transfer.rst.inc
@@ -35,21 +35,21 @@ borg transfer
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. see "borg help match-archives". |
+ | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--first N`` | consider first N archives after other filters were applied |
+ | | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--last N`` | consider last N archives after other filters were applied |
+ | | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+ | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+ | | ``--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. |
+ | | ``--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. |
+ | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -78,14 +78,14 @@ borg transfer
|
Archive filters
- -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. see "borg help match-archives".
+ -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. See "borg help match-archives".
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
- --first N consider first N archives after other filters were applied
- --last N consider last N archives after other filters were applied
- --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
- --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.
+ --first N consider the first N archives after other filters are applied
+ --last N consider the last N archives after other filters are applied
+ --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
+ --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.
Description
diff --git a/docs/usage/umount.rst.inc b/docs/usage/umount.rst.inc
index 151d76a804..4fece9a0be 100644
--- a/docs/usage/umount.rst.inc
+++ b/docs/usage/umount.rst.inc
@@ -12,15 +12,15 @@ borg umount
.. class:: borg-options-table
- +-------------------------------------------------------+----------------+----------------------------------------+
- | **positional arguments** |
- +-------------------------------------------------------+----------------+----------------------------------------+
- | | ``MOUNTPOINT`` | mountpoint of the filesystem to umount |
- +-------------------------------------------------------+----------------+----------------------------------------+
- | .. class:: borg-common-opt-ref |
- | |
- | :ref:`common_options` |
- +-------------------------------------------------------+----------------+----------------------------------------+
+ +-------------------------------------------------------+----------------+-----------------------------------------+
+ | **positional arguments** |
+ +-------------------------------------------------------+----------------+-----------------------------------------+
+ | | ``MOUNTPOINT`` | mountpoint of the filesystem to unmount |
+ +-------------------------------------------------------+----------------+-----------------------------------------+
+ | .. class:: borg-common-opt-ref |
+ | |
+ | :ref:`common_options` |
+ +-------------------------------------------------------+----------------+-----------------------------------------+
.. raw:: html
@@ -33,7 +33,7 @@ borg umount
.. only:: latex
MOUNTPOINT
- mountpoint of the filesystem to umount
+ mountpoint of the filesystem to unmount
:ref:`common_options`
@@ -42,7 +42,7 @@ borg umount
Description
~~~~~~~~~~~
-This command un-mounts a FUSE filesystem that was mounted with ``borg mount``.
+This command unmounts a FUSE filesystem that was mounted with ``borg mount``.
This is a convenience wrapper that just calls the platform-specific shell
command - usually this is either umount or fusermount -u.
\ No newline at end of file
diff --git a/docs/usage/undelete.rst.inc b/docs/usage/undelete.rst.inc
index 5024edacb2..acd7eb4144 100644
--- a/docs/usage/undelete.rst.inc
+++ b/docs/usage/undelete.rst.inc
@@ -19,9 +19,9 @@ borg undelete
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``-n``, ``--dry-run`` | do not change repository |
+ | | ``-n``, ``--dry-run`` | do not change the repository |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--list`` | output verbose list of archives |
+ | | ``--list`` | output a verbose list of archives |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
@@ -29,21 +29,21 @@ borg undelete
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. see "borg help match-archives". |
+ | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--first N`` | consider first N archives after other filters were applied |
+ | | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--last N`` | consider last N archives after other filters were applied |
+ | | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+ | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
- | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+ | | ``--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. |
+ | | ``--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. |
+ | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -61,22 +61,22 @@ borg undelete
options
- -n, --dry-run do not change repository
- --list output verbose list of archives
+ -n, --dry-run do not change the repository
+ --list output a verbose list of archives
:ref:`common_options`
|
Archive filters
- -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. see "borg help match-archives".
+ -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. See "borg help match-archives".
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
- --first N consider first N archives after other filters were applied
- --last N consider last N archives after other filters were applied
- --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
- --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.
+ --first N consider the first N archives after other filters are applied
+ --last N consider the last N archives after other filters are applied
+ --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
+ --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.
Description
@@ -86,11 +86,12 @@ This command undeletes archives in the repository.
Important: Undeleting archives is only possible before compacting.
Once ``borg compact`` has run, all disk space occupied only by the
-soft-deleted archives will be freed and undelete is not possible
-anymore.
+soft-deleted archives will be freed, and undeleting is no longer
+possible.
-When in doubt, use ``--dry-run --list`` to see what would be undeleted.
+When in doubt, use ``--dry-run --list`` to see what would be
+undeleted.
-You can undelete multiple archives by specifying a matching pattern,
-using the ``--match-archives PATTERN`` option (for more info on these patterns,
-see :ref:`borg_patterns`).
\ No newline at end of file
+You can undelete multiple archives by specifying a match pattern using
+the ``--match-archives PATTERN`` option (for more information on these
+patterns, see :ref:`borg_patterns`).
\ No newline at end of file
diff --git a/docs/usage/version.rst.inc b/docs/usage/version.rst.inc
index 1964ebc1e0..2d5a9c22ed 100644
--- a/docs/usage/version.rst.inc
+++ b/docs/usage/version.rst.inc
@@ -36,25 +36,25 @@ borg version
Description
~~~~~~~~~~~
-This command displays the borg client version / borg server version.
+This command displays the Borg client and server versions.
-If a local repo is given, the client code directly accesses the repository,
-thus we show the client version also as the server version.
+If a local repository is given, the client code directly accesses the repository,
+so the client version is also shown as the server version.
-If a remote repo is given (e.g. ssh:), the remote borg is queried and
+If a remote repository is given (e.g., ssh:), the remote Borg is queried, and
its version is displayed as the server version.
Examples::
- # local repo (client uses 1.4.0 alpha version)
+ # local repository (client uses 1.4.0 alpha version)
$ borg version /mnt/backup
1.4.0a / 1.4.0a
- # remote repo (client uses 1.4.0 alpha, server uses 1.2.7 release)
+ # remote repository (client uses 1.4.0 alpha, server uses 1.2.7 release)
$ borg version ssh://borg@borgbackup:repo
1.4.0a / 1.2.7
-Due to the version tuple format used in borg client/server negotiation, only
+Due to the version tuple format used in Borg client/server negotiation, only
a simplified version is displayed (as provided by borg.version.format_version).
-There is also borg --version to display a potentially more precise client version.
\ No newline at end of file
+You can also use ``borg --version`` to display a potentially more precise client version.
\ No newline at end of file
diff --git a/docs/usage/with-lock.rst.inc b/docs/usage/with-lock.rst.inc
index d7a2b39b8c..8e8db70bbd 100644
--- a/docs/usage/with-lock.rst.inc
+++ b/docs/usage/with-lock.rst.inc
@@ -52,14 +52,14 @@ This command runs a user-specified command while locking the repository. For exa
$ BORG_REPO=/mnt/borgrepo borg with-lock rsync -av /mnt/borgrepo /somewhere/else/borgrepo
-It will first try to acquire the lock (make sure that no other operation is
-running in the repo), then execute the given command as a subprocess and wait
-for its termination, release the lock and return the user command's return
-code as borg's return code.
+It first tries to acquire the lock (make sure that no other operation is
+running in the repository), then executes the given command as a subprocess and waits
+for its termination, releases the lock, and returns the user command's return
+code as Borg's return code.
.. note::
If you copy a repository with the lock held, the lock will be present in
- the copy. Thus, before using borg on the copy from a different host,
- you need to use "borg break-lock" on the copied repository, because
+ the copy. Before using Borg on the copy from a different host,
+ you need to run ``borg break-lock`` on the copied repository, because
Borg is cautious and does not automatically remove stale locks made by a different host.
\ No newline at end of file
diff --git a/requirements.d/pyinstaller.txt b/requirements.d/pyinstaller.txt
new file mode 100644
index 0000000000..132be3872e
--- /dev/null
+++ b/requirements.d/pyinstaller.txt
@@ -0,0 +1 @@
+pyinstaller==6.14.2
diff --git a/src/borg/platform/__init__.py b/src/borg/platform/__init__.py
index e0491101b7..6954178ffa 100644
--- a/src/borg/platform/__init__.py
+++ b/src/borg/platform/__init__.py
@@ -12,6 +12,9 @@
from .base import SaveFile, sync_dir, fdatasync, safe_fadvise
from .base import get_process_id, fqdn, hostname, hostid
+# work around pyinstaller "forgetting" to include the xattr module
+from . import xattr # noqa: F401
+
platform_ug: ModuleType | None = None # make mypy happy
if is_linux: # pragma: linux only