update CHANGES

docs: move RTD version selector to sidebar top-left, fixes #8204

.appveyor.yml

@@ -1,27 +0,0 @@
-version: '{build}'
-
-environment:
-  matrix:
-    - PYTHON: C:\Python38-x64
-
-# Disable automatic builds
-build: off
-
-# Build artifacts: all wheel and exe files in the dist folder
-artifacts:
-  - path: 'dist\*.whl'
-  - path: 'dist\*.exe'
-
-install:
-- ps: scripts\win-download-openssl.ps1
-- ps: |
-    & $env:PYTHON\python.exe -m venv borg-env
-    borg-env\Scripts\activate.ps1
-    python -m pip install -U pip
-    pip install -r requirements.d/development.txt
-    pip install wheel pyinstaller
-
-build_script:
-- ps: |
-    borg-env\Scripts\activate.ps1
-    scripts\win-build.ps1

.coafile

@@ -1,41 +0,0 @@
-[all]
-# note: put developer specific settings into ~/.coarc (e.g. editor = ...)
-max_line_length = 255
-use_spaces = True
-ignore = src/borg/(chunker.c|compress.c|hashindex.c|item.c),
-         src/borg/algorithms/(checksums.c|crc32*.c),
-         src/borg/algorithms/blake2/**,
-         src/borg/algorithms/lz4/**,
-         src/borg/algorithms/xxh64/**,
-         src/borg/algorithms/zstd/**,
-         src/borg/crypto/low_level.c,
-         src/borg/platform/*.c
-
-[all.general]
-files = src/borg/**/*.(py|pyx|c)
-bears = SpaceConsistencyBear, FilenameBear, InvalidLinkBear, LineLengthBear
-file_naming_convention = snake
-
-[all.python]
-files = src/borg/**/*.py
-bears = PEP8Bear, PyDocStyleBear, PyLintBear
-pep_ignore = E123,E125,E126,E127,E128,E226,E301,E309,E402,F401,F405,F811,W690
-pylint_disable = C0103, C0111, C0112, C0122, C0123, C0301, C0302, C0325, C0330, C0411, C0412, C0413, C1801,
-                 I1101,
-                 W0102, W0104, W0106, W0108, W0120, W0201, W0212, W0221, W0231, W0401, W0404,
-                 W0511, W0603, W0611, W0612, W0613, W0614, W0621, W0622, W0640, W0702, W0703,
-                 W1201, W1202, W1401,
-                 R0101, R0201, R0204, R0901, R0902, R0903, R0904, R0911, R0912, R0913, R0914, R0915,
-                 R0916, R1701, R1704, R1705, R1706, R1710,
-                 E0102, E0202, E0401, E0601, E0611, E0702, E1101, E1102, E1120, E1129, E1130
-pydocstyle_ignore = D100, D101, D102, D103, D104, D105, D200, D201, D202, D203, D204, D205, D209, D210,
-                    D212, D213, D300, D301, D400, D401, D402, D403, D404
-
-[all.c]
-files = src/borg/**/*.c
-bears = CPPCheckBear
-
-[all.html]
-files = src/borg/**/*.html
-bears = HTMLLintBear
-htmllint_ignore = *

.coveragerc

@@ -1,24 +0,0 @@
-[run]
-branch = True
-disable_warnings = module-not-measured
-source = src/borg
-omit =
-    */borg/__init__.py
-    */borg/__main__.py
-    */borg/_version.py
-    */borg/fuse.py
-    */borg/support/*
-    */borg/testsuite/*
-    */borg/hash_sizes.py
-
-[report]
-exclude_lines =
-    pragma: no cover
-    pragma: freebsd only
-    pragma: unknown platform only
-    def __repr__
-    raise AssertionError
-    raise NotImplementedError
-    if 0:
-    if __name__ == .__main__.:
-ignore_errors = True

.github/ISSUE_TEMPLATE.md

@@ -1,56 +1,55 @@
 <!--
 Thank you for reporting an issue.
 
-*IMPORTANT* -  *before* creating a new issue please look around:
+*IMPORTANT* – before creating a new issue, please look around:
- - Borgbackup documentation: http://borgbackup.readthedocs.io/en/stable/index.html
+ - BorgBackup documentation: https://borgbackup.readthedocs.io/en/stable/index.html
  - FAQ: https://borgbackup.readthedocs.io/en/stable/faq.html
  and
- - open issues in Github tracker: https://github.com/borgbackup/borg/issues
+ - Open issues in the GitHub tracker: https://github.com/borgbackup/borg/issues
-  
+
 If you cannot find a similar problem, then create a new issue.
 
 Please fill in as much of the template as possible.
 -->
 
-## Have you checked borgbackup docs, FAQ, and open Github issues?
+## Have you checked the BorgBackup docs, FAQ, and open GitHub issues?
 
 No
 
-## Is this a BUG / ISSUE report or a QUESTION?
+## Is this a bug/issue report or a question?
 
-Invalid
+Bug/Issue/Question
 
-## System information. For client/server mode post info for both machines.
+## System information. For client/server mode, post info for both machines.
 
 #### Your borg version (borg -V).
 
 #### Operating system (distribution) and version.
 
-#### Hardware / network configuration, and filesystems used.
+#### Hardware/network configuration and filesystems used.
 
 #### How much data is handled by borg?
 
-#### Full borg commandline that lead to the problem (leave away excludes and passwords)
+#### Full borg command line that led to the problem (leave out excludes and passwords).
 
 
 ## Describe the problem you're observing.
 
 #### Can you reproduce the problem? If so, describe how. If not, describe troubleshooting steps you took before opening the issue.
 
-#### Include any warning/errors/backtraces from the system logs
+#### Include any warnings/errors/backtraces from the system logs
 
 <!--
 
 If this complaint relates to borg performance, please include CRUD benchmark
 results and any steps you took to troubleshoot.
-How to run benchmark: http://borgbackup.readthedocs.io/en/stable/usage/benchmark.html
+How to run the benchmark: https://borgbackup.readthedocs.io/en/stable/usage/benchmark.html
 
-*IMPORTANT* - Please mark logs and text output from terminal commands 
+*IMPORTANT* – Please mark logs and terminal command output, otherwise GitHub will not display them correctly.
-or else Github will not display them correctly. 
 An example is provided below.
 
 Example:
 ```
-this is an example how log text should be marked (wrap it with ```)
+this is an example of how log text should be marked (wrap it with ```)
 ```
 -->

.github/PULL_REQUEST_TEMPLATE

@@ -1,8 +0,0 @@
-Thank you for contributing code to Borg, your help is appreciated!
-
-Please, before you submit a pull request, make sure it complies with the
-guidelines given in our documentation:
-
-https://borgbackup.readthedocs.io/en/latest/development.html#contributions
-
-**Please remove all above text before submitting your pull request.**

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+<!--
+Thank you for contributing to BorgBackup!
+
+Please make sure your PR complies with our contribution guidelines:
+https://borgbackup.readthedocs.io/en/latest/development.html#contributions
+-->
+
+## Description
+
+<!-- What does this PR do? Reference any related issues with "fixes #XXXX". -->
+
+
+## Checklist
+
+- [ ] PR is against `master` (or maintenance branch if only applicable there)
+- [ ] New code has tests and docs where appropriate
+- [ ] Tests pass (run `tox` or the relevant test subset)
+- [ ] Commit messages are clean and reference related issues

.github/workflows/ci.yml

@@ -1,28 +1,32 @@
-# badge: https://github.com/borgbackup/borg/workflows/CI/badge.svg?branch=master
+# badge: https://github.com/borgbackup/borg/workflows/CI/badge.svg?branch=1.4-maint
 
 name: CI
 
 on:
   push:
-    branches: [ master ]
+    branches: [ 1.4-maint ]
+    tags:
+    - '1.*'
     paths:
     - '**.py'
     - '**.pyx'
     - '**.c'
     - '**.h'
     - '**.yml'
+    - '**.toml'
     - '**.cfg'
     - '**.ini'
     - 'requirements.d/*'
     - '!docs/**'
   pull_request:
-    branches: [ master ]
+    branches: [ 1.4-maint ]
     paths:
     - '**.py'
     - '**.pyx'
     - '**.c'
     - '**.h'
     - '**.yml'
+    - '**.toml'
     - '**.cfg'
     - '**.ini'
     - 'requirements.d/*'
@@ -31,58 +35,136 @@ on:
 jobs:
   lint:
 
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
-    timeout-minutes: 10
+    timeout-minutes: 5
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
-    - name: Set up Python
+    - uses: chartboost/ruff-action@v1
-      uses: actions/setup-python@v2
+
+
+  asan_ubsan:
+
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    needs: [lint]
+
+    steps:
+    - uses: actions/checkout@v4
       with:
-        python-version: 3.8
+        # Just fetching one commit is not enough for setuptools-scm, so we fetch all.
-    - name: Lint with flake8
+        fetch-depth: 0
+        fetch-tags: true
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install system packages
       run: |
-        pip install flake8
+        sudo apt-get update
-        flake8 src scripts conftest.py
+        sudo apt-get install -y pkg-config build-essential
+        sudo apt-get install -y libssl-dev libacl1-dev libxxhash-dev liblz4-dev libzstd-dev
 
-  pytest:
+    - name: Install Python dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.d/development.txt
 
-    needs: lint
+    - name: Build Borg with ASan/UBSan
+      # Build the C/Cython extensions with AddressSanitizer and UndefinedBehaviorSanitizer enabled.
+      # How this works:
+      # - The -fsanitize=address,undefined flags inject runtime checks into our native code. If a bug is hit
+      #   (e.g., buffer overflow, use-after-free, out-of-bounds, or undefined behavior), the sanitizer prints
+      #   a detailed error report to stderr, including a stack trace, and forces the process to exit with
+      #   non-zero status. In CI, this will fail the step/job so you will notice.
+      # - ASAN_OPTIONS/UBSAN_OPTIONS configure the sanitizers' runtime behavior (see below for meanings).
+      env:
+        CFLAGS: "-O1 -g -fno-omit-frame-pointer -fsanitize=address,undefined"
+        CXXFLAGS: "-O1 -g -fno-omit-frame-pointer -fsanitize=address,undefined"
+        LDFLAGS: "-fsanitize=address,undefined"
+        # ASAN_OPTIONS controls AddressSanitizer runtime tweaks:
+        # - detect_leaks=0: Disable LeakSanitizer to avoid false positives with CPython/pymalloc in short-lived tests.
+        # - strict_string_checks=1: Make invalid string operations (e.g., over-reads) more likely to be detected.
+        # - check_initialization_order=1: Catch uses that depend on static initialization order (C++).
+        # - detect_stack_use_after_return=1: Detect stack-use-after-return via stack poisoning (may increase overhead).
+        ASAN_OPTIONS: "detect_leaks=0:strict_string_checks=1:check_initialization_order=1:detect_stack_use_after_return=1"
+        # UBSAN_OPTIONS controls UndefinedBehaviorSanitizer runtime:
+        # - print_stacktrace=1: Include a stack trace for UB reports to ease debugging.
+        #   Note: UBSan is recoverable by default (process may continue after reporting). If you want CI to
+        #   abort immediately and fail on the first UB, add `halt_on_error=1` (e.g., UBSAN_OPTIONS="print_stacktrace=1:halt_on_error=1").
+        UBSAN_OPTIONS: "print_stacktrace=1"
+        # PYTHONDEVMODE enables additional Python runtime checks and warnings.
+        PYTHONDEVMODE: "1"
+      run: pip install -e .
+
+    - name: Run tests under sanitizers
+      env:
+        ASAN_OPTIONS: "detect_leaks=0:strict_string_checks=1:check_initialization_order=1:detect_stack_use_after_return=1"
+        UBSAN_OPTIONS: "print_stacktrace=1"
+        PYTHONDEVMODE: "1"
+      # Ensure the ASan runtime is loaded first to avoid "ASan runtime does not come first" warnings.
+      # We discover libasan/libubsan paths via gcc and preload them for the Python test process.
+      # the remote tests are slow and likely won't find anything useful
+      run: |
+        set -euo pipefail
+        export LD_PRELOAD="$(gcc -print-file-name=libasan.so):$(gcc -print-file-name=libubsan.so)"
+        echo "Using LD_PRELOAD=$LD_PRELOAD"
+        pytest -v --benchmark-skip -k "not remote"
+
+  native_tests:
+
+    needs: [lint]
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
     strategy:
-      matrix:
+      fail-fast: false
-        include:
+      # noinspection YAMLSchemaValidation
-            - os: ubuntu-20.04
+      matrix: >-
-              python-version: '3.8'
+        ${{ fromJSON(
-              toxenv: py38-fuse2
+          github.event_name == 'pull_request' && '{
-            - os: ubuntu-20.04
+            "include": [
-              python-version: '3.9'
+              {"os": "ubuntu-22.04", "python-version": "3.10", "toxenv": "py310-fuse2"},
-              toxenv: py39-fuse3
+              {"os": "ubuntu-24.04", "python-version": "3.14", "toxenv": "py314-fuse3"}
-            - os: ubuntu-20.04
+            ]
-              python-version: '3.10'
+          }' || '{
-              toxenv: py310-fuse3
+            "include": [
-            - os: macos-10.15  # macos-latest is macos 11.6.2 and hanging at test_fuse, #6099
+              {"os": "ubuntu-22.04", "python-version": "3.10", "toxenv": "py310-fuse2"},
-              python-version: '3.8'
+              {"os": "ubuntu-22.04", "python-version": "3.11", "toxenv": "py311-fuse3", "binary": "borg-linux-glibc235-x86_64-gh"},
-              toxenv: py38-fuse2
+              {"os": "ubuntu-22.04-arm", "python-version": "3.11", "toxenv": "py311-fuse3", "binary": "borg-linux-glibc235-arm64-gh"},
+              {"os": "ubuntu-24.04", "python-version": "3.12", "toxenv": "py312-fuse3"},
+              {"os": "ubuntu-24.04", "python-version": "3.13", "toxenv": "py313-fuse3"},
+              {"os": "ubuntu-24.04", "python-version": "3.14", "toxenv": "py314-fuse3"},
+              {"os": "macos-15-intel", "python-version": "3.11", "toxenv": "py311-none", "binary": "borg-macos-15-x86_64-gh"},
+              {"os": "macos-15", "python-version": "3.11", "toxenv": "py311-none", "binary": "borg-macos-15-arm64-gh"}
+            ]
+          }'
+        ) }}
 
     env:
-      # Configure pkg-config to use OpenSSL from Homebrew
-      PKG_CONFIG_PATH: /usr/local/opt/openssl@1.1/lib/pkgconfig
       TOXENV: ${{ matrix.toxenv }}
 
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 40
+    # macOS machines can be slow, if overloaded.
+    timeout-minutes: 360
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
       with:
-        # just fetching 1 commit is not enough for setuptools-scm, so we fetch all
+        # Just fetching one commit is not enough for setuptools-scm, so we fetch all
         fetch-depth: 0
+        fetch-tags: true
+
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
+
     - name: Cache pip
-      uses: actions/cache@v2
+      uses: actions/cache@v4
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip-${{ hashFiles('requirements.d/development.txt') }}
@@ -95,38 +177,286 @@ jobs:
       run: |
         sudo apt-get update
         sudo apt-get install -y libssl-dev libacl1-dev liblz4-dev libzstd-dev pkg-config build-essential
-        sudo apt-get install -y libxxhash-dev || true
+        sudo apt-get install -y libxxhash-dev
-        sudo apt-get install -y libb2-dev || true
+        if [[ "$TOXENV" == *"fuse2"* ]]; then
-        sudo apt-get install -y libfuse-dev fuse || true  # Required for Python llfuse module
+          sudo apt-get install -y libfuse-dev fuse  # Required for Python llfuse module
-        sudo apt-get install -y libfuse3-dev fuse3 || true  # Required for Python pyfuse3 module
+        elif [[ "$TOXENV" == *"fuse3"* ]]; then
+          sudo apt-get install -y libfuse3-dev fuse3  # Required for Python pyfuse3 module
+        fi
 
     - name: Install macOS packages
       if: ${{ runner.os == 'macOS' }}
-      run: |
+      run: brew bundle install
-        brew install pkg-config || brew upgrade pkg-config
-        brew install zstd || brew upgrade zstd
-        brew install lz4 || brew upgrade lz4
-        brew install openssl@1.1 || brew upgrade openssl@1.1
-        brew install --cask macfuse || brew upgrade --cask macfuse  # Required for Python llfuse module
 
     - name: Install Python requirements
       run: |
         python -m pip install --upgrade pip setuptools wheel
         pip install -r requirements.d/development.txt
-    - name: Install borgbackup
+
+    - name: Install BorgBackup
       run: |
-        # pip install -e .
+        if [[ "$TOXENV" == *"fuse2"* ]]; then
-        python setup.py -v develop
+          pip install -ve ".[llfuse]"
-    - name: run pytest via tox
+        elif [[ "$TOXENV" == *"fuse3"* ]]; then
+          pip install -ve ".[pyfuse3]"
+        else
+          pip install -ve .
+        fi
+
+    - name: Build Borg fat binaries (${{ matrix.binary }})
+      if: ${{ matrix.binary && startsWith(github.ref, 'refs/tags/') }}
       run: |
-        # do not use fakeroot, but run as root. avoids the dreaded EISDIR sporadic failures. see #2482.
+        pip install 'pyinstaller==6.14.2'
+        mkdir -p dist/binary
+        # Ensure locally built binaries in ./dist/binary are found during tox tests
+        echo "$GITHUB_WORKSPACE/dist/binary" >> "$GITHUB_PATH"
+        pyinstaller --clean --distpath=dist/binary scripts/borg.exe.spec
+
+    - name: Smoke-test the built binary (${{ matrix.binary }})
+      if: ${{ matrix.binary && startsWith(github.ref, 'refs/tags/') }}
+      run: |
+        pushd dist/binary
+        echo "single-file binary"
+        chmod +x borg.exe
+        ./borg.exe -V
+        echo "single-directory binary"
+        chmod +x borg-dir/borg.exe
+        ./borg-dir/borg.exe -V
+        tar czf borg.tgz borg-dir
+        popd
+        echo "borg.exe binary in PATH"
+        borg.exe -V
+
+    - name: Prepare binaries (${{ matrix.binary }})
+      if: ${{ matrix.binary && startsWith(github.ref, 'refs/tags/') }}
+      run: |
+        mkdir -p artifacts
+        if [ -f dist/binary/borg.exe ]; then
+          cp dist/binary/borg.exe artifacts/${{ matrix.binary }}
+        fi
+        if [ -f dist/binary/borg.tgz ]; then
+          cp dist/binary/borg.tgz artifacts/${{ matrix.binary }}.tgz
+        fi
+        echo "binary files"
+        ls -l artifacts/
+
+    - name: Attest binaries provenance (${{ matrix.binary }})
+      if: ${{ matrix.binary && startsWith(github.ref, 'refs/tags/') }}
+      uses: actions/attest-build-provenance@v3
+      with:
+        subject-path: 'artifacts/*'
+
+    - name: Upload binaries (${{ matrix.binary }})
+      if: ${{ matrix.binary && startsWith(github.ref, 'refs/tags/') }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ matrix.binary }}
+        path: artifacts/*
+        if-no-files-found: error
+
+    - name: Run pytest via tox
+      run: |
+        # Do not use fakeroot; run as root. Avoids the dreaded sporadic EISDIR failures; see #2482.
         #sudo -E bash -c "tox -e py"
         tox --skip-missing-interpreters
+
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v1
+      uses: codecov/codecov-action@v4
       env:
         OS: ${{ runner.os }}
         python: ${{ matrix.python-version }}
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
         env_vars: OS, python
+
+  vm_tests:
+
+    # Cross-OS tests running inside VMs, aligned with master branch structure.
+    # Uses cross-platform-actions/action to run on FreeBSD, NetBSD, OpenBSD, Haiku.
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    runs-on: ubuntu-24.04
+    timeout-minutes: 90
+    needs: [lint]
+    continue-on-error: true
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: freebsd
+            version: '14.3'
+            display_name: FreeBSD
+            # Controls binary build and provenance attestation on tags
+            do_binaries: true
+            artifact_prefix: borg-freebsd-14-x86_64-gh
+          - os: netbsd
+            version: '10.1'
+            display_name: NetBSD
+            do_binaries: false
+          - os: openbsd
+            version: '7.7'
+            display_name: OpenBSD
+            do_binaries: false
+          - os: haiku
+            version: 'r1beta5'
+            display_name: Haiku
+            do_binaries: false
+
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        fetch-tags: true
+
+    - name: Test on ${{ matrix.display_name }}
+      id: cross_os
+      uses: cross-platform-actions/action@v0.29.0
+      env:
+        DO_BINARIES: ${{ matrix.do_binaries }}
+      with:
+        operating_system: ${{ matrix.os }}
+        version: ${{ matrix.version }}
+        shell: bash
+        run: |
+          set -euxo pipefail
+          case "${{ matrix.os }}" in
+            freebsd)
+              # Ensure a proper hostname/FQDN is set (VMs may not have one by default)
+              sudo -E /bin/sh -c 'grep -q "freebsd\.local" /etc/hosts || echo "127.0.0.1 freebsd.local freebsd" >> /etc/hosts'
+              sudo -E hostname freebsd.local
+              hostname
+              export IGNORE_OSVERSION=yes
+              sudo -E pkg update -f
+              sudo -E pkg install -y xxhash liblz4 zstd pkgconf
+              sudo -E pkg install -y fusefs-libs
+              sudo -E kldload fusefs
+              sudo -E sysctl vfs.usermount=1
+              sudo -E chmod 666 /dev/fuse
+              sudo -E pkg install -y rust
+              sudo -E pkg install -y git
+              sudo -E pkg install -y python310 py310-sqlite3
+              sudo -E pkg install -y python311 py311-sqlite3 py311-pip py311-virtualenv
+              sudo ln -sf /usr/local/bin/python3.11 /usr/local/bin/python3
+              sudo ln -sf /usr/local/bin/python3.11 /usr/local/bin/python
+              sudo ln -sf /usr/local/bin/pip3.11 /usr/local/bin/pip3
+              sudo ln -sf /usr/local/bin/pip3.11 /usr/local/bin/pip
+              python -m venv .venv
+              . .venv/bin/activate
+              python -V
+              pip -V
+              python -m pip install --upgrade pip wheel
+              pip install -r requirements.d/development.txt
+              pip install -e ".[llfuse]"
+              if [[ "${{ matrix.do_binaries }}" == "true" && "${{ startsWith(github.ref, 'refs/tags/') }}" == "true" ]]; then
+                python -m pip install 'pyinstaller==6.14.2'
+                mkdir -p dist/binary
+                pyinstaller --clean --distpath=dist/binary scripts/borg.exe.spec
+                pushd dist/binary
+                echo "single-file binary"
+                chmod +x borg.exe
+                ./borg.exe -V
+                echo "single-directory binary"
+                chmod +x borg-dir/borg.exe
+                ./borg-dir/borg.exe -V
+                tar czf borg.tgz borg-dir
+                popd
+                mkdir -p artifacts
+                if [ -f dist/binary/borg.exe ]; then
+                  cp -v dist/binary/borg.exe artifacts/${{ matrix.artifact_prefix }}
+                fi
+                if [ -f dist/binary/borg.tgz ]; then
+                  cp -v dist/binary/borg.tgz artifacts/${{ matrix.artifact_prefix }}.tgz
+                fi
+                echo "binary files"
+                ls -l artifacts/
+              fi
+              export PATH="$(pwd)/dist/binary:$PATH"
+              tox -e py311-fuse2
+              ;;
+            netbsd)
+              # Ensure a proper hostname/FQDN is set (VMs may not have one by default)
+              sudo -E /bin/sh -c 'grep -q "netbsd\.local" /etc/hosts || echo "127.0.0.1 netbsd.local netbsd" >> /etc/hosts'
+              sudo -E hostname netbsd.local
+              hostname
+              arch="$(uname -m)"
+              sudo -E mkdir -p /usr/pkg/etc/pkgin
+              echo "http://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/${arch}/10.1/All" | sudo tee /usr/pkg/etc/pkgin/repositories.conf > /dev/null
+              sudo -E pkgin update
+              sudo -E pkgin -y upgrade
+              sudo -E pkgin -y install zstd lz4 xxhash git
+              sudo -E pkgin -y install rust
+              sudo -E pkgin -y install pkg-config
+              sudo -E pkgin -y install py311-pip py311-virtualenv py311-tox
+              sudo -E ln -sf /usr/pkg/bin/python3.11 /usr/pkg/bin/python3
+              sudo -E ln -sf /usr/pkg/bin/pip3.11 /usr/pkg/bin/pip3
+              sudo -E ln -sf /usr/pkg/bin/virtualenv-3.11 /usr/pkg/bin/virtualenv3
+              sudo -E ln -sf /usr/pkg/bin/tox-3.11 /usr/pkg/bin/tox3
+              # Ensure base system admin tools are on PATH for the non-root shell
+              export PATH="/sbin:/usr/sbin:$PATH"
+              echo "--- Preparing an extattr-enabled filesystem ---"
+              # On many NetBSD setups /tmp is tmpfs without extended attributes.
+              # Create a FFS image with extended attributes enabled and use it for TMPDIR.
+              VNDDEV="vnd0"
+              IMGFILE="/tmp/fs.img"
+              sudo -E dd if=/dev/zero of=${IMGFILE} bs=1m count=1024
+              sudo -E vndconfig -c "${VNDDEV}" "${IMGFILE}"
+              sudo -E newfs -O 2ea /dev/r${VNDDEV}a
+              MNT="/mnt/eafs"
+              sudo -E mkdir -p ${MNT}
+              sudo -E mount -t ffs -o extattr /dev/${VNDDEV}a $MNT
+              export TMPDIR="${MNT}/tmp"
+              sudo -E mkdir -p ${TMPDIR}
+              sudo -E chmod 1777 ${TMPDIR}
+              touch ${TMPDIR}/testfile
+              lsextattr user ${TMPDIR}/testfile && echo "[xattr] *** xattrs SUPPORTED on ${TMPDIR}! ***"
+              tox3 -e py311-none
+              ;;
+            openbsd)
+              sudo -E pkg_add xxhash lz4 zstd git
+              sudo -E pkg_add rust
+              sudo -E pkg_add openssl%3.4
+              sudo -E pkg_add py3-pip py3-virtualenv py3-tox
+              export BORG_OPENSSL_NAME=eopenssl34
+              tox -e py312-none
+              ;;
+            haiku)
+              pkgman refresh
+              pkgman install -y git pkgconfig zstd lz4 xxhash
+              pkgman install -y openssl3
+              pkgman install -y rust_bin
+              pkgman install -y python3.10
+              pkgman install -y cffi
+              pkgman install -y lz4_devel zstd_devel xxhash_devel openssl3_devel libffi_devel
+              # there is no pkgman package for tox, so we install it into a venv
+              python3 -m ensurepip --upgrade
+              python3 -m pip install --upgrade pip wheel
+              python3 -m venv .venv
+              . .venv/bin/activate
+              export PKG_CONFIG_PATH="/system/develop/lib/pkgconfig:/system/lib/pkgconfig:${PKG_CONFIG_PATH:-}"
+              export BORG_LIBLZ4_PREFIX=/system/develop
+              export BORG_LIBZSTD_PREFIX=/system/develop
+              export BORG_LIBXXHASH_PREFIX=/system/develop
+              export BORG_OPENSSL_PREFIX=/system/develop
+              pip install -r requirements.d/development.txt
+              pip install -e .
+              # troubles with either tox or pytest xdist, so we run pytest manually:
+              pytest -v -rs --benchmark-skip -k "not remote and not socket"
+              ;;
+          esac
+
+    - name: Upload artifacts
+      if: startsWith(github.ref, 'refs/tags/') && matrix.do_binaries
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ matrix.artifact_prefix }}
+        path: artifacts/*
+        if-no-files-found: ignore
+
+    - name: Attest provenance
+      if: startsWith(github.ref, 'refs/tags/') && matrix.do_binaries
+      uses: actions/attest-build-provenance@v3
+      with:
+        subject-path: 'artifacts/*'

.github/workflows/codeql-analysis.yml

@@ -4,17 +4,17 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ master ]
+    branches: [ 1.4-maint ]
   pull_request:
     # The branches below must be a subset of the branches above
-    branches: [ master ]
+    branches: [ 1.4-maint ]
   schedule:
     - cron: '39 2 * * 5'
 
 jobs:
   analyze:
     name: Analyze
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     permissions:
       actions: read
       contents: read
@@ -29,38 +29,41 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
       with:
         # just fetching 1 commit is not enough for setuptools-scm, so we fetch all
         fetch-depth: 0
-
+    - name: Set up Python
-    # Initializes the CodeQL tools for scanning.
+      uses: actions/setup-python@v5
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
       with:
-        languages: ${{ matrix.language }}
+        python-version: 3.11
-        # If you wish to specify custom queries, you can do so here or in a config file.
-        # By default, queries listed here will override any specified in a config file.
-        # Prefix the list here with "+" to use these queries and those in the config file.
-        # queries: ./path/to/local/query, your-org/your-repo/queries@main
-
     - name: Cache pip
-      uses: actions/cache@v2
+      uses: actions/cache@v4
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip-${{ hashFiles('requirements.d/development.txt') }}
         restore-keys: |
             ${{ runner.os }}-pip-
             ${{ runner.os }}-
-
+    - name: Install requirements
-    # ℹ️ Command-line programs to run using the OS shell.
-    # 📚 https://git.io/JvXDl
-
-    - name: Install requirements, build and install Borg
       run: |
-       sudo apt install libacl1-dev
+        sudo apt-get update
-       pip3 install -r requirements.d/development.txt
+        sudo apt-get install -y pkg-config build-essential
-       pip3 install -e .
+        sudo apt-get install -y libssl-dev libacl1-dev libxxhash-dev liblz4-dev libzstd-dev
-
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v2
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+    - name: Build and install Borg
+      run: |
+        python3 -m venv ../borg-env
+        source ../borg-env/bin/activate
+        pip3 install -r requirements.d/development.txt
+        pip3 install -ve .
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      uses: github/codeql-action/analyze@v2

.github/workflows/windows.yml

@@ -0,0 +1,28 @@
+name: Windows CI
+on: [push, pull_request]
+
+jobs:
+  msys2-ucrt64:
+    if: false  # build is broken, thus disabled, see #8264
+    runs-on: windows-latest
+    defaults:
+      run:
+        shell: msys2 {0}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: msys2/setup-msys2@v2
+        with:
+          msystem: UCRT64
+          update: true
+      - name: Install dependencies
+        run: ./scripts/msys2-install-deps
+      - name: Build
+        run: ./scripts/msys2-build
+      - name: Test
+        run: ./dist/borg.exe -V
+      - uses: actions/upload-artifact@v3
+        with:
+          name: borg-windows
+          path: dist/borg.exe

.gitignore

@@ -32,3 +32,4 @@ borg.exe
 .coverage.*
 .vagrant
 .eggs
+.DS_Store

.pre-commit-config.yaml

@@ -0,0 +1,5 @@
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.0.287
+  hooks:
+    - id: ruff

.readthedocs.yaml

@@ -0,0 +1,33 @@
+# .readthedocs.yaml - Read the Docs configuration file.
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details.
+
+version: 2
+
+build:
+    os: ubuntu-22.04
+    tools:
+        python: "3.11"
+    jobs:
+        post_checkout:
+            - git fetch --unshallow
+    apt_packages:
+        - build-essential
+        - pkg-config
+        - libacl1-dev
+        - libssl-dev
+        - liblz4-dev
+        - libzstd-dev
+        - libxxhash-dev
+
+python:
+    install:
+        - requirements: requirements.d/development.lock.txt
+        - requirements: requirements.d/docs.txt
+        - method: pip
+          path: .
+
+sphinx:
+    configuration: docs/conf.py
+
+formats:
+    - htmlzip

Brewfile

@@ -0,0 +1,12 @@
+brew 'pkg-config'
+brew 'zstd'
+brew 'lz4'
+brew 'xxhash'
+brew 'openssl@3'
+
+# osxfuse (aka macFUSE) is only required for "borg mount",
+# but won't work on GitHub Actions' workers.
+# it requires installing a kernel extension, so some users
+# may want it and some won't.
+
+#cask 'osxfuse'

LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) 2015-2022 The Borg Collective (see AUTHORS file)
+Copyright (C) 2015-2025 The Borg Collective (see AUTHORS file)
 Copyright (C) 2010-2014 Jonas Borgström <jonas@borgstrom.se>
 All rights reserved.
 

MANIFEST.in

@@ -1,7 +1,7 @@
-# stuff we need to include into the sdist is handled automatically by
+# Files to include into the sdist are handled automatically by
-# setuptools_scm - it includes all git-committed files.
+# setuptools_scm — it includes all Git-committed files.
-# but we want to exclude some committed files/dirs not needed in the sdist:
+# But we want to exclude some committed files/dirs not needed in the sdist:
-exclude .coafile .editorconfig .gitattributes .gitignore .mailmap Vagrantfile
+exclude .editorconfig .gitattributes .gitignore .mailmap Vagrantfile
 prune .github
 include src/borg/platform/darwin.c src/borg/platform/freebsd.c src/borg/platform/linux.c src/borg/platform/posix.c
 include src/borg/platform/syncfilerange.c

README.rst

@@ -18,7 +18,7 @@ See the `installation manual`_ or, if you have already
 downloaded Borg, ``docs/installation.rst`` to get started with Borg.
 There is also an `offline documentation`_ available, in multiple formats.
 
-.. _installation manual: https://borgbackup.readthedocs.org/en/stable/installation.html
+.. _installation manual: https://borgbackup.readthedocs.io/en/stable/installation.html
 .. _offline documentation: https://readthedocs.org/projects/borgbackup/downloads
 
 Main features
@@ -57,10 +57,10 @@ Main features
 
 **Data encryption**
     All data can be protected using 256-bit AES encryption, data integrity and
-    authenticity is verified using HMAC-SHA256. Data is encrypted clientside.
+    authenticity is verified using HMAC-SHA256. Data is encrypted client-side.
 
 **Obfuscation**
-    Optionally, borg can actively obfuscate e.g. the size of files / chunks to
+    Optionally, Borg can actively obfuscate, e.g., the size of files/chunks to
     make fingerprinting attacks more difficult.
 
 **Compression**
@@ -73,24 +73,24 @@ Main features
     * lzma (low speed, high compression)
 
 **Off-site backups**
-    Borg can store data on any remote host accessible over SSH.  If Borg is
+    Borg can store data on any remote host accessible over SSH. If Borg is
-    installed on the remote host, big performance gains can be achieved
+    installed on the remote host, significant performance gains can be achieved
-    compared to using a network filesystem (sshfs, nfs, ...).
+    compared to using a network file system (sshfs, NFS, ...).
 
-**Backups mountable as filesystems**
+**Backups mountable as file systems**
-    Backup archives are mountable as userspace filesystems for easy interactive
+    Backup archives are mountable as user-space file systems for easy interactive
-    backup examination and restores (e.g. by using a regular file manager).
+    backup examination and restores (e.g., by using a regular file manager).
 
 **Easy installation on multiple platforms**
     We offer single-file binaries that do not require installing anything -
     you can just run them on these platforms:
 
     * Linux
-    * Mac OS X
+    * macOS
     * FreeBSD
     * OpenBSD and NetBSD (no xattrs/ACLs support or binaries yet)
     * Cygwin (experimental, no binaries yet)
-    * Linux Subsystem of Windows 10 (experimental)
+    * Windows Subsystem for Linux (WSL) on Windows 10/11 (experimental)
 
 **Free and Open Source Software**
   * security and functionality can be audited independently
@@ -128,9 +128,9 @@ Now doing another backup, just to show off the great deduplication::
     -----------------------------------------------------------------------------
 
 
-For a graphical frontend refer to our complementary project `BorgWeb <https://borgweb.readthedocs.io/>`_.
+For a graphical frontend, refer to our complementary project `BorgWeb <https://borgweb.readthedocs.io/>`_.
 
-Helping, Donations and Bounties, becoming a Patron
+Helping, donations and bounties, becoming a Patron
 --------------------------------------------------
 
 Your help is always welcome!
@@ -144,17 +144,17 @@ https://www.borgbackup.org/support/fund.html
 Links
 -----
 
-* `Main Web Site <https://borgbackup.readthedocs.org/>`_
+* `Main website <https://borgbackup.readthedocs.io/>`_
 * `Releases <https://github.com/borgbackup/borg/releases>`_,
   `PyPI packages <https://pypi.python.org/pypi/borgbackup>`_ and
-  `ChangeLog <https://github.com/borgbackup/borg/blob/master/docs/changes.rst>`_
+  `Changelog <https://github.com/borgbackup/borg/blob/master/docs/changes.rst>`_
-* `Offline Documentation <https://readthedocs.org/projects/borgbackup/downloads>`_
+* `Offline documentation <https://readthedocs.org/projects/borgbackup/downloads>`_
 * `GitHub <https://github.com/borgbackup/borg>`_ and
-  `Issue Tracker <https://github.com/borgbackup/borg/issues>`_.
+  `Issue tracker <https://github.com/borgbackup/borg/issues>`_.
-* `Web-Chat (IRC) <https://web.libera.chat/#borgbackup>`_ and
+* `Web chat (IRC) <https://web.libera.chat/#borgbackup>`_ and
-  `Mailing List <https://mail.python.org/mailman/listinfo/borgbackup>`_
+  `Mailing list <https://mail.python.org/mailman/listinfo/borgbackup>`_
-* `License <https://borgbackup.readthedocs.org/en/stable/authors.html#license>`_
+* `License <https://borgbackup.readthedocs.io/en/stable/authors.html#license>`_
-* `Security contact <https://borgbackup.readthedocs.io/en/latest/support.html#security-contact>`_
+* `Security contact <https://borgbackup.readthedocs.io/en/stable/support.html#security-contact>`_
 
 Compatibility notes
 -------------------
@@ -171,23 +171,19 @@ see ``docs/support.rst`` in the source distribution).
 
 .. start-badges
 
-|doc| |build| |coverage| |bestpractices| |bounties|
+|doc| |build| |coverage| |bestpractices|
-
-.. |bounties| image:: https://api.bountysource.com/badge/team?team_id=78284&style=bounties_posted
-        :alt: Bounty Source
-        :target: https://www.bountysource.com/teams/borgbackup
 
 .. |doc| image:: https://readthedocs.org/projects/borgbackup/badge/?version=stable
         :alt: Documentation
-        :target: https://borgbackup.readthedocs.org/en/stable/
+        :target: https://borgbackup.readthedocs.io/en/stable/
 
-.. |build| image:: https://github.com/borgbackup/borg/workflows/CI/badge.svg?branch=master
+.. |build| image:: https://github.com/borgbackup/borg/workflows/CI/badge.svg?branch=1.4-maint
-        :alt: Build Status (master)
+        :alt: Build Status (1.4-maint)
         :target: https://github.com/borgbackup/borg/actions
 
-.. |coverage| image:: https://codecov.io/github/borgbackup/borg/coverage.svg?branch=master
+.. |coverage| image:: https://codecov.io/github/borgbackup/borg/coverage.svg?branch=1.4-maint
         :alt: Test Coverage
-        :target: https://codecov.io/github/borgbackup/borg?branch=master
+        :target: https://codecov.io/github/borgbackup/borg?branch=1.4-maint
 
 .. |screencast_basic| image:: https://asciinema.org/a/133292.png
         :alt: BorgBackup Basic Usage

README_WINDOWS.rst

@@ -1,48 +1,48 @@
-Borg Native on Windows
+Borg native on Windows
 ======================
 
-Running borg natively on windows is in a early alpha stage. Expect many things to fail.
+Running Borg natively on Windows is in an early alpha stage. Expect many things to fail.
-Do not use the native windows build on any data which you do not want to lose!
+Do not use the native Windows build on any data that you do not want to lose!
 
 Build Requirements
 ------------------
 
 - VC 14.0 Compiler
-- OpenSSL Library v1.1.1c, 64bit (available at https://github.com/python/cpython-bin-deps)
+- OpenSSL Library v1.1.1c, 64-bit (available at https://github.com/python/cpython-bin-deps)
-  Please use the `win-download-openssl.ps1` script to download and extract the library to
+  Use the `win-download-openssl.ps1` script to download and extract the library to
   the correct location. See also the OpenSSL section below.
-- Patience and a lot of coffee / beer
+- Patience and a lot of coffee/beer
 
 What's working
 --------------
 
 .. note::
    The following examples assume that the `BORG_REPO` and `BORG_PASSPHRASE` environment variables are set
-   if the repo or passphrase is not explicitly given.
+   when the repository or passphrase is not explicitly provided.
 
 - Borg does not crash if called with ``borg``
-- ``borg init --encryption repokey-blake2 ./demoRepo`` runs without an error/warning.
+- ``borg init --encryption repokey-blake2 ./demoRepo`` runs without errors or warnings.
-  Note that absolute paths only work if the protocol is explicitly set to file://
+  Note that absolute paths only work if the protocol is explicitly set to ``file://``
 - ``borg create ::backup-{now} D:\DemoData`` works as expected.
 - ``borg list`` works as expected.
-- ``borg extract --strip-components 1 ::backup-XXXX`` works. 
+- ``borg extract --strip-components 1 ::backup-XXXX`` works.
-  If absolute paths are extracted, it's important to pass ``--strip-components 1`` as
+  If absolute paths are extracted, it is important to pass ``--strip-components 1``,
   otherwise the data is restored to the original location!
 
 What's NOT working
 ------------------
 
-- Extracting a backup which was created on windows machine on a non windows machine will fail.
+- Extracting a backup created on a Windows machine on a non-Windows machine will fail.
-- And many things more.
+- Many other things.
 
 
 OpenSSL, Windows and Python
 ---------------------------
 Windows does not ship OpenSSL by default, so we need to get the library from somewhere else.
-However, a default python installation does include `libcrypto` which is required by borg.
+However, a default Python installation does include `libcrypto`, which is required by Borg.
-The only things which are missing to build borg are the header and `*.lib` files.
+The only things missing to build Borg are the header and `*.lib` files.
-Luckily the python developers provide all required files in a separate repository.
+Luckily, the Python developers provide all required files in a separate repository.
 The `win-download-openssl.ps1` script can be used to download the package from
 https://github.com/python/cpython-bin-deps and extract the files to the correct location.
-For Anaconda, the required libraries can be installed with `conda install -c anaconda openssl`.
+For Anaconda, the required libraries can be installed with ``conda install -c anaconda openssl``.
 

SECURITY.md

@@ -5,8 +5,10 @@
 These borg releases are currently supported with security updates.
 
 | Version | Supported          |
-| ------- | ------------------ |
+|---------|--------------------|
-| 1.1.x   | :white_check_mark: |
+| 1.4.x   | :white_check_mark: |
+| 1.2.x   | :white_check_mark: |
+| 1.1.x   | :x:                |
 | < 1.1   | :x:                |
 
 ## Reporting a Vulnerability

Vagrantfile

@@ -3,22 +3,24 @@
 
 # Automated creation of testing environments / binaries on misc. platforms
 
-$cpus = Integer(ENV.fetch('VMCPUS', '4'))  # create VMs with that many cpus
+$cpus = Integer(ENV.fetch('VMCPUS', '16'))  # create VMs with that many cpus
-$xdistn = Integer(ENV.fetch('XDISTN', '4'))  # dispatch tests to that many pytest workers
+$xdistn = Integer(ENV.fetch('XDISTN', '16'))  # dispatch tests to that many pytest workers
 $wmem = $xdistn * 256  # give the VM additional memory for workers [MB]
 
 def packages_debianoid(user)
   return <<-EOF
     export DEBIAN_FRONTEND=noninteractive
-    # this is to avoid grub asking about which device it should install to:
+    # This is to avoid GRUB asking which device it should install to:
     echo "set grub-pc/install_devices /dev/sda" | debconf-communicate
     apt-get -y -qq update
     apt-get -y -qq dist-upgrade
-    # for building borgbackup and dependencies:
+    # For building BorgBackup and dependencies:
-    apt install -y libssl-dev libacl1-dev liblz4-dev libzstd-dev pkg-config
+    apt install -y libssl-dev libacl1-dev liblz4-dev libzstd-dev libxxhash-dev pkg-config
     apt install -y libfuse-dev fuse || true
     apt install -y libfuse3-dev fuse3 || true
     apt install -y locales || true
+    # We need to give the prefix to support Debian Buster (no libxxhash.pc for pkg-config there):
+    echo 'export BORG_LIBXXHASH_PREFIX=/usr' >> ~vagrant/.bash_profile
     sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
     usermod -a -G fuse #{user}
     chgrp fuse /dev/fuse
@@ -36,15 +38,18 @@ def packages_freebsd
     hostname freebsd
     # install all the (security and other) updates, base system
     freebsd-update --not-running-from-cron fetch install
-    # for building borgbackup and dependencies:
+    # For building BorgBackup and dependencies:
     pkg install -y liblz4 zstd pkgconf
     pkg install -y fusefs-libs || true
     pkg install -y fusefs-libs3 || true
+    pkg install -y rust
     pkg install -y git bash  # fakeroot causes lots of troubles on freebsd
     # for building python (for the tests we use pyenv built pythons):
-    pkg install -y python38 py38-sqlite3 py38-virtualenv py38-pip
+    pkg install -y python310 py310-sqlite3
     # make sure there is a python3 command
-    ln -sf /usr/local/bin/python3.8 /usr/local/bin/python3
+    ln -sf /usr/local/bin/python3.10 /usr/local/bin/python3
+    python3 -m ensurepip
+    pip3 install virtualenv
     # make bash default / work:
     chsh -s bash vagrant
     mount -t fdescfs fdesc /dev/fd
@@ -52,7 +57,7 @@ def packages_freebsd
     # make FUSE work
     echo 'fuse_load="YES"' >> /boot/loader.conf
     echo 'vfs.usermount=1' >> /etc/sysctl.conf
-    kldload fuse
+    kldload fusefs
     sysctl vfs.usermount=1
     pw groupmod operator -M vagrant
     # /dev/fuse has group operator
@@ -66,11 +71,23 @@ end
 
 def packages_openbsd
   return <<-EOF
+    hostname "openbsd77.localdomain"
+    echo "$(hostname)" > /etc/myname
+    echo "127.0.0.1	localhost" > /etc/hosts
+    echo "::1 localhost" >> /etc/hosts
+    echo "127.0.0.1	$(hostname) $(hostname -s)" >> /etc/hosts
+    echo "https://ftp.eu.openbsd.org/pub/OpenBSD" > /etc/installurl
+    ftp https://cdn.openbsd.org/pub/OpenBSD/$(uname -r)/$(uname -m)/comp$(uname -r | tr -d .).tgz
+    tar -C / -xzphf comp$(uname -r | tr -d .).tgz
+    rm comp$(uname -r | tr -d .).tgz
     pkg_add bash
     chsh -s bash vagrant
+    pkg_add xxhash
     pkg_add lz4
     pkg_add zstd
     pkg_add git  # no fakeroot
+    pkg_add rust
+    pkg_add openssl%3.4
     pkg_add py3-pip
     pkg_add py3-virtualenv
   EOF
@@ -78,11 +95,11 @@ end
 
 def packages_netbsd
   return <<-EOF
-    # use the latest stuff, some packages in "9.2" are quite broken
+    echo 'http://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/$arch/9.3/All' > /usr/pkg/etc/pkgin/repositories.conf
-    echo 'http://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/$arch/9.0_current/All' > /usr/pkg/etc/pkgin/repositories.conf
     pkgin update
     pkgin -y upgrade
     pkg_add zstd lz4 xxhash git
+    pkg_add rust
     pkg_add bash
     chsh -s bash vagrant
     echo "export PROMPT_COMMAND=" >> ~vagrant/.bash_profile  # bug in netbsd 9.2, .bash_profile broken for screen
@@ -90,45 +107,36 @@ def packages_netbsd
     pkg_add pkg-config
     # pkg_add fuse  # llfuse supports netbsd, but is still buggy.
     # https://bitbucket.org/nikratio/python-llfuse/issues/70/perfuse_open-setsockopt-no-buffer-space
-    pkg_add python38 py38-sqlite3 py38-pip py38-virtualenv py38-expat
+    pkg_add py311-sqlite3 py311-pip py311-virtualenv py311-expat
-    ln -s /usr/pkg/lib/python3.8/_sysconfigdata_netbsd9.py /usr/pkg/lib/python3.8/_sysconfigdata__netbsd9_.py  # bug in netbsd 9.2, expected filename not there.
+    ln -s /usr/pkg/bin/python3.11 /usr/pkg/bin/python
-    pkg_add python39 py39-sqlite3 py39-pip py39-virtualenv py39-expat
+    ln -s /usr/pkg/bin/python3.11 /usr/pkg/bin/python3
-    ln -s /usr/pkg/bin/python3.9 /usr/pkg/bin/python
+    ln -s /usr/pkg/bin/pip3.11 /usr/pkg/bin/pip
-    ln -s /usr/pkg/bin/python3.9 /usr/pkg/bin/python3
+    ln -s /usr/pkg/bin/pip3.11 /usr/pkg/bin/pip3
-    ln -s /usr/pkg/bin/pip3.9 /usr/pkg/bin/pip
+    ln -s /usr/pkg/bin/virtualenv-3.11 /usr/pkg/bin/virtualenv
-    ln -s /usr/pkg/bin/pip3.9 /usr/pkg/bin/pip3
+    ln -s /usr/pkg/bin/virtualenv-3.11 /usr/pkg/bin/virtualenv3
-    ln -s /usr/pkg/bin/virtualenv-3.9 /usr/pkg/bin/virtualenv
-    ln -s /usr/pkg/bin/virtualenv-3.9 /usr/pkg/bin/virtualenv3
-    ln -s /usr/pkg/lib/python3.9/_sysconfigdata_netbsd9.py /usr/pkg/lib/python3.9/_sysconfigdata__netbsd9_.py  # bug in netbsd 9.2, expected filename not there.
   EOF
 end
 
-def packages_darwin
+def package_update_openindiana
   return <<-EOF
-    # install all the (security and other) updates
+    echo "nameserver 1.1.1.1" > /etc/resolv.conf
-    sudo softwareupdate --ignore iTunesX
+    # needs separate provisioning step + reboot to become effective:
-    sudo softwareupdate --ignore iTunes
+    pkg update
-    sudo softwareupdate --ignore Safari
-    sudo softwareupdate --ignore "Install macOS High Sierra"
-    sudo softwareupdate --install --all
-    which brew || CI=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
-    brew update > /dev/null
-    brew install pkg-config readline openssl@1.1 zstd lz4 xz fakeroot
-    brew install --cask macfuse
-    # brew upgrade  # upgrade everything (takes rather long)
-    echo 'export PKG_CONFIG_PATH=/usr/local/opt/openssl@1.1/lib/pkgconfig' >> ~vagrant/.bash_profile
   EOF
 end
 
 def packages_openindiana
   return <<-EOF
-    # needs separate provisioning step + reboot:
+    pkg install gcc-13 git
-    #pkg update
+    pkg install pkg-config libxxhash
-    #pkg install gcc-7 python-39 setuptools-39
+    pkg install python-313
-    ln -sf /usr/bin/python3.9 /usr/bin/python3
+    ln -sf /usr/bin/python3.13 /usr/bin/python3
+    ln -sf /usr/bin/python3.13-config /usr/bin/python3-config
     python3 -m ensurepip
-    ln -sf /usr/bin/pip3.9 /usr/bin/pip3
+    ln -sf /usr/bin/pip3.13 /usr/bin/pip3
     pip3 install virtualenv
+    # let borg's pkg-config find openssl:
+    pfexec pkg set-mediator -V 3 openssl
   EOF
 end
 
@@ -147,18 +155,10 @@ def install_pyenv(boxname)
   EOF
 end
 
-def fix_pyenv_darwin(boxname)
-  return <<-EOF
-    echo 'export PYTHON_CONFIGURE_OPTS="--enable-framework"' >> ~/.bash_profile
-  EOF
-end
-
 def install_pythons(boxname)
   return <<-EOF
     . ~/.bash_profile
-    pyenv install 3.10.0  # tests, version supporting openssl 1.1
+    pyenv install 3.11.14  # tests, binary build
-    pyenv install 3.9.10  # tests, version supporting openssl 1.1, binary build
-    pyenv install 3.8.0  # tests, version supporting openssl 1.1
     pyenv rehash
   EOF
 end
@@ -175,9 +175,9 @@ def build_pyenv_venv(boxname)
   return <<-EOF
     . ~/.bash_profile
     cd /vagrant/borg
-    # use the latest 3.9 release
+    # use the latest 3.11 release
-    pyenv global 3.9.10
+    pyenv global 3.11.14
-    pyenv virtualenv 3.9.10 borg-env
+    pyenv virtualenv 3.11.14 borg-env
     ln -s ~/.pyenv/versions/borg-env .
   EOF
 end
@@ -190,8 +190,7 @@ def install_borg(fuse)
     pip install -U wheel  # upgrade wheel, might be too old
     cd borg
     pip install -r requirements.d/development.lock.txt
-    python setup.py clean
+    python3 scripts/make.py clean
-    python setup.py clean2
     pip install -e .[#{fuse}]
   EOF
 end
@@ -201,10 +200,7 @@ def install_pyinstaller()
     . ~/.bash_profile
     cd /vagrant/borg
     . borg-env/bin/activate
-    git clone https://github.com/thomaswaldmann/pyinstaller.git
+    pip install 'pyinstaller==6.7.0'
-    cd pyinstaller
-    git checkout v4.7-maint
-    python setup.py install
   EOF
 end
 
@@ -227,10 +223,12 @@ def run_tests(boxname, skip_env)
     . ../borg-env/bin/activate
     if which pyenv 2> /dev/null; then
       # for testing, use the earliest point releases of the supported python versions:
-      pyenv global 3.8.0 3.9.10 3.10.0
+      pyenv global 3.11.14
-      pyenv local 3.8.0 3.9.10 3.10.0
+      pyenv local 3.11.14
     fi
     # otherwise: just use the system python
+    # avoid that git complains about dubious ownership if we use fakeroot:
+    git config --global --add safe.directory /vagrant/borg/borg
     # some OSes can only run specific test envs, e.g. because they miss FUSE support:
     export TOX_SKIP_ENV='#{skip_env}'
     if which fakeroot 2> /dev/null; then
@@ -269,147 +267,148 @@ Vagrant.configure(2) do |config|
     v.cpus = $cpus
   end
 
-  config.vm.define "focal64" do |b|
+  config.vm.define "noble" do |b|
-    b.vm.box = "ubuntu/focal64"
+    b.vm.box = "bento/ubuntu-24.04"
     b.vm.provider :virtualbox do |v|
       v.memory = 1024 + $wmem
     end
     b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant")
     b.vm.provision "packages debianoid", :type => :shell, :inline => packages_debianoid("vagrant")
-    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("focal64")
+    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("noble")
     b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse")
-    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("focal64", ".*none.*")
+    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("noble", ".*none.*")
   end
 
-  config.vm.define "bullseye64" do |b|
+  config.vm.define "jammy" do |b|
+    b.vm.box = "ubuntu/jammy64"
+    b.vm.provider :virtualbox do |v|
+      v.memory = 1024 + $wmem
+    end
+    b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant")
+    b.vm.provision "packages debianoid", :type => :shell, :inline => packages_debianoid("vagrant")
+    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("jammy")
+    b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse")
+    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("jammy", ".*none.*")
+  end
+
+  config.vm.define "trixie" do |b|
+    b.vm.box = "debian/testing64"
+    b.vm.provider :virtualbox do |v|
+      v.memory = 1024 + $wmem
+    end
+    b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant")
+    b.vm.provision "packages debianoid", :type => :shell, :inline => packages_debianoid("vagrant")
+    b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("trixie")
+    b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("trixie")
+    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("trixie")
+    b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse")
+    b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller()
+    b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("trixie")
+    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("trixie", ".*none.*")
+  end
+
+  config.vm.define "bookworm" do |b|
+    b.vm.box = "debian/bookworm64"
+    b.vm.provider :virtualbox do |v|
+      v.memory = 1024 + $wmem
+    end
+    b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant")
+    b.vm.provision "packages debianoid", :type => :shell, :inline => packages_debianoid("vagrant")
+    b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("bookworm")
+    b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("bookworm")
+    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("bookworm")
+    b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse")
+    b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller()
+    b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("bookworm")
+    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("bookworm", ".*none.*")
+  end
+
+  config.vm.define "bullseye" do |b|
     b.vm.box = "debian/bullseye64"
     b.vm.provider :virtualbox do |v|
       v.memory = 1024 + $wmem
     end
     b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant")
     b.vm.provision "packages debianoid", :type => :shell, :inline => packages_debianoid("vagrant")
-    b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("bullseye64")
+    b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("bullseye")
-    b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("bullseye64")
+    b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("bullseye")
-    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("bullseye64")
+    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("bullseye")
     b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse")
     b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller()
-    b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("bullseye64")
+    b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("bullseye")
-    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("bullseye64", ".*none.*")
+    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("bullseye", ".*none.*")
   end
 
-  config.vm.define "buster64" do |b|
+  config.vm.define "freebsd13" do |b|
-    b.vm.box = "debian/buster64"
+    b.vm.box = "generic/freebsd13"
-    b.vm.provider :virtualbox do |v|
-      v.memory = 1024 + $wmem
-    end
-    b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant")
-    b.vm.provision "packages debianoid", :type => :shell, :inline => packages_debianoid("vagrant")
-    b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("buster64")
-    b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("buster64")
-    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("buster64")
-    b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse")
-    b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller()
-    b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("buster64")
-    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("buster64", ".*none.*")
-  end
-
-  config.vm.define "stretch64" do |b|
-    b.vm.box = "debian/stretch64"
-    b.vm.provider :virtualbox do |v|
-      v.memory = 1024 + $wmem
-    end
-    b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant")
-    b.vm.provision "packages debianoid", :type => :shell, :inline => packages_debianoid("vagrant")
-    b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("stretch64")
-    b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("stretch64")
-    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("stretch64")
-    b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse")
-    b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller()
-    b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("stretch64")
-    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("stretch64", ".*(fuse3|none).*")
-  end
-
-  config.vm.define "freebsd64" do |b|
-    b.vm.box = "freebsd121-64"
     b.vm.provider :virtualbox do |v|
       v.memory = 1024 + $wmem
     end
     b.ssh.shell = "sh"
     b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant")
     b.vm.provision "packages freebsd", :type => :shell, :inline => packages_freebsd
-    b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("freebsd64")
+    b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("freebsd13")
-    b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("freebsd64")
+    b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("freebsd13")
-    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("freebsd64")
+    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("freebsd13")
     b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse")
     b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller()
-    b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("freebsd64")
+    b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("freebsd13")
-    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("freebsd64", ".*(fuse3|none).*")
+    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("freebsd13", ".*(fuse3|none).*")
   end
 
-  config.vm.define "openbsd64" do |b|
+  config.vm.define "freebsd14" do |b|
-    b.vm.box = "generic/openbsd6"
+    b.vm.box = "generic/freebsd14"
+    b.vm.provider :virtualbox do |v|
+      v.memory = 1024 + $wmem
+    end
+    b.ssh.shell = "sh"
+    b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant")
+    b.vm.provision "packages freebsd", :type => :shell, :inline => packages_freebsd
+    b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("freebsd14")
+    b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("freebsd14")
+    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("freebsd14")
+    b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse")
+    b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller()
+    b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("freebsd14")
+    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("freebsd14", ".*(fuse3|none).*")
+  end
+
+  config.vm.define "openbsd7" do |b|
+    b.vm.box = "l3system/openbsd77-amd64"
     b.vm.provider :virtualbox do |v|
       v.memory = 1024 + $wmem
     end
     b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant")
     b.vm.provision "packages openbsd", :type => :shell, :inline => packages_openbsd
-    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("openbsd64")
+    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("openbsd7")
     b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("nofuse")
-    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("openbsd64", ".*fuse.*")
+    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("openbsd7", ".*fuse.*")
   end
 
-  config.vm.define "netbsd64" do |b|
+  config.vm.define "netbsd9" do |b|
     b.vm.box = "generic/netbsd9"
     b.vm.provider :virtualbox do |v|
       v.memory = 4096 + $wmem  # need big /tmp tmpfs in RAM!
     end
     b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant")
     b.vm.provision "packages netbsd", :type => :shell, :inline => packages_netbsd
-    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("netbsd64")
+    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("netbsd9")
     b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg(false)
-    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("netbsd64", ".*fuse.*")
+    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("netbsd9", ".*fuse.*")
-  end
-
-  config.vm.define "darwin64" do |b|
-    b.vm.box = "macos-sierra"
-    b.vm.provider :virtualbox do |v|
-      v.memory = 4096 + $wmem
-      v.customize ['modifyvm', :id, '--ostype', 'MacOS_64']
-      v.customize ['modifyvm', :id, '--paravirtprovider', 'default']
-      v.customize ['modifyvm', :id, '--nested-hw-virt', 'on']
-      # Adjust CPU settings according to
-      # https://github.com/geerlingguy/macos-virtualbox-vm
-      v.customize ['modifyvm', :id, '--cpuidset',
-                   '00000001', '000306a9', '00020800', '80000201', '178bfbff']
-      # Disable USB variant requiring Virtualbox proprietary extension pack
-      v.customize ["modifyvm", :id, '--usbehci', 'off', '--usbxhci', 'off']
-    end
-    b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant")
-    b.vm.provision "packages darwin", :type => :shell, :privileged => false, :inline => packages_darwin
-    b.vm.provision "install pyenv", :type => :shell, :privileged => false, :inline => install_pyenv("darwin64")
-    b.vm.provision "fix pyenv", :type => :shell, :privileged => false, :inline => fix_pyenv_darwin("darwin64")
-    b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("darwin64")
-    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("darwin64")
-    b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("llfuse")
-    b.vm.provision "install pyinstaller", :type => :shell, :privileged => false, :inline => install_pyinstaller()
-    b.vm.provision "build binary with pyinstaller", :type => :shell, :privileged => false, :inline => build_binary_with_pyinstaller("darwin64")
-    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("darwin64", ".*(fuse3|none).*")
   end
 
   # rsync on openindiana has troubles, does not set correct owner for /vagrant/borg and thus gives lots of
   # permission errors. can be manually fixed in the VM by: sudo chown -R vagrant /vagrant/borg ; then rsync again.
-  config.vm.define "openindiana64" do |b|
+  config.vm.define "openindiana" do |b|
-    b.vm.box = "openindiana"
+    b.vm.box = "openindiana/hipster"
     b.vm.provider :virtualbox do |v|
       v.memory = 2048 + $wmem
     end
     b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant")
+    b.vm.provision "package update openindiana", :type => :shell, :inline => package_update_openindiana, :reboot => true
     b.vm.provision "packages openindiana", :type => :shell, :inline => packages_openindiana
-    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("openindiana64")
+    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("openindiana")
     b.vm.provision "install borg", :type => :shell, :privileged => false, :inline => install_borg("nofuse")
-    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("openindiana64", ".*fuse.*")
+    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("openindiana", ".*fuse.*")
   end
-
-  # TODO: create more VMs with python 3.8+ and openssl 1.1.
-  # See branch 1.1-maint for a better equipped Vagrantfile (but still on py35 and openssl 1.0).
 end

docs/3rd_party/README

@@ -1,5 +0,0 @@
-Here we store 3rd party documentation, licenses, etc.
-
-Please note that all files inside the "borg" package directory (except the
-stuff excluded in setup.py) will be INSTALLED, so don't keep docs or licenses
-there.

docs/3rd_party/blake2/COPYING

@@ -1,122 +0,0 @@
-Creative Commons Legal Code
-
-CC0 1.0 Universal
-
-    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
-    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
-    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
-    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
-    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
-    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
-    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
-    HEREUNDER.
-
-Statement of Purpose
-
-The laws of most jurisdictions throughout the world automatically confer
-exclusive Copyright and Related Rights (defined below) upon the creator
-and subsequent owner(s) (each and all, an "owner") of an original work of
-authorship and/or a database (each, a "Work").
-
-Certain owners wish to permanently relinquish those rights to a Work for
-the purpose of contributing to a commons of creative, cultural and
-scientific works ("Commons") that the public can reliably and without fear
-of later claims of infringement build upon, modify, incorporate in other
-works, reuse and redistribute as freely as possible in any form whatsoever
-and for any purposes, including without limitation commercial purposes.
-These owners may contribute to the Commons to promote the ideal of a free
-culture and the further production of creative, cultural and scientific
-works, or to gain reputation or greater distribution for their Work in
-part through the use and efforts of others.
-
-For these and/or other purposes and motivations, and without any
-expectation of additional consideration or compensation, the person
-associating CC0 with a Work (the "Affirmer"), to the extent that he or she
-is an owner of Copyright and Related Rights in the Work, voluntarily
-elects to apply CC0 to the Work and publicly distribute the Work under its
-terms, with knowledge of his or her Copyright and Related Rights in the
-Work and the meaning and intended legal effect of CC0 on those rights.
-
-1. Copyright and Related Rights. A Work made available under CC0 may be
-protected by copyright and related or neighboring rights ("Copyright and
-Related Rights"). Copyright and Related Rights include, but are not
-limited to, the following:
-
-  i. the right to reproduce, adapt, distribute, perform, display,
-     communicate, and translate a Work;
- ii. moral rights retained by the original author(s) and/or performer(s);
-iii. publicity and privacy rights pertaining to a person's image or
-     likeness depicted in a Work;
- iv. rights protecting against unfair competition in regards to a Work,
-     subject to the limitations in paragraph 4(a), below;
-  v. rights protecting the extraction, dissemination, use and reuse of data
-     in a Work;
- vi. database rights (such as those arising under Directive 96/9/EC of the
-     European Parliament and of the Council of 11 March 1996 on the legal
-     protection of databases, and under any national implementation
-     thereof, including any amended or successor version of such
-     directive); and
-vii. other similar, equivalent or corresponding rights throughout the
-     world based on applicable law or treaty, and any national
-     implementations thereof.
-
-2. Waiver. To the greatest extent permitted by, but not in contravention
-of, applicable law, Affirmer hereby overtly, fully, permanently,
-irrevocably and unconditionally waives, abandons, and surrenders all of
-Affirmer's Copyright and Related Rights and associated claims and causes
-of action, whether now known or unknown (including existing as well as
-future claims and causes of action), in the Work (i) in all territories
-worldwide, (ii) for the maximum duration provided by applicable law or
-treaty (including future time extensions), (iii) in any current or future
-medium and for any number of copies, and (iv) for any purpose whatsoever,
-including without limitation commercial, advertising or promotional
-purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
-member of the public at large and to the detriment of Affirmer's heirs and
-successors, fully intending that such Waiver shall not be subject to
-revocation, rescission, cancellation, termination, or any other legal or
-equitable action to disrupt the quiet enjoyment of the Work by the public
-as contemplated by Affirmer's express Statement of Purpose.
-
-3. Public License Fallback. Should any part of the Waiver for any reason
-be judged legally invalid or ineffective under applicable law, then the
-Waiver shall be preserved to the maximum extent permitted taking into
-account Affirmer's express Statement of Purpose. In addition, to the
-extent the Waiver is so judged Affirmer hereby grants to each affected
-person a royalty-free, non transferable, non sublicensable, non exclusive,
-irrevocable and unconditional license to exercise Affirmer's Copyright and
-Related Rights in the Work (i) in all territories worldwide, (ii) for the
-maximum duration provided by applicable law or treaty (including future
-time extensions), (iii) in any current or future medium and for any number
-of copies, and (iv) for any purpose whatsoever, including without
-limitation commercial, advertising or promotional purposes (the
-"License"). The License shall be deemed effective as of the date CC0 was
-applied by Affirmer to the Work. Should any part of the License for any
-reason be judged legally invalid or ineffective under applicable law, such
-partial invalidity or ineffectiveness shall not invalidate the remainder
-of the License, and in such case Affirmer hereby affirms that he or she
-will not (i) exercise any of his or her remaining Copyright and Related
-Rights in the Work or (ii) assert any associated claims and causes of
-action with respect to the Work, in either case contrary to Affirmer's
-express Statement of Purpose.
-
-4. Limitations and Disclaimers.
-
- a. No trademark or patent rights held by Affirmer are waived, abandoned,
-    surrendered, licensed or otherwise affected by this document.
- b. Affirmer offers the Work as-is and makes no representations or
-    warranties of any kind concerning the Work, express, implied,
-    statutory or otherwise, including without limitation warranties of
-    title, merchantability, fitness for a particular purpose, non
-    infringement, or the absence of latent or other defects, accuracy, or
-    the present or absence of errors, whether or not discoverable, all to
-    the greatest extent permissible under applicable law.
- c. Affirmer disclaims responsibility for clearing rights of other persons
-    that may apply to the Work or any use thereof, including without
-    limitation any person's Copyright and Related Rights in the Work.
-    Further, Affirmer disclaims responsibility for obtaining any necessary
-    consents, permissions or other rights required for any use of the
-    Work.
- d. Affirmer understands and acknowledges that Creative Commons is not a
-    party to this document and has no duty or obligation with respect to
-    this CC0 or use of the Work.
-

docs/3rd_party/blake2/README.md

@@ -1,13 +0,0 @@
-# BLAKE2
-
-This is the reference source code package of BLAKE2.
-
-All code is triple-licensed under the [CC0](http://creativecommons.org/publicdomain/zero/1.0),
-the [OpenSSL Licence](https://www.openssl.org/source/license.html),
-or the [Apache Public License 2.0](https://www.apache.org/licenses/LICENSE-2.0),
-at your choosing.
-
-More: [https://blake2.net](https://blake2.net). [GitHub repository](https://github.com/BLAKE2/BLAKE2).
-
-Contact: contact@blake2.net
-

docs/3rd_party/lz4/LICENSE

@@ -1,24 +0,0 @@
-LZ4 Library
-Copyright (c) 2011-2016, Yann Collet
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification,
-are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice, this
-  list of conditions and the following disclaimer in the documentation and/or
-  other materials provided with the distribution.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
-ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
-ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docs/3rd_party/zstd/LICENSE

@@ -1,30 +0,0 @@
-BSD License
-
-For Zstandard software
-
-Copyright (c) 2016-present, Facebook, Inc. All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification,
-are permitted provided that the following conditions are met:
-
- * Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
-
- * Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
- * Neither the name Facebook nor the names of its contributors may be used to
-   endorse or promote products derived from this software without specific
-   prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
-ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
-ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docs/_templates/layout.html

@@ -0,0 +1,174 @@
+{%- extends "basic/layout.html" %}
+
+{# Do this so that bootstrap is included before the main css file #}
+{%- block htmltitle %}
+  {% set script_files = script_files + ["_static/myscript.js"] %}
+  <!-- Licensed under the Apache 2.0 License -->
+  <link rel="stylesheet" type="text/css" href="{{ pathto('_static/fonts/open-sans/stylesheet.css', 1) }}" />
+  <!-- Licensed under the SIL Open Font License -->
+  <link rel="stylesheet" type="text/css" href="{{ pathto('_static/fonts/source-serif-pro/source-serif-pro.css', 1) }}" />
+  <link rel="stylesheet" type="text/css" href="{{ pathto('_static/css/bootstrap.min.css', 1) }}" />
+  <link rel="stylesheet" type="text/css" href="{{ pathto('_static/css/bootstrap-theme.min.css', 1) }}" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  {{ super() }}
+{%- endblock %}
+
+{%- block extrahead %}
+  {% if theme_touch_icon %}
+  <link rel="apple-touch-icon" href="{{ pathto('_static/' ~ theme_touch_icon, 1) }}" />
+  {% endif %}
+  <meta name="readthedocs-addons-api-version" content="1" />
+  {{ super() }}
+{% endblock %}
+
+{# Displays the URL for the homepage if it's set or the master_doc if it is not #}
+{% macro homepage() -%}
+  {%- if theme_homepage %}
+    {%- if hasdoc(theme_homepage) %}
+      {{ pathto(theme_homepage) }}
+    {%- else %}
+      {{ theme_homepage }}
+    {%- endif %}
+  {%- else %}
+    {{ pathto(master_doc) }}
+  {%- endif %}
+{%- endmacro %}
+
+{# Displays the URL for the tospage if it's set or falls back to homepage macro #}
+{% macro tospage() -%}
+  {%- if theme_tospage %}
+    {%- if hasdoc(theme_tospage) %}
+      {{ pathto(theme_tospage) }}
+    {%- else %}
+      {{ theme_tospage }}
+    {%- endif %}
+  {%- else %}
+    {{ homepage() }}
+  {%- endif %}
+{%- endmacro %}
+
+{# Displays the URL for the projectpage if it's set or falls back to homepage macro #}
+{% macro projectlink() -%}
+  {%- if theme_projectlink %}
+    {%- if hasdoc(theme_projectlink) %}
+      {{ pathto(theme_projectlink) }}
+    {%- else %}
+      {{ theme_projectlink }}
+    {%- endif %}
+  {%- else %}
+    {{ homepage() }}
+  {%- endif %}
+{%- endmacro %}
+
+{# Displays the next and previous links both before and after content #}
+{% macro render_relations() -%}
+  {% if prev or next %}
+  <div class="footer-relations">
+    {% if prev %}
+      <div class="pull-left">
+        <a class="btn btn-default" href="{{ prev.link|e }}" title="{{ _('previous chapter')}} (use the left arrow)">{{ prev.title }}</a>
+      </div>
+    {% endif %}
+    {%- if next and next.title != '&lt;no title&gt;' %}
+      <div class="pull-right">
+        <a class="btn btn-default" href="{{ next.link|e }}" title="{{ _('next chapter')}} (use the right arrow)">{{ next.title }}</a>
+      </div>
+    {%- endif %}
+    </div>
+    <div class="clearer"></div>
+  {% endif %}
+{%- endmacro %}
+
+{%- macro guzzle_sidebar() %}
+  <div id="left-column">
+    <div class="sphinxsidebar">
+      {%- if sidebars != None %}
+        {#- new style sidebar: explicitly include/exclude templates #}
+        {%- for sidebartemplate in sidebars %}
+        {%- include sidebartemplate %}
+        {%- endfor %}
+      {% else %}
+        {% include "logo-text.html" %}
+        {% include "globaltoc.html" %}
+        {% include "searchbox.html" %}
+      {%- endif %}
+    </div>
+  </div>
+{%- endmacro %}
+
+{%- block content %}
+
+  {%- if pagename == 'index' and theme_index_template %}
+    {% include theme_index_template %}
+  {%- else %}
+    <div class="container-wrapper">
+
+      <div id="mobile-toggle">
+        <a href="#"><span class="glyphicon glyphicon-align-justify" aria-hidden="true"></span></a>
+      </div>
+
+      {%- block sidebar1 %}{{ guzzle_sidebar() }}{% endblock %}
+
+      {%- block document_wrapper %}
+        {%- block document %}
+        <div id="right-column">
+          {% block breadcrumbs %}
+          <div role="navigation" aria-label="breadcrumbs navigation">
+            <ol class="breadcrumb">
+              <li><a href="{{ pathto(master_doc) }}">Docs</a></li>
+              {% for doc in parents %}
+                <li><a href="{{ doc.link|e }}">{{ doc.title }}</a></li>
+              {% endfor %}
+              <li>{{ title }}</li>
+            </ol>
+          </div>
+          {% endblock %}
+          <div class="document clearer body" role="main">
+            {% block body %} {% endblock %}
+          </div>
+          {%- block bottom_rel_links %}
+            {{ render_relations() }}
+          {%- endblock %}
+        </div>
+        <div class="clearfix"></div>
+        {%- endblock %}
+      {%- endblock %}
+
+      {%- block comments -%}
+        {% if theme_disqus_comments_shortname %}
+        <div class="container comment-container">
+          {% include "comments.html" %}
+        </div>
+        {% endif %}
+      {%- endblock %}
+    </div>
+  {%- endif %}
+  {%- endblock %}
+
+{%- block footer %}
+<script type="text/javascript">
+  $("#mobile-toggle a").click(function () {
+    $("#left-column").toggle();
+  });
+</script>
+<script type="text/javascript" src="{{ pathto('_static/js/bootstrap.js', 1)}}"></script>
+{%- block footer_wrapper %}
+  <div class="footer">
+    &copy; Copyright {{ copyright }}. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
+  </div>
+{%- endblock %}
+{%- block ga %}
+  {%- if theme_google_analytics_account %}
+    <script type="text/javascript">
+      var _gaq = _gaq || [];
+      _gaq.push(['_setAccount', '{{ theme_google_analytics_account }}']);
+      _gaq.push(['_trackPageview']);
+      (function() {
+        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+      })();
+    </script>
+  {%- endif %}
+{%- endblock %}
+{%- endblock %}

docs/_templates/versionselector.html

@@ -0,0 +1,29 @@
+<div class="version-selector" id="borg-version-selector" style="display:none;">
+  <label for="version-select">Select your Borg version:</label>
+  <select id="version-select"></select>
+</div>
+<script type="text/javascript">
+  // Populate the version selector using ReadTheDocs data if available.
+  function borgInitVersionSelector(data) {
+    var versions = data && data.versions && data.versions.active;
+    if (!versions || !versions.length) return;
+    var current = data.versions && data.versions.current && data.versions.current.slug;
+    var select = document.getElementById("version-select");
+    if (!select) return;
+    versions.forEach(function(v) {
+      var opt = document.createElement("option");
+      opt.value = v.urls.documentation;
+      opt.textContent = v.slug;
+      if (v.slug === current) opt.selected = true;
+      select.appendChild(opt);
+    });
+    select.addEventListener("change", function() {
+      window.location.href = this.value;
+    });
+    document.getElementById("borg-version-selector").style.display = "";
+  }
+
+  document.addEventListener("readthedocs-addons-data-ready", function(event) {
+    borgInitVersionSelector(event.detail.data());
+  });
+</script>

docs/binaries/00_README.txt

@@ -0,0 +1,117 @@
+Binary BorgBackup builds
+========================
+
+General notes
+-------------
+
+The binaries are supposed to work on the specified platform without installing anything else.
+
+There are some limitations, though:
+- for Linux, your system must have the same or newer glibc version as the one used for building
+- for macOS, you need to have the same or newer macOS version as the one used for building
+- for other OSes, there are likely similar limitations
+
+If you don't find something working on your system, check the older borg releases.
+
+*.asc are GnuPG signatures - only provided for locally built binaries.
+*.exe (or no extension) is the single-file fat binary.
+*.tgz is the single-directory fat binary (extract it once with tar -xzf).
+
+Using the single-directory build is faster and does not require as much space
+in the temporary directory as the self-extracting single-file build.
+
+macOS: to avoid issues, download the file via the command line OR remove the
+       "quarantine" attribute after downloading:
+       $ xattr -dr com.apple.quarantine borg-macos1012.tgz
+
+
+Download the correct files
+--------------------------
+
+Binaries built on GitHub servers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+borg-linux-glibc235-x86_64-gh Linux AMD/Intel (built on Ubuntu 22.04 LTS with glibc 2.35)
+borg-linux-glibc235-arm64-gh  Linux ARM (built on Ubuntu 22.04 LTS with glibc 2.35)
+
+borg-macos-15-arm64-gh        macOS Apple Silicon (built on macOS 15 w/o FUSE support)
+borg-macos-15-x86_64-gh       macOS Intel (built on macOS 15 w/o FUSE support)
+
+borg-freebsd-14-x86_64-gh     FreeBSD AMD/Intel (built on FreeBSD 14)
+
+Binaries built locally
+~~~~~~~~~~~~~~~~~~~~~~
+
+borg-linux-glibc231-x86_64 Linux (built on Debian 11 "Bullseye" with glibc 2.31)
+
+Note: if you don't find a specific binary here, check release 1.4.1 or 1.2.9.
+
+
+Verifying your download
+-----------------------
+
+I provide GPG signatures for files which I have built locally on my machines.
+
+To check the GPG signature, download both the file and the corresponding
+signature (*.asc file) and then (on the shell) type, for example:
+
+    gpg --recv-keys 9F88FB52FAF7B393
+    gpg --verify borgbackup.tar.gz.asc borgbackup.tar.gz
+
+The files are signed by:
+
+Thomas Waldmann <tw@waldmann-edv.de>
+GPG key fingerprint: 6D5B EF9A DD20 7580 5747 B70F 9F88 FB52 FAF7 B393
+
+My fingerprint is also in the footer of all my BorgBackup mailing list posts.
+
+
+Provenance attestations for GitHub-built binaries
+-------------------------------------------------
+
+For binaries built on GitHub (files with a "-gh" suffix in the name), we publish
+an artifact provenance attestation that proves the binary was built by our
+GitHub Actions workflow from a specific commit or tag. You can verify this using
+the GitHub CLI (gh). Install it from https://cli.github.com/ and make sure you
+use a recent version that supports "gh attestation".
+
+Practical example (Linux, 1.4.3 tag):
+
+    curl -LO https://github.com/borgbackup/borg/releases/download/1.4.3/borg-linux-glibc235-x86_64-gh
+    gh attestation verify --repo borgbackup/borg --source-ref refs/tags/1.4.3 borg-linux-glibc235-x86_64-gh
+
+If verification succeeds, gh prints a summary stating the subject (your file),
+that it was attested by GitHub Actions, and the job/workflow reference.
+
+
+Installing
+----------
+
+It is suggested that you rename or symlink the binary to just "borg".
+If you need "borgfs", just also symlink it to the same binary, it will
+detect internally under which name it was invoked.
+
+On UNIX-like platforms, /usr/local/bin/ or ~/bin/ is a nice place for it,
+but you can invoke it from anywhere by providing the full path to it.
+
+Make sure the file is readable and executable (chmod +rx borg on UNIX-like
+platforms).
+
+
+Reporting issues
+----------------
+
+Please first check the FAQ and whether a GitHub issue already exists.
+
+If you find a NEW issue, please open a ticket on our issue tracker:
+
+https://github.com/borgbackup/borg/issues/
+
+There, please give:
+- the version number (it is displayed if you invoke borg -V)
+- the sha256sum of the binary
+- a good description of what the issue is
+- a good description of how to reproduce your issue
+- a traceback with system info (if you have one)
+- your precise platform (CPU, 32/64-bit?), OS, distribution, release
+- your Python and (g)libc versions

docs/book.rst

@@ -5,7 +5,7 @@
 Borg documentation
 ==================
 
-.. when you add an element here, do not forget to add it to index.rst
+.. When you add an element here, do not forget to add it to index.rst.
 .. Note: Some things are in appendices (see latex_appendices in conf.py)
 
 .. toctree::

docs/borg_theme/css/borg.css

@@ -52,8 +52,7 @@ h1 {
 }
 
 .container.experimental,
-#debugging-facilities,
+#debugging-facilities {
-#borg-recreate {
     /* don't change text dimensions */
     margin: 0 -30px; /* padding below + border width */
     padding: 0 10px; /* 10 px visual margin between edge of text and the border */
@@ -123,10 +122,26 @@ table.docutils.borg-options-table tr td:first-child:not([colspan="3"]) {
     margin: 0;
 }
 
-.borg-options-table {
+.borg-options-table,
+.borg-encryption-table {
     width: 100%;
 }
 
+.borg-encryption-table th {
+    text-align: center;
+}
+
+.borg-encryption-table th,
+.borg-encryption-table td {
+    vertical-align: top;
+}
+
+.borg-encryption-table .literal {
+    display: block;
+    margin: 0;
+    white-space: normal;
+}
+
 kbd, /* used in usage pages for options */
 code,
 .rst-content tt.literal,
@@ -179,3 +194,45 @@ cite {
 #common-options .option {
     white-space: nowrap;
 }
+/* Remove the right-column max-width cap so content fills the full available width. */
+#right-column {
+    max-width: none;
+}
+/* Hide the default RTD flyout since we show the version selector in the sidebar. */
+readthedocs-flyout {
+    display: none !important;
+}
+/* Version selector in the sidebar. */
+.version-selector {
+    padding: 0 22px;
+    margin: 7px 0 7px 0;
+    font-size: 14px;
+}
+.version-selector label {
+    display: block;
+    margin-bottom: 4px;
+    color: #000;
+}
+.version-selector select {
+    width: 100%;
+    padding: 4px;
+    background-color: #fafafa;
+    color: #000;
+    border: 1px solid #ccc;
+    border-radius: 3px;
+}
+.version-selector::after {
+    content: '';
+    display: block;
+    border-top: 1px solid #ccc;
+    margin: 7px 0 0 0;
+}
+/* Reduce top and bottom margin of searchbox block to 7px to match separator spacing. */
+.sidebar-block:has(#main-search) {
+    margin-top: 7px;
+    margin-bottom: 7px;
+}
+/* Reduce the separator margin below the search block to 7px. */
+.sphinxsidebar > .sidebar-block:has(#main-search):after {
+    margin: 7px 22px 0 22px;
+}

docs/conf.py

@@ -12,8 +12,10 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-import sys, os
+import sys
-sys.path.insert(0, os.path.abspath('../src'))
+import os
+
+sys.path.insert(0, os.path.abspath("../src"))
 
 from borg import __version__ as sw_version
 
@@ -40,7 +42,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'Borg - Deduplicating Archiver'
-copyright = u'2010-2014 Jonas Borgström, 2015-2022 The Borg Collective (see AUTHORS file)'
+copyright = '2010-2014 Jonas Borgström, 2015-2025 The Borg Collective (see AUTHORS file)'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -111,6 +113,7 @@ def set_rst_settings(app):
 
 
 def setup(app):
+    app.setup_extension('sphinxcontrib.jquery')
     app.add_css_file('css/borg.css')
     app.connect('builder-inited', set_rst_settings)
 
@@ -154,10 +157,11 @@ html_last_updated_fmt = '%Y-%m-%d'
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 html_use_smartypants = True
+smartquotes_action = 'qe'  # no D in there means "do not transform -- and ---"
 
 # Custom sidebar templates, maps document names to template names.
 html_sidebars = {
-    '**': ['logo-text.html', 'searchbox.html', 'globaltoc.html'],
+    '**': ['logo-text.html', "versionselector.html", 'searchbox.html', 'globaltoc.html'],
 }
 
 # Additional templates that should be rendered to pages, maps page names to
@@ -255,9 +259,11 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
+    'sphinxcontrib.jquery',  # jquery is not included anymore by default
+    'guzzle_sphinx_theme',  # register the theme as an extension to generate a sitemap.xml
 ]
 
 extlinks = {
-    'issue': ('https://github.com/borgbackup/borg/issues/%s', '#'),
+    'issue': ('https://github.com/borgbackup/borg/issues/%s', '#%s'),
     'targz_url': ('https://pypi.python.org/packages/source/b/borgbackup/%%s-%s.tar.gz' % version, None),
 }

docs/deployment.rst

@@ -14,3 +14,4 @@ This chapter details deployment strategies for the following scenarios.
    deployment/automated-local
    deployment/image-backup
    deployment/pull-backup
+   deployment/non-root-user

docs/deployment/automated-local.rst

@@ -14,8 +14,8 @@ systemd and udev.
 Overview
 --------
 
-An udev rule is created to trigger on the addition of block devices. The rule contains a tag
+A udev rule is created to trigger on the addition of block devices. The rule contains a tag
-that triggers systemd to start a oneshot service. The oneshot service executes a script in
+that causes systemd to start a oneshot service. The oneshot service executes a script in
 the standard systemd service environment, which automatically captures stdout/stderr and
 logs it to the journal.
 
@@ -29,30 +29,16 @@ Configuring the system
 First, create the ``/etc/backups`` directory (as root).
 All configuration goes into this directory.
 
-Then, create ``/etc/backups/40-backup.rules`` with the following content (all on one line)::
+Find out the ID of the partition table of your backup disk (here assumed to be /dev/sdz):
+    lsblk --fs -o +PTUUID /dev/sdz
 
-    ACTION=="add", SUBSYSTEM=="bdi", DEVPATH=="/devices/virtual/bdi/*",
+Then, create ``/etc/backups/80-backup.rules`` with the following content (all on one line)::
-    TAG+="systemd", ENV{SYSTEMD_WANTS}="automatic-backup.service"
 
-.. topic:: Finding a more precise udev rule
+    ACTION=="add", SUBSYSTEM=="block", ENV{ID_PART_TABLE_UUID}=="<the PTUUID you just noted>", TAG+="systemd", ENV{SYSTEMD_WANTS}+="automatic-backup.service"
 
-    If you always connect the drive(s) to the same physical hardware path, e.g. the same
+The "systemd" tag in conjunction with the SYSTEMD_WANTS environment variable causes systemd to
-    eSATA port, then you can make a more precise udev rule.
+launch the "automatic-backup" service, which we will create next, as the file
-
+``/etc/backups/automatic-backup.service``:
-    Execute ``udevadm monitor`` and connect a drive to the port you intend to use.
-    You should see a flurry of events, find those regarding the `block` subsystem.
-    Pick the event whose device path ends in something similar to a device file name,
-    typically`sdX/sdXY`. Use the event's device path and replace `sdX/sdXY` after the
-    `/block/` part in the path with a star (\*). For example:
-    `DEVPATH=="/devices/pci0000:00/0000:00:11.0/ata3/host2/target2:0:0/2:0:0:0/block/*"`.
-
-    Reboot a few times to ensure that the hardware path does not change: on some motherboards
-    components of it can be random. In these cases you cannot use a more accurate rule,
-    or need to insert additional stars for matching the path.
-
-The "systemd" tag in conjunction with the SYSTEMD_WANTS environment variable has systemd
-launch the "automatic-backup" service, which we will create next, as the
-``/etc/backups/automatic-backup.service`` file:
 
 .. code-block:: ini
 
@@ -79,13 +65,13 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
     # Script configuration
     #
 
-    # The backup partition is mounted there
+    # The backup partition is mounted here
     MOUNTPOINT=/mnt/backup
 
     # This is the location of the Borg repository
     TARGET=$MOUNTPOINT/borg-backups/backup.borg
 
-    # Archive name schema
+    # Archive name scheme
     DATE=$(date --iso-8601)-$(hostname)
 
     # This is the file that will later contain UUIDs of registered backup drives
@@ -107,10 +93,10 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
 
     echo "Disk $uuid is a backup disk"
     partition_path=/dev/disk/by-uuid/$uuid
-    # Mount file system if not already done. This assumes that if something is already
+    # Mount the file system if not already done. This assumes that if something is already
     # mounted at $MOUNTPOINT, it is the backup drive. It won't find the drive if
     # it was mounted somewhere else.
-    (mount | grep $MOUNTPOINT) || mount $partition_path $MOUNTPOINT
+    findmnt $MOUNTPOINT >/dev/null || mount $partition_path $MOUNTPOINT
     drive=$(lsblk --inverse --noheadings --list --paths --output name $partition_path | head --lines 1)
     echo "Drive path: $drive"
 
@@ -136,8 +122,8 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
 
     # This is just an example, change it however you see fit
     borg create $BORG_OPTS \
-      --exclude /root/.cache \
+      --exclude root/.cache \
-      --exclude /var/lib/docker/devicemapper \
+      --exclude var/lib/docker/devicemapper \
       $TARGET::$DATE-$$-system \
       / /boot
 
@@ -145,7 +131,7 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
     # Even if it isn't (add --exclude /home above), it probably makes sense
     # to have /home in a separate archive.
     borg create $BORG_OPTS \
-      --exclude 'sh:/home/*/.cache' \
+      --exclude 'sh:home/*/.cache' \
       $TARGET::$DATE-$$-home \
       /home/
 
@@ -164,7 +150,7 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
     fi
 
 Create the ``/etc/backups/autoeject`` file to have the script automatically eject the drive
-after creating the backup. Rename the file to something else (e.g. ``/etc/backup/autoeject-no``)
+after creating the backup. Rename the file to something else (e.g. ``/etc/backups/autoeject-no``)
 when you want to do something with the drive after creating backups (e.g running check).
 
 Create the ``/etc/backups/backup-suspend`` file if the machine should suspend after completing
@@ -178,7 +164,7 @@ The last part is to actually enable the udev rules and services:
 
 .. code-block:: bash
 
-    ln -s /etc/backups/40-backup.rules /etc/udev/rules.d/40-backup.rules
+    ln -s /etc/backups/80-backup.rules /etc/udev/rules.d/80-backup.rules
     ln -s /etc/backups/automatic-backup.service /etc/systemd/system/automatic-backup.service
     systemctl daemon-reload
     udevadm control --reload
@@ -191,7 +177,7 @@ Find the UUID of the file system that backups should be stored on::
 
     lsblk -o+uuid,label
 
-Note the UUID into the ``/etc/backup/backup.disks`` file.
+Note the UUID into the ``/etc/backups/backup.disks`` file.
 
 Mount the drive to /mnt/backup.
 
@@ -212,7 +198,7 @@ Security considerations
 -----------------------
 
 The script as shown above will mount any file system with an UUID listed in
-``/etc/backup/backup.disks``. The UUID check is a safety / annoyance-reduction
+``/etc/backups/backup.disks``. The UUID check is a safety / annoyance-reduction
 mechanism to keep the script from blowing up whenever a random USB thumb drive is connected.
 It is not meant as a security mechanism. Mounting file systems and reading repository
 data exposes additional attack surfaces (kernel file system drivers,

docs/deployment/central-backup-server.rst

@@ -4,20 +4,20 @@
 Central repository server with Ansible or Salt
 ==============================================
 
-This section will give an example how to setup a borg repository server for multiple
+This section gives an example of how to set up a Borg repository server for multiple
 clients.
 
 Machines
 --------
 
 There are multiple machines used in this section and will further be named by their
-respective fully qualified domain name (fqdn).
+respective fully qualified domain name (FQDN).
 
 * The backup server: `backup01.srv.local`
 * The clients:
 
   - John Doe's desktop: `johndoe.clnt.local`
-  - Webserver 01: `web01.srv.local`
+  - Web server 01: `web01.srv.local`
   - Application server 01: `app01.srv.local`
 
 User and group
@@ -28,7 +28,7 @@ Recommended user and group with additional settings:
 
 * User: `backup`
 * Group: `backup`
-* Shell: `/bin/bash` (or other capable to run the `borg serve` command)
+* Shell: `/bin/bash` (or another capable of running the `borg serve` command)
 * Home: `/home/backup`
 
 Most clients shall initiate a backup from the root user to catch all
@@ -79,11 +79,11 @@ The options which are added to the key will perform the following:
 3. Restrict ssh and do not allow stuff which imposes a security risk
 
 Due to the ``cd`` command we use, the server automatically changes the current
-working directory. Then client doesn't need to have knowledge of the absolute
+working directory. The client doesn't need to have knowledge of the absolute
 or relative remote repository path and can directly access the repositories at
-``<user>@<host>:<repo>``.
+``ssh://<user>@<host>/./<repo>``.
 
-.. note:: The setup above ignores all client given commandline parameters
+.. note:: The setup above ignores all client-given command-line parameters
           which are normally appended to the `borg serve` command.
 
 Client
@@ -93,21 +93,21 @@ The client needs to initialize the `pictures` repository like this:
 
 ::
 
- borg init backup@backup01.srv.local:pictures
+ borg init ssh://backup@backup01.srv.local/./pictures
 
-Or with the full path (should actually never be used, as only for demonstrational purposes).
+Or with the full path (should actually never be used, as only for demonstration purposes).
-The server should automatically change the current working directory to the `<client fqdn>` folder.
+The server should automatically change the current working directory to the `<client FQDN>` folder.
 
 ::
 
-  borg init backup@backup01.srv.local:/home/backup/repos/johndoe.clnt.local/pictures
+  borg init ssh://backup@backup01.srv.local/home/backup/repos/johndoe.clnt.local/pictures
 
-When `johndoe.clnt.local` tries to access a not restricted path the following error is raised.
+When `johndoe.clnt.local` tries to access an unrestricted path, the following error is raised.
 John Doe tries to backup into the Web 01 path:
 
 ::
 
-  borg init backup@backup01.srv.local:/home/backup/repos/web01.srv.local/pictures
+  borg init ssh://backup@backup01.srv.local/home/backup/repos/web01.srv.local/pictures
 
 ::
 

docs/deployment/hosting-repositories.rst

@@ -5,11 +5,11 @@
 Hosting repositories
 ====================
 
-This sections shows how to securely provide repository storage for users.
+This section shows how to securely provide repository storage for users.
 Optionally, each user can have a storage quota.
 
 Repositories are accessed through SSH. Each user of the service should
-have her own login which is only able to access the user's files.
+have their own login which is only able to access the user's files.
 Technically it would be possible to have multiple users share one login,
 however, separating them is better. Separate logins increase isolation
 and are thus an additional layer of security and safety for both the

docs/deployment/image-backup.rst

@@ -8,6 +8,38 @@ Backing up disk images can still be efficient with Borg because its `deduplicati
 technique makes sure only the modified parts of the file are stored. Borg also has
 optional simple sparse file support for extract.
 
+It is of utmost importance to pin down the disk you want to back up.
+You need to use the SERIAL for that.
+Use:
+
+.. code-block:: bash
+
+    # You can find the short disk serial by:
+    # udevadm info --query=property --name=nvme1n1 | grep ID_SERIAL_SHORT | cut -d '=' -f 2
+
+    DISK_SERIAL="7VS0224F"
+    DISK_ID=$(readlink -f /dev/disk/by-id/*"${DISK_SERIAL}") # Returns /dev/nvme1n1
+
+    mapfile -t PARTITIONS < <(lsblk -o NAME,TYPE -p -n -l "$DISK_ID" | awk '$2 == "part" {print $1}')
+    echo "Partitions of $DISK_ID:"
+    echo "${PARTITIONS[@]}"
+    echo "Disk Identifier: $DISK_ID"
+
+    # Use the following line to perform a borg backup for the full disk:
+    # borg create --read-special /path/to/repo::{now} "$DISK_ID"
+
+    # Use the following to perform a borg backup for all partitions of the disk
+    # borg create --read-special /path/to/repo::{now} "${PARTITIONS[@]}"
+
+    # Example output:
+    # Partitions of /dev/nvme1n1:
+    # /dev/nvme1n1p1
+    # /dev/nvme1n1p2
+    # /dev/nvme1n1p3
+    # Disk Identifier: /dev/nvme1n1
+    # borg create --read-special /path/to/repo::{now} /dev/nvme1n1
+    # borg create --read-special /path/to/repo::{now} /dev/nvme1n1p1 /dev/nvme1n1p2 /dev/nvme1n1p3
+
 Decreasing the size of image backups
 ------------------------------------
 
@@ -33,7 +65,7 @@ deduplicating. For backup, save the disk header and the contents of each partiti
         PARTNUM=$(echo $x | grep -Eo "[0-9]+$")
         ntfsclone -so - $x | borg create repo::hostname-part$PARTNUM -
     done
-    # to backup non-NTFS partitions as well:
+    # to back up non-NTFS partitions as well:
     echo "$PARTITIONS" | grep -v NTFS | cut -d' ' -f1 | while read x; do
         PARTNUM=$(echo $x | grep -Eo "[0-9]+$")
         borg create --read-special repo::hostname-part$PARTNUM $x
@@ -116,4 +148,4 @@ way to create application-consistent backups.
 
 Borg doesn't intend to address these issues due to their huge complexity and
 platform/software dependency. Combining Borg with the mechanisms provided by the platform
-(snapshots, hypervisor features) will be the best approach to start tackling them.
+(snapshots, hypervisor features) will be the best approach to start tackling them.

docs/deployment/non-root-user.rst

@@ -0,0 +1,66 @@
+.. include:: ../global.rst.inc
+.. highlight:: none
+.. _non_root_user:
+
+================================
+Backing up using a non-root user
+================================
+
+This section describes how to run Borg as a non-root user and still be able to
+back up every file on the system.
+
+Normally Borg is run as the root user to bypass all filesystem permissions and
+be able to read all files. But in theory this also allows Borg to modify or
+delete files on your system, in case of a bug, for example.
+
+To eliminate this possibility, we can run Borg as a non-root user and give it read-only
+permissions to all files on the system.
+
+
+Using Linux capabilities inside a systemd service
+=================================================
+
+One way to do so is to use Linux `capabilities
+<https://man7.org/linux/man-pages/man7/capabilities.7.html>`_ within a systemd
+service.
+
+Linux capabilities allow us to give some of the privileges that the root user has to
+a non-root user. This works on a per-thread level and does not grant these permissions
+to the non-root user as a whole.
+
+For this, we need to run our backup script from a systemd service and use the `AmbientCapabilities
+<https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#AmbientCapabilities=>`_
+option added in systemd 229.
+
+A very basic unit file would look like this:
+
+::
+
+    [Unit]
+    Description=Borg Backup
+
+    [Service]
+    Type=oneshot
+    User=borg
+    ExecStart=/usr/local/sbin/backup.sh
+
+    AmbientCapabilities=CAP_DAC_READ_SEARCH
+
+The ``CAP_DAC_READ_SEARCH`` capability gives Borg read-only access to all files and directories on the system.
+
+This service can then be started manually using ``systemctl start``, a systemd timer or other methods.
+
+Restore considerations
+======================
+
+When restoring files, the root user should be used. When using the non-root user, borg extract will
+change all files to be owned by the non-root user. Using borg mount will not allow the non-root user
+to access files that it would not have access to on the system itself.
+
+Other than that, the same restore process that would be used when running the backup as root can be used.
+
+.. warning::
+
+    When using a local repo and running borg commands as root, make sure to only use commands that do not
+    modify the repo itself, like extract or mount. Modifying the repo using the root user will break
+    the repo for the non-root user, since some files inside the repo will now be owned by root.

docs/deployment/pull-backup.rst

@@ -6,20 +6,20 @@
 Backing up in pull mode
 =======================
 
-Typically the borg client connects to a backup server using SSH as a transport
+Typically the Borg client connects to a backup server using SSH as a transport
 when initiating a backup. This is referred to as push mode.
 
-If you however require the backup server to initiate the connection or prefer
+If, however, you require the backup server to initiate the connection or prefer
 it to initiate the backup run, one of the following workarounds is required to
 allow such a pull mode setup.
 
-A common use case for pull mode is to backup a remote server to a local personal
+A common use case for pull mode is to back up a remote server to a local personal
 computer.
 
 SSHFS
 =====
 
-Assuming you have a pull backup system set up with borg, where a backup server
+Assuming you have a pull backup system set up with Borg, where a backup server
 pulls the data from the target via SSHFS. In this mode, the backup client's file
 system is mounted remotely on the backup server. Pull mode is even possible if
 the SSH connection must be established by the client via a remote tunnel. Other
@@ -58,13 +58,13 @@ completely in every aspect from such a backup.
     mappings, assuming they only come from files (/etc/passwd and group).
     This assumption might be wrong, e.g. if users/groups also come from
     ldap or other providers.
-    Thus, it might be better to use ``--numeric-owner`` and not archive any
+    Thus, it might be better to use ``--numeric-ids`` and not archive any
     user or group names (but just the numeric IDs) and not use chroot.
 
 Creating a backup
 -----------------
 
-Generally, in a pull backup situation there is no direct way for borg to know
+Generally, in a pull backup situation there is no direct way for Borg to know
 the client's original UID:GID name mapping of files, because Borg would use
 ``/etc/passwd`` and ``/etc/group`` of the backup server to map the names. To
 derive the right names, Borg needs to have access to the client's passwd and
@@ -72,7 +72,7 @@ group files and use them in the backup process.
 
 The solution to this problem is chrooting into an sshfs mounted directory. In
 this example the whole client root file system is mounted. We use the
-stand-alone BorgBackup executable and copy it into the mounted file system to
+standalone BorgBackup executable and copy it into the mounted file system to
 make Borg available after entering chroot; this can be skipped if Borg is
 already installed on the client.
 
@@ -98,9 +98,9 @@ create the backup, retaining the original paths, excluding the repository:
 
 ::
 
-    borg create --exclude /borgrepo --files-cache ctime,size /borgrepo::archive /
+    borg create --exclude borgrepo --files-cache ctime,size /borgrepo::archive /
 
-For the sake of simplicity only ``/borgrepo`` is excluded here. You may want to
+For the sake of simplicity only ``borgrepo`` is excluded here. You may want to
 set up an exclude file with additional files and folders to be excluded. Also
 note that we have to modify Borg's file change detection behaviour – SSHFS
 cannot guarantee stable inode numbers, so we have to supply the
@@ -181,13 +181,13 @@ When doing a full restore, we restore all files (including the ones containing
 the ID-to-name mapping, ``/etc/passwd`` and ``/etc/group``). Everything will be
 consistent automatically if we restore the numeric IDs stored in the archive. So
 there is no need for a chroot environment; we just mount the client file system
-and extract a backup, utilizing the ``--numeric-owner`` option:
+and extract a backup, utilizing the ``--numeric-ids`` option:
 
 ::
 
     sshfs root@host:/ /mnt/sshfs
     cd /mnt/sshfs
-    borg extract --numeric-owner /path/to/repo::archive
+    borg extract --numeric-ids /path/to/repo::archive
     cd ~
     umount /mnt/sshfs
 

docs/development.rst

@@ -19,7 +19,7 @@ Some guidance for contributors:
 
 - Discuss changes on the GitHub issue tracker, on IRC or on the mailing list.
 
-- Make your PRs on the ``master`` branch (see `Branching Model`_ for details).
+- Make your PRs on the ``master`` branch (see `Branching Model`_ for details and exceptions).
 
 - Do clean changesets:
 
@@ -52,8 +52,8 @@ Borg development happens on the ``master`` branch and uses GitHub pull
 requests (if you don't have GitHub or don't want to use it you can
 send smaller patches via the borgbackup mailing list to the maintainers).
 
-Stable releases are maintained on maintenance branches named ``x.y-maint``, eg.
+Stable releases are maintained on maintenance branches named ``x.y-maint``, e.g.
-the maintenance branch of the 1.0.x series is ``1.0-maint``.
+the maintenance branch of the 1.4.x series is ``1.4-maint``.
 
 Most PRs should be filed against the ``master`` branch. Only if an
 issue affects **only** a particular maintenance branch a PR should be
@@ -131,12 +131,9 @@ you run the tests.
 Continuous Integration
 ----------------------
 
-All pull requests go through `GitHub Actions`_, which runs the tests on Linux
+All pull requests go through `GitHub Actions`_, which runs the tests on misc.
-and Mac OS X as well as the flake8 style checker. Windows builds run on AppVeyor_,
+Python versions and on misc. platforms as well as some additional checks.
-while additional Unix-like platforms are tested on Golem_.
 
-.. _AppVeyor: https://ci.appveyor.com/project/borgbackup/borg/
-.. _Golem: https://golem.enkore.de/view/Borg/
 .. _GitHub Actions: https://github.com/borgbackup/borg/actions
 
 Output and Logging
@@ -164,6 +161,12 @@ virtual env and run::
   pip install -r requirements.d/development.txt
 
 
+This project utilizes pre-commit to lint code before it is committed.
+Although pre-commit is installed when running the command above, the pre-commit hooks
+will have to be installed separately. Run this command to install the pre-commit hooks::
+
+  pre-commit install
+
 Running the tests
 -----------------
 
@@ -171,7 +174,7 @@ The tests are in the borg/testsuite package.
 
 To run all the tests, you need to have fakeroot installed. If you do not have
 fakeroot, you still will be able to run most tests, just leave away the
-`fakeroot -u` from the given command lines.
+``fakeroot -u`` from the given command lines.
 
 To run the test suite use the following command::
 
@@ -182,7 +185,7 @@ Some more advanced examples::
   # verify a changed tox.ini (run this after any change to tox.ini):
   fakeroot -u tox --recreate
 
-  fakeroot -u tox -e py38  # run all tests, but only on python 3.8
+  fakeroot -u tox -e py310  # run all tests, but only on python 3.10
 
   fakeroot -u tox borg.testsuite.locking  # only run 1 test module
 
@@ -194,26 +197,36 @@ Important notes:
 
 - When using ``--`` to give options to py.test, you MUST also give ``borg.testsuite[.module]``.
 
+Running the tests (using the pypi package)
+------------------------------------------
 
-Running more checks using coala
+Since borg 1.4, it is also possible to run the tests without a development
--------------------------------
+environment, using the borgbackup dist package (downloaded from pypi.org or
-
+github releases page):
-First install coala and some checkers ("bears"):
-
 ::
 
-  pip install -r requirements.d/coala.txt
+    # optional: create and use a virtual env:
+    python3 -m venv env
+    . env/bin/activate
 
-You can now run coala from the toplevel directory; it will read its settings
+    # install packages
-from ``.coafile`` there:
+    pip install borgbackup
+    pip install pytest pytest-benchmark
 
-::
+    # method A: use a pytest.ini
 
-  coala
+    cat >pytest.ini <<<EOF
+    [pytest]
+    python_files = testsuite/*.py
+    markers = allow_cache_wipe
+    addopts = -rs --benchmark-skip
+    EOF
 
-Some bears have additional requirements and they usually tell you about
+    pytest --pyargs borg.testsuite
-them in case they are missing.
 
+    # method B: give the options via the cmdline (each time you invoke the tests):
+
+    pytest -rs --benchmark-skip -o 'python_files=testsuite/*.py' -o 'markers=allow_cache_wipe' --pyargs borg.testsuite
 
 Adding a compression algorithm
 ------------------------------
@@ -236,8 +249,8 @@ for easier use by packagers downstream.
 When a command is added, a command line flag changed, added or removed,
 the usage docs need to be rebuilt as well::
 
-  python setup.py build_usage
+  python scripts/make.py build_usage
-  python setup.py build_man
+  python scripts/make.py build_man
 
 However, we prefer to do this as part of our :ref:`releasing`
 preparations, so it is generally not necessary to update these when
@@ -291,6 +304,49 @@ Usage::
    # To copy files from the VM (in this case, the generated binary):
    vagrant scp OS:/vagrant/borg/borg.exe .
 
+Using Podman
+------------
+
+macOS-based developers (and others who prefer containers) can run the Linux test suite locally using Podman.
+
+Prerequisites:
+
+-   Install Podman (e.g., ``brew install podman``).
+-   Initialize the Podman machine, only once: ``podman machine init``.
+-   Start the Podman machine, before using it: ``podman machine start``.
+
+Usage::
+
+    # Open an interactive shell in the container (default if no command given):
+    ./scripts/linux-run
+
+    # Run the default tox environment:
+    ./scripts/linux-run tox
+
+    # Run a specific tox environment:
+    ./scripts/linux-run tox -e py311-pyfuse3
+
+    # Pass arguments to pytest (e.g., run specific tests):
+    ./scripts/linux-run tox -e py313-pyfuse3 -- -k mount
+
+    # Switch base image (temporarily):
+    ./scripts/linux-run --image python:3.11-bookworm tox
+
+Resource Usage
+~~~~~~~~~~~~~~
+
+The default Podman VM uses 2GB RAM and half your CPUs.
+For heavy tests (parallel execution), this might be tight.
+
+-   **Check usage:** Run ``podman stats`` in another terminal while tests are running.
+-   **Increase resources:**
+
+    ::
+
+        podman machine stop
+        podman machine set --cpus 6 --memory 4096
+        podman machine start
+
 
 Creating standalone binaries
 ----------------------------
@@ -310,7 +366,6 @@ If you encounter issues, see also our `Vagrantfile` for details.
           work on same OS, same architecture (x86 32bit, amd64 64bit)
           without external dependencies.
 
-
 .. _releasing:
 
 Creating a new release
@@ -326,12 +381,18 @@ Checklist:
 - Update ``CHANGES.rst``, based on ``git log $PREVIOUS_RELEASE..``.
 - Check version number of upcoming release in ``CHANGES.rst``.
 - Render ``CHANGES.rst`` via ``make html`` and check for markup errors.
-- Verify that ``MANIFEST.in`` and ``setup.py`` are complete.
+- Verify that ``MANIFEST.in``, ``pyproject.toml`` and ``setup.py`` are complete.
-- ``python setup.py build_usage ; python setup.py build_man`` and commit.
+- Run these commands, check git status for files that might need to be added, and commit::
+
+    python scripts/make.py build_usage
+    python scripts/make.py build_man
+
 - Tag the release::
 
     git tag -s -m "tagged/signed release X.Y.Z" X.Y.Z
 
+- Push the release PR branch to GitHub, make a pull request.
+- Also push the release tag.
 - Create a clean repo and use it for the following steps::
 
     git clone borg borg-clean
@@ -340,8 +401,9 @@ Checklist:
   It will also reveal uncommitted required files.
   Moreover, it makes sure the vagrant machines only get committed files and
   do a fresh start based on that.
-- Run tox and/or binary builds on all supported platforms via vagrant,
+- Optional: run tox and/or binary builds on all supported platforms via vagrant,
-  check for test failures.
+  check for test failures. This is now optional as we do platform testing and
+  binary building on GitHub.
 - Create sdist, sign it, upload release to (test) PyPi:
 
   ::
@@ -349,26 +411,32 @@ Checklist:
     scripts/sdist-sign X.Y.Z
     scripts/upload-pypi X.Y.Z test
     scripts/upload-pypi X.Y.Z
-- Put binaries into dist/borg-OSNAME and sign them:
 
-  ::
+  Note: the signature is not uploaded to PyPi any more, but we upload it to
+  github releases.
 
-    scripts/sign-binaries 201912312359
+- When GitHub CI looks good on the release PR, merge it and then check "Actions":
+  GitHub will create binary assets after the release PR is merged within the
+  CI testing of the merge. Check the "Upload binaries" step on Ubuntu (AMD/Intel
+  and ARM64) and macOS (Intel and ARM64), fetch the ZIPs with the binaries.
+- Unpack the ZIPs and test the binaries, upload the binaries to the GitHub
+  release page (borg-OS-SPEC-ARCH-gh and borg-OS-SPEC-ARCH-gh.tgz).
 - Close the release milestone on GitHub.
 - `Update borgbackup.org
   <https://github.com/borgbackup/borgbackup.github.io/pull/53/files>`_ with the
   new version number and release date.
 - Announce on:
 
- - Mailing list.
+  - Mailing list.
- - Twitter.
+  - Mastodon / BlueSky / X (aka Twitter).
- - IRC channel (change ``/topic``).
+  - IRC channel (change ``/topic``).
 
 - Create a GitHub release, include:
 
-  * Standalone binaries (see above for how to create them).
+  - pypi dist package and signature
+  - Standalone binaries (see above for how to create them).
 
-    + For OS X, document the OS X Fuse version in the README of the binaries.
+    - For macOS binaries **with** FUSE support, document the macFUSE version
-      OS X FUSE uses a kernel extension that needs to be compatible with the
+      in the README of the binaries. macFUSE uses a kernel extension that needs
-      code contained in the binary.
+      to be compatible with the code contained in the binary.
-  * A link to ``CHANGES.rst``.
+  - A link to ``CHANGES.rst``.

docs/faq.rst

@@ -45,6 +45,12 @@ repository is only modified from one place. Also keep in mind that
 Borg will keep an exclusive lock on the repository while creating
 or deleting archives, which may make *simultaneous* backups fail.
 
+Can I back up to multiple, swapped backup targets?
+--------------------------------------------------
+
+It is possible to swap your backup disks if each backup medium is assigned its
+own repository by creating a new one with :ref:`borg_init`.
+
 Can I copy or synchronize my repo to another location?
 ------------------------------------------------------
 
@@ -107,6 +113,9 @@ run into this by yourself by restoring an older copy of your repository.
 "attack": maybe an attacker has replaced your repo by an older copy, trying to
 trick you into AES counter reuse, trying to break your repo encryption.
 
+Borg users have also reported that fs issues (like hw issues / I/O errors causing
+the fs to become read-only) can cause this warning, see :issue:`7853`.
+
 If you'ld decide to ignore this and accept unsafe operation for this repository,
 you could delete the manifest-timestamp and the local cache:
 
@@ -201,15 +210,15 @@ sure you have an up-to-date version of borgbackup if you want to continue
 instead of retransferring a huge file. In some cases, there is only an outdated
 version shipped with your distribution (e.g. Debian). See :ref:`installation`.
 
-How can I backup huge file(s) over a unstable connection?
+How can I back up huge file(s) over an unstable connection?
----------------------------------------------------------
+-----------------------------------------------------------
 
 This is not a problem anymore.
 
 For more details, see :ref:`checkpoints_parts`.
 
 How can I switch append-only mode on and off?
------------------------------------------------------------------------------------------------------------------------------------
+---------------------------------------------
 
 You could do that (via borg config REPO append_only 0/1), but using different
 ssh keys and different entries in ``authorized_keys`` is much easier and also
@@ -219,8 +228,12 @@ maybe has less potential of things going wrong somehow.
 My machine goes to sleep causing `Broken pipe`
 ----------------------------------------------
 
-When backing up your data over the network, your machine should not go to sleep.
+While backing up your data over the network, your machine should not go to sleep.
-On macOS you can use `caffeinate` to avoid that.
+On Linux you can use `systemd-inhibit` to avoid that. On macOS you can use `caffeinate`.
+
+``systemd-inhibit borg create ...``
+
+``caffeinate -i borg create ...``
 
 How can I restore huge file(s) over an unstable connection?
 -----------------------------------------------------------
@@ -368,9 +381,7 @@ Checking processors
   operate hardware outside its specifications for productive use.
 
   Tools to verify correct processor operation include Prime95 (mprime), linpack,
-  and the `Intel Processor Diagnostic Tool
+  and stress-ng.
-  <https://downloadcenter.intel.com/download/19792/Intel-Processor-Diagnostic-Tool>`_
-  (applies only to Intel processors).
 
 .. rubric:: Repairing a damaged repository
 
@@ -429,18 +440,19 @@ How do I configure different prune policies for different directories?
 Say you want to prune ``/var/log`` faster than the rest of
 ``/``. How do we implement that? The answer is to backup to different
 archive *names* and then implement different prune policies for
-different prefixes. For example, you could have a script that does::
+different --glob-archives matching patterns.
 
-    borg create --exclude /var/log $REPOSITORY:main-$(date +%Y-%m-%d) /
+For example, you could have a script that does::
+
+    borg create --exclude var/log $REPOSITORY:main-$(date +%Y-%m-%d) /
     borg create $REPOSITORY:logs-$(date +%Y-%m-%d) /var/log
 
 Then you would have two different prune calls with different policies::
 
-    borg prune --verbose --list -d 30 --prefix main- "$REPOSITORY"
+    borg prune --verbose --list -d 30 --glob-archives 'main-*' "$REPOSITORY"
-    borg prune --verbose --list -d 7  --prefix logs- "$REPOSITORY"
+    borg prune --verbose --list -d 7  --glob-archives 'logs-*' "$REPOSITORY"
 
-This will keep 7 days of logs and 30 days of everything else. Borg 1.1
+This will keep 7 days of logs and 30 days of everything else.
-also supports the ``--glob-archives`` parameter.
 
 How do I remove files from an existing backup?
 ----------------------------------------------
@@ -468,6 +480,24 @@ will only be applied to new chunks, not existing chunks. So it's safe
 to change them.
 
 
+Why is backing up an unmodified FAT filesystem slow on Linux?
+-------------------------------------------------------------
+
+By default, the files cache used by BorgBackup considers the inode of files.
+When an inode number changes compared to the last backup, it hashes the file
+again. The ``vfat`` kernel driver does not produce stable inode numbers by
+default.  One way to achieve stable inode numbering is mounting the filesystem
+using ``nfs=nostale_ro``. Doing so implies mounting the filesystem read-only.
+Another option is to not consider inode numbers in the files cache by passing
+``--files-cache=ctime,size``.
+
+Why are backups slow on a Linux server that is a member of a Windows domain?
+----------------------------------------------------------------------------
+
+If a Linux server is a member of a Windows domain, username to userid resolution might be
+performed via ``winbind`` without caching, which can slow down backups significantly.
+You can use e.g. ``nscd`` to add caching and improve the speed.
+
 Security
 ########
 
@@ -514,14 +544,33 @@ The Borg config directory has content that you should take care of:
   recovered.
 
 ``keys`` subdirectory
-  All your borg keyfile keys are stored in this directory. Please note that
+  All your borg keyfile keys are stored in this directory. Please note that borg
-  borg repokey keys are stored inside the repository. You MUST make sure to have an
+  repokey keys are stored inside the repository. In any case, you MUST make sure
-  independent backup of these keyfiles, otherwise you cannot access your backups anymore if you lose
+  to have an independent backup of the borg keys, see :ref:`borg_key_export` for
-  them. You also MUST keep these files secret; everyone who gains access to your repository and has
+  more details.
-  the corresponding keyfile (and the key passphrase) can extract it.
 
 Make sure that only you have access to the Borg config directory.
 
+
+Note about creating multiple keyfile repositories at the same path
+------------------------------------------------------------------
+
+If you create a new keyfile-encrypted repository at the same filesystem
+path multiple times (for example, when a previous repository at that path
+was moved away or unmounted), Borg will not overwrite or reuse the existing
+key file in your keys directory. Instead, it creates a new key file by
+appending a numeric suffix to the base name (e.g., .2, .3, ...).
+
+This means you may see multiple key files like:
+
+- ~/.config/borg/keys/home_user_backup
+- ~/.config/borg/keys/home_user_backup.2
+- ~/.config/borg/keys/home_user_backup.3
+
+Each of these corresponds to a distinct repository created at the same
+path at different times. This behavior avoids accidental key reuse or
+overwrite.
+
 .. _cache_security:
 
 Do I need to take security precautions regarding the cache?
@@ -564,8 +613,7 @@ Using ``BORG_PASSCOMMAND`` with a properly permissioned file
   directory and use permissions to keep anyone else from reading it. For
   example, first create a key::
 
-    head -c 32 /dev/urandom | base64 -w 0 > ~/.borg-passphrase
+    (umask 0077; head -c 32 /dev/urandom | base64 -w 0 > ~/.borg-passphrase)
-    chmod 400 ~/.borg-passphrase
 
   Then in an automated script one can put::
 
@@ -655,7 +703,7 @@ all your files/dirs data and metadata are stored in their encrypted form
 into the repository.
 
 Yes, as an attacker with access to the remote server could delete (or
-otherwise make unavailable) all your backups.
+otherwise make unavailable) all your backups on that server.
 
 How can I protect against a hacked backup client?
 -------------------------------------------------
@@ -692,7 +740,7 @@ These are your options to protect against that:
 How can I protect against theft, sabotage, lightning, fire, ...?
 ----------------------------------------------------------------
 
-In general: if your only backup medium is nearby the backupped machine and
+In general: if your only backup medium is nearby the backed-up machine and
 always connected, you can easily get into trouble: they likely share the same
 fate if something goes really wrong.
 
@@ -727,7 +775,7 @@ Since the nonce is not necessary to read the data that is already encrypted,
 ``borg info``, ``borg list``, ``borg extract`` and ``borg mount`` should work
 just fine without it.
 
-If the the nonce file stored in the repo is lost, but you still have your local copy,
+If the nonce file stored in the repo is lost, but you still have your local copy,
 borg will recreate the repository nonce file the next time you run ``borg create``.
 This should be safe for repositories that are only used from one user account
 on one machine.
@@ -739,31 +787,34 @@ the nonce is deleted or if you suspect it may have been tampered with. See :ref:
 Common issues
 #############
 
-Why does Borg extract hang after some time?
+/path/to/repo is not a valid repository. Check repo config.
--------------------------------------------
+-----------------------------------------------------------
 
-When I do a ``borg extract``, after a while all activity stops, no cpu usage,
+There can be many causes of this error. E.g. you have incorrectly specified the repository path.
-no downloads.
 
-This may happen when the SSH connection is stuck on server side. You can
+You will also get this error if you try to access a repository that uses the argon2 key algorithm using an old version of borg.
-configure SSH on client side to prevent this by sending keep-alive requests,
+We recommend upgrading to the latest stable version and trying again. We are sorry. We should have thought about forward
-for example in ~/.ssh/config:
+compatibility and implemented a more helpful error message.
 
-::
+Why am I seeing idle borg serve processes on the repo server?
+-------------------------------------------------------------
 
-    Host borg.example.com
+Please see the next question.
-        # Client kills connection after 3*30 seconds without server response:
-        ServerAliveInterval 30
-        ServerAliveCountMax 3
 
-You can also do the opposite and configure SSH on server side in
+Why does Borg disconnect or hang when backing up to a remote server?
-/etc/ssh/sshd_config, to make the server send keep-alive requests to the client:
+--------------------------------------------------------------------
 
-::
+Communication with the remote server (using an ssh: repo URL) happens via an SSH
+connection. This can lead to some issues that would not occur during a local backup:
 
-    # Server kills connection after 3*30 seconds without client response:
+- Since Borg does not send data all the time, the connection may get closed, leading
-    ClientAliveInterval 30
+  to errors like "connection closed by remote".
-    ClientAliveCountMax 3
+- On the other hand, network issues may lead to a dysfunctional connection
+  that is only detected after some time by the server, leading to stale ``borg serve``
+  processes and locked repositories.
+
+To fix such problems, please apply these :ref:`SSH settings <ssh_configuration>` so that
+keep-alive requests are sent regularly.
 
 How can I deal with my very unstable SSH connection?
 ----------------------------------------------------
@@ -779,32 +830,6 @@ could try to work around:
   to do any more. Due to the way borg mount works, this might be less efficient
   than borg extract for bigger volumes of data.
 
-Why do I get "connection closed by remote" after a while?
----------------------------------------------------------
-
-When doing a backup to a remote server (using a ssh: repo URL), it sometimes
-stops after a while (some minutes, hours, ... - not immediately) with
-"connection closed by remote" error message. Why?
-
-That's a good question and we are trying to find a good answer in :issue:`636`.
-
-Why am I seeing idle borg serve processes on the repo server?
--------------------------------------------------------------
-
-Maybe the ssh connection between client and server broke down and that was not
-yet noticed on the server. Try these settings:
-
-::
-
-    # /etc/ssh/sshd_config on borg repo server - kill connection to client
-    # after ClientAliveCountMax * ClientAliveInterval seconds with no response
-    ClientAliveInterval 20
-    ClientAliveCountMax 3
-
-If you have multiple borg create ... ; borg create ... commands in a already
-serialized way in a single script, you need to give them ``--lock-wait N`` (with N
-being a bit more than the time the server needs to terminate broken down
-connections and release the lock).
 
 .. _disable_archive_chunks:
 
@@ -822,18 +847,8 @@ will make the subsequent rebuilds faster (because it needs to transfer less data
 from the repository). While being faster, the cache needs quite some disk space,
 which might be unwanted.
 
-There is a temporary (but maybe long lived) hack to avoid using lots of disk
+You can disable the cached archive chunk indexes by setting the environment
-space for chunks.archive.d (see :issue:`235` for details):
+variable ``BORG_USE_CHUNKS_ARCHIVE`` to ``no``.
-
-::
-
-    # this assumes you are working with the same user as the backup.
-    cd ~/.cache/borg/$(borg config /path/to/repo id)
-    rm -rf chunks.archive.d ; touch chunks.archive.d
-
-This deletes all the cached archive chunk indexes and replaces the directory
-that kept them with a file, so borg won't be able to store anything "in" there
-in future.
 
 This has some pros and cons, though:
 
@@ -863,6 +878,12 @@ Check if your encoding is set correctly. For most POSIX-like systems, try::
 
   export LANG=en_US.UTF-8  # or similar, important is correct charset
 
+If that does not help:
+
+- check for typos, check if you really used ``export``.
+- check if you have set ``LC_ALL`` - if so, try not setting it.
+- check if you generated the respective locale via ``locale-gen``.
+
 I can't extract non-ascii filenames by giving them on the commandline!?
 -----------------------------------------------------------------------
 
@@ -933,6 +954,24 @@ Then you do the backup and look at the log output:
   details and potential issues).
   You can use the ``stat`` command on files to manually look at fs metadata to debug if
   there is any unexpected change triggering the ``M`` status.
+  Also, the ``--debug-topic=files_cache`` option of ``borg create`` provides a lot of debug
+  output helping to analyse why the files cache does not give its expected high performance.
+
+When borg runs inside a virtual machine, there are some more things to look at:
+
+Some hypervisors (e.g. kvm on older proxmox) give some broadly compatible CPU type to the
+VM (usually to ease migration between VM hosts of potentially different hardware CPUs).
+
+It is broadly compatible because they leave away modern CPU features that could be
+not present in older or other CPUs, e.g. hardware acceleration for AES crypto, for
+sha2 hashes, for (P)CLMUL(QDQ) computations useful for crc32.
+
+So, basically you pay for compatibility with bad performance. If you prefer better
+performance, you should try to use the x86-64-v2-AES VCPU or the "host" VCPU,
+exposing misc. hw acceleration features to the VM which runs borg.
+
+On Linux, check ``/proc/cpuinfo`` for the CPU flags inside the VM.
+For kvm check the docs about "Host model" and "Host passthrough".
 
 See also the next few FAQ entries for more details.
 
@@ -1007,6 +1046,10 @@ will be slow because it would chunk all the files each time. If you set
 BORG_FILES_CACHE_TTL to at least 26 (or maybe even a small multiple of that),
 it would be much faster.
 
+Besides using a higher BORG_FILES_CACHE_TTL (which also increases memory usage),
+there is also BORG_FILES_CACHE_SUFFIX which can be used to have separate (smaller)
+files caches for each backup set instead of the default one (big) unified files cache.
+
 Another possible reason is that files don't always have the same path, for
 example if you mount a filesystem without stable mount points for each backup
 or if you are running the backup from a filesystem snapshot whose name is not
@@ -1020,6 +1063,32 @@ A workaround is to set the option ``--files-cache=ctime,size`` to exclude the in
 number comparison from the files cache check so that files with different inode
 numbers won't be treated as modified.
 
+Using a pure-python msgpack! This will result in lower performance.
+-------------------------------------------------------------------
+
+borg uses `msgpack` to serialize/deserialize data.
+
+`msgpack` has 2 implementations:
+
+- a fast one (C code compiled into a platform specific binary), and
+- a slow pure-python one.
+
+The slow one is used if it can't successfully import the fast one.
+
+If you use the pyinstaller-made borg "fat binary" which we offer on github
+releases, it could be that you downloaded a binary that does not match the
+(g)libc on your system.
+
+Binaries made for an older glibc than the one you have on your system usually
+just work, but the opposite is not necessarily the case and can lead to misc.
+issues - like failing to load the fast msgpack code or not working at all.
+
+So: try a binary made for an older glibc.
+
+If you see this without using a "fat binary" from us, it usually means that
+msgpack is not built / installed correctly. It could be also that the platform
+is not fully supported (so the python code works, but there is no fast binary
+code).
 
 Is there a way to limit bandwidth with Borg?
 --------------------------------------------
@@ -1178,10 +1247,58 @@ It may be useful to set ``BORG_RELOCATED_REPO_ACCESS_IS_OK=yes`` to avoid the
 prompts when renaming multiple repositories or in a non-interactive context
 such as a script. See :doc:`deployment` for an example.
 
+The repository quota size is reached, what can I do?
+----------------------------------------------------
+
+The simplest solution is to increase or disable the quota and resume the backup:
+
+::
+
+    borg config /path/to/repo storage_quota 0
+
+If you are bound to the quota, you have to free repository space. The first to
+try is running :ref:`borg_compact` to free unused backup space (see also
+:ref:`separate_compaction`):
+
+::
+
+    borg compact /path/to/repo
+
+If your repository is already compacted, run :ref:`borg_prune` or
+:ref:`borg_delete` to delete archives that you do not need anymore, and then run
+``borg compact`` again.
+
+My backup disk is full, what can I do?
+--------------------------------------
+
+Borg cannot work if you really have zero free space on the backup disk, so the
+first thing you must do is deleting some files to regain free disk space. See
+:ref:`about_free_space` for further details.
+
+Some Borg commands that do not change the repository might work under disk-full
+conditions, but generally this should be avoided. If your backup disk is already
+full when Borg starts a write command like `borg create`, it will abort
+immediately and the repository will stay as-is.
+
+If you run a backup that stops due to a disk running full, Borg will roll back,
+delete the new new segment file and thus freeing disk space automatically. There
+may be a checkpoint archive left that has been saved before the disk got full.
+You can keep it to speed up the next backup or delete it to get back more disk
+space.
 
 Miscellaneous
 #############
 
+macOS: borg mounts not shown in Finder's side bar
+-------------------------------------------------
+
+https://github.com/macfuse/macfuse/wiki/Mount-options#local
+
+Read the above first and use this on your own risk::
+
+    borg mount -olocal REPO MOUNTPOINT
+
+
 Requirements for the borg single-file binary, esp. (g)libc?
 -----------------------------------------------------------
 
@@ -1295,7 +1412,7 @@ There are some caveats:
 Why is my backup bigger than with attic?
 ----------------------------------------
 
-Attic was rather unflexible when it comes to compression, it always
+Attic was rather inflexible when it comes to compression, it always
 compressed using zlib level 6 (no way to switch compression off or
 adjust the level or algorithm).
 

docs/global.rst.inc

@@ -13,9 +13,9 @@
 .. _ACL: https://en.wikipedia.org/wiki/Access_control_list
 .. _libacl: https://savannah.nongnu.org/projects/acl/
 .. _libattr: https://savannah.nongnu.org/projects/attr/
+.. _libxxhash: https://github.com/Cyan4973/xxHash
 .. _liblz4: https://github.com/Cyan4973/lz4
 .. _libzstd: https://github.com/facebook/zstd
-.. _libb2: https://github.com/BLAKE2/libb2
 .. _OpenSSL: https://www.openssl.org/
 .. _`Python 3`: https://www.python.org/
 .. _Buzhash: https://en.wikipedia.org/wiki/Buzhash

docs/index.rst

@@ -6,7 +6,7 @@ Borg Documentation
 
 .. include:: ../README.rst
 
-.. when you add an element here, do not forget to add it to book.rst
+.. When you add an element here, do not forget to add it to book.rst.
 
 .. toctree::
    :maxdepth: 2

docs/installation.rst

@@ -42,7 +42,7 @@ package which can be installed with the package manager.
 Distribution Source                                        Command
 ============ ============================================= =======
 Alpine Linux `Alpine repository`_                          ``apk add borgbackup``
-Arch Linux   `[community]`_                                ``pacman -S borg``
+Arch Linux   `[extra]`_                                    ``pacman -S borg``
 Debian       `Debian packages`_                            ``apt install borgbackup``
 Gentoo       `ebuild`_                                     ``emerge borgbackup``
 GNU Guix     `GNU Guix`_                                   ``guix package --install borg``
@@ -63,9 +63,9 @@ Ubuntu       `Ubuntu packages`_, `Ubuntu PPA`_             ``apt install borgbac
 ============ ============================================= =======
 
 .. _Alpine repository: https://pkgs.alpinelinux.org/packages?name=borgbackup
-.. _[community]: https://www.archlinux.org/packages/?name=borg
+.. _[extra]: https://www.archlinux.org/packages/?name=borg
 .. _Debian packages: https://packages.debian.org/search?keywords=borgbackup&searchon=names&exact=1&suite=all&section=all
-.. _Fedora official repository: https://apps.fedoraproject.org/packages/borgbackup
+.. _Fedora official repository: https://packages.fedoraproject.org/pkgs/borgbackup/borgbackup/
 .. _FreeBSD ports: https://www.freshports.org/archivers/py-borgbackup/
 .. _ebuild: https://packages.gentoo.org/packages/app-backup/borgbackup
 .. _GNU Guix: https://www.gnu.org/software/guix/package-list.html#borg
@@ -78,7 +78,7 @@ Ubuntu       `Ubuntu packages`_, `Ubuntu PPA`_             ``apt install borgbac
 .. _Homebrew: https://formulae.brew.sh/formula/borgbackup
 .. _private Tap: https://github.com/borgbackup/homebrew-tap
 .. _Raspbian testing: https://archive.raspbian.org/raspbian/pool/main/b/borgbackup/
-.. _Ubuntu packages: https://packages.ubuntu.com/xenial/borgbackup
+.. _Ubuntu packages: https://launchpad.net/ubuntu/+source/borgbackup
 .. _Ubuntu PPA: https://launchpad.net/~costamagnagianfranco/+archive/ubuntu/borgbackup
 
 Please ask package maintainers to build a package or, if you can package /
@@ -105,22 +105,20 @@ Standalone Binary
 .. note:: Releases are signed with an OpenPGP key, see
           :ref:`security-contact` for more instructions.
 
-Borg x86/x64 amd/intel compatible binaries (generated with `pyinstaller`_)
+Borg x86-64 AMD/Intel-compatible binaries (generated with `pyinstaller`_)
-are available on the releases_ page for the following platforms:
+are available on the releases_ page for the following platforms (for more
+details see the ``00_README.txt`` file there):
 
-* **Linux**: glibc >= 2.28 (ok for most supported Linux releases).
+* Linux
-  Older glibc releases are untested and may not work.
+* FreeBSD
-* **MacOS**: 10.12 or newer (To avoid signing issues download the file via
+* MacOS
-  command line **or** remove the ``quarantine`` attribute after downloading:
-  ``$ xattr -dr com.apple.quarantine borg-macosx64.tgz``)
-* **FreeBSD**: 12.1 (unknown whether it works for older releases)
 
 ARM binaries are built by Johann Bauer, see: https://borg.bauerj.eu/
 
 To install such a binary, just drop it into a directory in your ``PATH``,
 make borg readable and executable for its users and then you can run ``borg``::
 
-    sudo cp borg-linux64 /usr/local/bin/borg
+    sudo cp borg-linux /usr/local/bin/borg
     sudo chown root:root /usr/local/bin/borg
     sudo chmod 755 /usr/local/bin/borg
 
@@ -157,30 +155,26 @@ Dependencies
 ~~~~~~~~~~~~
 
 To install Borg from a source package (including pip), you have to install the
-following dependencies first:
+following dependencies first. For the libraries you will also need their
+development header files (sometimes in a separate `-dev` or `-devel` package).
 
-* `Python 3`_ >= 3.8.0, plus development headers.
+* `Python 3`_ >= 3.10.0
-* OpenSSL_ >= 1.0.0, plus development headers.
+* OpenSSL_ >= 1.0.0
-* libacl_ (which depends on libattr_), both plus development headers.
+* libacl_ (which depends on libattr_)
-* We have bundled code of the following packages, but borg by default (see
+* libxxhash_ >= 0.8.1
-  setup.py if you want to change that) prefers a shared library if it can
+* liblz4_ >= 1.7.0 (r129)
-  be found on the system (lib + dev headers) at build time:
+* libzstd_ >= 1.3.0
-
+* pkg-config (cli tool) - Borg uses this to discover header and library
-  - liblz4_ >= 1.7.0 (r129)
+  locations automatically. Alternatively, you can also point to them via some
-  - libzstd_ >= 1.3.0
+  environment variables, see setup.py.
-  - libxxhash >= 0.8.1 (0.8.0 might work also)
+* Some other Python dependencies, pip will automatically install them for you.
-* pkg-config (cli tool) and pkgconfig python package (borg uses these to
+* Optionally, if you wish to mount an archive as a FUSE filesystem, you need
-  discover header and library location - if it can't import pkgconfig and
-  is not pointed to header/library locations via env vars [see setup.py],
-  it will fall back to using the bundled code, see above).
-  **These must be present before invoking setup.py!**
-* some other Python dependencies, pip will automatically install them for you.
-* optionally, if you wish to mount an archive as a FUSE filesystem, you need
   a FUSE implementation for Python:
 
-  - Either pyfuse3_ (preferably, newer and maintained) or llfuse_ (older,
+  - pyfuse3_ >= 3.1.1 (for fuse 3, use `pip install borgbackup[pyfuse3]`), or
-    unmaintained now). See also the BORG_FUSE_IMPL env variable.
+  - llfuse_ >= 1.3.8 (for fuse 2, use `pip install borgbackup[llfuse]`).
-  - See setup.py about the version requirements.
+  - Additionally, your OS will need to have FUSE support installed
+    (e.g. a package `fuse` for fuse 2 or a package `fuse3` for fuse 3 support).
 
 If you have troubles finding the right package names, have a look at the
 distribution specific sections below or the Vagrantfile in the git repository,
@@ -188,24 +182,34 @@ which contains installation scripts for a number of operating systems.
 
 In the following, the steps needed to install the dependencies are listed for a
 selection of platforms. If your distribution is not covered by these
-instructions, try to use your package manager to install the dependencies.  On
+instructions, try to use your package manager to install the dependencies.
-FreeBSD, you may need to get a recent enough OpenSSL version from FreeBSD
-ports.
 
 After you have installed the dependencies, you can proceed with steps outlined
 under :ref:`pip-installation`.
 
+Arch Linux
+++++++++++
+
+Install the runtime and build dependencies::
+
+    pacman -S python python-pip python-virtualenv openssl acl xxhash lz4 zstd base-devel
+    pacman -S fuse2     # needed for llfuse
+    pacman -S fuse3     # needed for pyfuse3
+
+Note that Arch Linux specifically doesn't support
+`partial upgrades <https://wiki.archlinux.org/title/Partial_upgrade>`__,
+so in case some packages cannot be retrieved from the repo, run with ``pacman -Syu``.
+
 Debian / Ubuntu
 +++++++++++++++
 
 Install the dependencies with development headers::
 
     sudo apt-get install python3 python3-dev python3-pip python3-virtualenv \
-    libacl1-dev libacl1 \
+    libacl1-dev \
     libssl-dev \
     liblz4-dev libzstd-dev libxxhash-dev \
-    build-essential \
+    build-essential pkg-config
-    pkg-config python3-pkgconfig
     sudo apt-get install libfuse-dev fuse    # needed for llfuse
     sudo apt-get install libfuse3-dev fuse3  # needed for pyfuse3
 
@@ -219,10 +223,10 @@ Fedora
 Install the dependencies with development headers::
 
     sudo dnf install python3 python3-devel python3-pip python3-virtualenv \
-    libacl-devel libacl \
+    libacl-devel \
     openssl-devel \
     lz4-devel libzstd-devel xxhash-devel \
-    pkgconf python3-pkgconfig
+    pkgconf
     sudo dnf install gcc gcc-c++ redhat-rpm-config
     sudo dnf install fuse-devel fuse         # needed for llfuse
     sudo dnf install fuse3-devel fuse3       # needed for pyfuse3
@@ -247,16 +251,10 @@ Alternatively, you can enumerate all build dependencies in the command line::
 macOS
 +++++
 
-When installing via Homebrew_, dependencies are installed automatically. To install
+When installing borgbackup via Homebrew_, the basic dependencies are installed automatically.
-dependencies manually::
 
-    brew install python3 openssl zstd lz4 xxhash
+For FUSE support to mount the backup archives, you need macFUSE, which is available
-    brew install pkg-config
+via `github <https://github.com/osxfuse/osxfuse/releases/latest>`__, or Homebrew::
-    pip3 install virtualenv pkgconfig
-
-For FUSE support to mount the backup archives, you need at least version 3.0 of
-macFUSE, which is available via `github
-<https://github.com/osxfuse/osxfuse/releases/latest>`__, or Homebrew::
 
     brew install --cask macfuse
 
@@ -266,7 +264,14 @@ the installed ``openssl`` formula, point pkg-config to the correct path::
 
     PKG_CONFIG_PATH="/usr/local/opt/openssl@1.1/lib/pkgconfig" pip install borgbackup[llfuse]
 
-For OS X Catalina and later, be aware that you must authorize full disk access.
+When working from a borg git repo workdir, you can install dependencies using the
+Brewfile::
+
+    brew install python@3.11  # can be any supported python3 version
+    brew bundle install  # install requirements from borg repo's ./Brewfile
+    pip3 install virtualenv
+
+Be aware that for all recent macOS releases you must authorize full disk access.
 It is no longer sufficient to run borg backups as root. If you have not yet
 granted full disk access, and you run Borg backup from cron, you will see
 messages such as::
@@ -315,8 +320,8 @@ Cygwin
 
 Use the Cygwin installer to install the dependencies::
 
-    python38 python38-devel python38-pkgconfig
+    python39 python39-devel
-    python38-setuptools python38-pip python38-wheel python38-virtualenv
+    python39-setuptools python39-pip python39-wheel python39-virtualenv
     libssl-devel libxxhash-devel liblz4-devel libzstd-devel
     binutils gcc-g++ git make openssh
 
@@ -330,6 +335,8 @@ Virtualenv_ can be used to build and install Borg without affecting
 the system Python or requiring root access.  Using a virtual environment is
 optional, but recommended except for the most simple use cases.
 
+Ensure to install the dependencies as described within :ref:`source-install`.
+
 .. note::
     If you install into a virtual environment, you need to **activate** it
     first (``source borg-env/bin/activate``), before running ``borg``.
@@ -344,9 +351,6 @@ This will use ``pip`` to install the latest release from PyPi::
     # might be required if your tools are outdated
     pip install -U pip setuptools wheel
 
-    # pkgconfig MUST be available before borg is installed!
-    pip install pkgconfig
-
     # install Borg + Python dependencies into virtualenv
     pip install borgbackup
     # or alternatively (if you want FUSE support):
@@ -358,6 +362,19 @@ activating your virtual environment::
 
     pip install -U borgbackup  # or ... borgbackup[llfuse/pyfuse3]
 
+When doing manual pip installation, man pages are not automatically
+installed.  You can run these commands to install the man pages
+locally::
+
+    # get borg from github
+    git clone https://github.com/borgbackup/borg.git borg
+
+    # Install the files with proper permissions
+    install -D -m 0644 borg/docs/man/borg*.1* $HOME/.local/share/man/man1/borg.1
+
+    # Update the man page cache
+    mandb
+
 .. _git-installation:
 
 Using git
@@ -366,20 +383,30 @@ Using git
 This uses latest, unreleased development code from git.
 While we try not to break master, there are no guarantees on anything.
 
+Ensure to install the dependencies as described within :ref:`source-install`.
+
+Version metadata is obtained dynamically at install time using ``setuptools-scm``.
+Please ensure that your git repo either has correct tags, or provide the version
+manually using the ``SETUPTOOLS_SCM_PRETEND_VERSION`` environment variable.
+
 ::
 
     # get borg from github
     git clone https://github.com/borgbackup/borg.git
 
     # create a virtual environment
-    virtualenv --python=${which python3} borg-env
+    virtualenv --python=$(which python3) borg-env
     source borg-env/bin/activate   # always before using!
 
-    # install borg + dependencies into virtualenv
+    # install borg dependencies into virtualenv
     cd borg
     pip install -r requirements.d/development.txt
     pip install -r requirements.d/docs.txt  # optional, to build the docs
 
+    # set a borg version if setuptools-scm fails to do so automatically
+    export SETUPTOOLS_SCM_PRETEND_VERSION=
+
+    # install borg into virtualenv
     pip install -e .           # in-place editable mode
     or
     pip install -e .[pyfuse3]  # in-place editable mode, use pyfuse3
@@ -397,9 +424,9 @@ If you need to use a different version of Python you can install this using ``py
 
     ...
     # create a virtual environment
-    pyenv install 3.8.0  # minimum, preferably use something more recent!
+    pyenv install 3.10.0  # minimum, preferably use something more recent!
-    pyenv global 3.8.0
+    pyenv global 3.10.0
-    pyenv local 3.8.0
+    pyenv local 3.10.0
     virtualenv --python=${pyenv which python} borg-env
     source borg-env/bin/activate   # always before using!
     ...

docs/internals.rst

@@ -4,7 +4,7 @@
 Internals
 =========
 
-The internals chapter describes and analyses most of the inner workings
+The internals chapter describes and analyzes most of the inner workings
 of Borg.
 
 Borg uses a low-level, key-value store, the :ref:`repository`, and
@@ -19,12 +19,12 @@ specified when the backup was performed.
 Deduplication is performed globally across all data in the repository
 (multiple backups and even multiple hosts), both on data and file
 metadata, using :ref:`chunks` created by the chunker using the
-Buzhash_ algorithm ("buzhash" chunker) or a simpler fixed blocksize
+Buzhash_ algorithm ("buzhash" chunker) or a simpler fixed block size
 algorithm ("fixed" chunker).
 
 To actually perform the repository-wide deduplication, a hash of each
 chunk is checked against the :ref:`chunks cache <cache>`, which is a
-hash-table of all chunks that already exist.
+hash table of all chunks that already exist.
 
 .. figure:: internals/structure.png
     :figwidth: 100%

docs/internals/data-structures.rst

@@ -21,29 +21,29 @@ Repository
 
 .. Some parts of this description were taken from the Repository docstring
 
-Borg stores its data in a `Repository`, which is a file system based
+Borg stores its data in a `Repository`, which is a filesystem-based
 transactional key-value store. Thus the repository does not know about
 the concept of archives or items.
 
 Each repository has the following file structure:
 
 README
-  simple text file telling that this is a Borg repository
+  Simple text file telling that this is a Borg repository
 
 config
-  repository configuration
+  Repository configuration
 
 data/
-  directory where the actual data is stored
+  Directory where the actual data is stored
 
 hints.%d
-  hints for repository compaction
+  Hints for repository compaction
 
 index.%d
-  repository index
+  Repository index
 
 lock.roster and lock.exclusive/*
-  used by the locking system to manage shared and exclusive locks
+  Used by the locking system to manage shared and exclusive locks
 
 Transactionality is achieved by using a log (aka journal) to record changes. The log is a series of numbered files
 called segments_. Each segment is a series of log entries. The segment number together with the offset of each
@@ -94,13 +94,13 @@ this value in a non-empty repository, you may also need to relocate the segment
 files manually.
 
 A segment starts with a magic number (``BORG_SEG`` as an eight byte ASCII string),
-followed by a number of log entries. Each log entry consists of:
+followed by a number of log entries. Each log entry consists of: (in this order)
 
-* 32-bit size of the entry
+* First, unsigned 32-bit number, the CRC32 of the entire entry (for a PUT including the DATA) excluding the CRC32 field
-* CRC32 of the entire entry (for a PUT this includes the data)
+* Second, unsigned 32-bit size of the entry (including the whole header)
-* entry tag: PUT, DELETE or COMMIT
+* Third, unsigned 8-bit entry tag: PUT(0), DELETE(1) or COMMIT(2)
-* PUT and DELETE follow this with the 32 byte key
+* Fourth, on PUT or DELETE, 32 byte key
-* PUT follow the key with the data
+* Fifth, PUT only, (size - 41) bytes of data (length = size - sizeof(CRC32) - sizeof(size) - sizeof(entry tag) - sizeof(key))
 
 Those files are strictly append-only and modified only once.
 
@@ -121,6 +121,14 @@ partial/uncommitted transaction.
 The size of individual segments is limited to 4 GiB, since the offset of entries
 within segments is stored in a 32-bit unsigned integer in the repository index.
 
+Objects
+~~~~~~~
+
+All objects (the manifest, archives, archive item streams chunks and file data
+chunks) are encrypted and/or compressed. See :ref:`data-encryption` for a
+graphic outlining the anatomy of an object in Borg. The `type` for compression
+is explained in :ref:`data-compression`.
+
 Index, hints and integrity
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -649,7 +657,7 @@ can be used to tune the chunker parameters, the default is:
 - CHUNK_MIN_EXP = 19 (minimum chunk size = 2^19 B = 512 kiB)
 - CHUNK_MAX_EXP = 23 (maximum chunk size = 2^23 B = 8 MiB)
 - HASH_MASK_BITS = 21 (target chunk size ~= 2^21 B = 2 MiB)
-- HASH_WINDOW_SIZE = 4095 [B] (`0xFFF`)
+- HASH_WINDOW_SIZE = 4095 [B] (`0xFFF`) (must be an odd number)
 
 The buzhash table is altered by XORing it with a seed randomly generated once
 for the repository, and stored encrypted in the keyfile. This is to prevent
@@ -810,7 +818,7 @@ bucket is reached.
 This particular mode of operation is open addressing with linear probing.
 
 When the hash table is filled to 75%, its size is grown. When it's
-emptied to 25%, its size is shrinked. Operations on it have a variable
+emptied to 25%, its size is shrunk. Operations on it have a variable
 complexity between constant and linear with low factor, and memory overhead
 varies between 33% and 300%.
 
@@ -860,6 +868,8 @@ HashIndex is implemented in C and wrapped with Cython in a class-based interface
 The Cython wrapper checks every passed value against these reserved values and
 raises an AssertionError if they are used.
 
+.. _data-encryption:
+
 Encryption
 ----------
 
@@ -961,18 +971,23 @@ key file, wrapped using the standard ``textwrap`` module with a header.
 The header is a single line with a MAGIC string, a space and a hexadecimal
 representation of the repository id.
 
+.. _data-compression:
+
 Compression
 -----------
 
-Borg supports the following compression methods:
+Borg supports the following compression methods, each identified by two bytes:
 
-- none (no compression, pass through data 1:1)
+- none (no compression, pass through data 1:1), identified by ``\x00\x00``
-- lz4 (low compression, but super fast)
+- lz4 (low compression, but super fast), identified by ``\x01\x00``
 - zstd (level 1-22 offering a wide range: level 1 is lower compression and high
-  speed, level 22 is higher compression and lower speed) - since borg 1.1.4
+  speed, level 22 is higher compression and lower speed) - since borg 1.1.4,
+  identified by ``\x03\x00``
 - zlib (level 0-9, level 0 is no compression [but still adding zlib overhead],
-  level 1 is low, level 9 is high compression)
+  level 1 is low, level 9 is high compression), identified by a zlib header
-- lzma (level 0-9, level 0 is low, level 9 is high compression).
+  (``\x.8\x..``)
+- lzma (level 0-9, level 0 is low, level 9 is high compression), identified
+  by ``\x02\x00``.
 
 Speed:  none > lz4 > zlib > lzma, lz4 > zstd
 Compression: lzma > zlib > lz4 > none, zstd > lz4
@@ -1132,7 +1147,7 @@ cache ``config``, since all three are transacted together.
 
 The ``[integrity]`` section is used:
 
-.. code-block:: ini
+.. code-block:: none
 
     [cache]
     version = 1

docs/internals/frontends.rst

@@ -10,18 +10,18 @@ Borg does not have a public API on the Python level. That does not keep you from
 but does mean that there are no release-to-release guarantees on what you might find in that package, not
 even for point releases (1.1.x), and there is no documentation beyond the code and the internals documents.
 
-Borg does on the other hand provide an API on a command-line level. In other words, a frontend should to
+Borg does, on the other hand, provide an API on a command-line level. In other words, a frontend should
-(for example) create a backup archive just invoke :ref:`borg_create`, give commandline parameters/options
+(for example) create a backup archive by invoking :ref:`borg_create`, pass command-line parameters/options
-as needed and parse JSON output from borg.
+as needed, and parse JSON output from Borg.
 
-Important: JSON output is expected to be UTF-8, but currently borg depends on the locale being configured
+Important: JSON output is expected to be UTF-8, but currently Borg depends on the locale being configured
-for that (must be a UTF-8 locale and *not* "C" or "ascii"), so that Python will choose to encode to UTF-8.
+for that (must be a UTF-8 locale and not "C" or "ASCII"), so that Python will choose to encode to UTF-8.
-The same applies to any inputs read by borg, they are expected to be UTF-8 encoded also.
+The same applies to any inputs read by Borg; they are expected to be UTF-8 encoded also.
 
 We consider this a bug (see :issue:`2273`) and might fix it later, so borg will use UTF-8 independent of
 the locale.
 
-On POSIX systems, you can usually set environment vars to choose a UTF-8 locale:
+On POSIX systems, you can usually set environment variables to choose a UTF-8 locale:
 
 ::
 
@@ -50,17 +50,20 @@ archive_progress
     The following keys exist, each represents the current progress.
 
     original_size
-        Original size of data processed so far (before compression and deduplication)
+        Original size of data processed so far (before compression and deduplication, may be empty/absent)
     compressed_size
-        Compressed size
+        Compressed size (may be empty/absent)
     deduplicated_size
-        Deduplicated size
+        Deduplicated size (may be empty/absent)
     nfiles
-        Number of (regular) files processed so far
+        Number of (regular) files processed so far (may be empty/absent)
     path
-        Current path
+        Current path (may be empty/absent)
     time
         Unix timestamp (float)
+    finished
+        boolean indicating whether the operation has finished, only the last object for an *operation*
+        can have this property set to *true*.
 
 progress_message
     A message-based progress information with no concrete progress information, just a message
@@ -90,12 +93,14 @@ progress_percent
         can have this property set to *true*.
     message
         A formatted progress message, this will include the percentage and perhaps other information
+        (absent for finished == true)
     current
-        Current value (always less-or-equal to *total*)
+        Current value (always less-or-equal to *total*, absent for finished == true)
     info
         Array that describes the current item, may be *null*, contents depend on *msgid*
+        (absent for finished == true)
     total
-        Total value
+        Total value (absent for finished == true)
     time
         Unix timestamp (float)
 
@@ -465,13 +470,13 @@ changes:
     A list of *Change* objects describing the changes made to the item in the two archives. For example,
     there will be two changes if the contents of a file are changed, and its ownership are changed.
 
-The *Change* object can contain a number of properties depending on the type of change that occured. 
+The *Change* object can contain a number of properties depending on the type of change that occurred.
 If a 'property' is not required for the type of change, it is not output.
 The possible properties of a *Change* object are:
 
 type:
   The **type** property is always present. It identifies the type of change and will be one of these values:
-  
+
   - *modified* - file contents changed.
   - *added* - the file was added.
   - *removed* - the file was removed.
@@ -495,26 +500,26 @@ added:
 
 removed:
     See **added** property.
-    
+
 old_mode:
     If **type** == '*mode*', then **old_mode** and **new_mode** provide the mode and permissions changes.
 
 new_mode:
     See **old_mode** property.
- 
+
 old_user:
     If **type** == '*owner*', then **old_user**, **new_user**, **old_group** and **new_group** provide the user
     and group ownership changes.
 
 old_group:
     See **old_user** property.
- 
+
 new_user:
     See **old_user** property.
- 
+
 new_group:
     See **old_user** property.
-    
+
 
 Example (excerpt) of ``borg diff --json-lines``::
 
@@ -533,92 +538,182 @@ Message IDs are strings that essentially give a log message or operation a name,
 full text, since texts change more frequently. Message IDs are unambiguous and reduce the need to parse
 log messages.
 
-Assigned message IDs are:
+Assigned message IDs and related error RCs (exit codes) are:
 
 .. See scripts/errorlist.py; this is slightly edited.
 
 Errors
-    Archive.AlreadyExists
+    Error rc: 2 traceback: no
-        Archive {} already exists
+        Error: {}
-    Archive.DoesNotExist
+    ErrorWithTraceback rc: 2 traceback: yes
-        Archive {} does not exist
+        Error: {}
-    Archive.IncompatibleFilesystemEncodingError
+
-        Failed to encode filename "{}" into file system encoding "{}". Consider configuring the LANG environment variable.
+    Buffer.MemoryLimitExceeded rc: 2 traceback: no
-    Cache.CacheInitAbortedError
-        Cache initialization aborted
-    Cache.EncryptionMethodMismatch
-        Repository encryption method changed since last access, refusing to continue
-    Cache.RepositoryAccessAborted
-        Repository access aborted
-    Cache.RepositoryIDNotUnique
-        Cache is newer than repository - do you have multiple, independently updated repos with same ID?
-    Cache.RepositoryReplay
-        Cache is newer than repository - this is either an attack or unsafe (multiple repos with same ID)
-    Buffer.MemoryLimitExceeded
         Requested buffer size {} is above the limit of {}.
-    ExtensionModuleError
+    EfficientCollectionQueue.SizeUnderflow rc: 2 traceback: no
-        The Borg binary extension modules do not seem to be properly installed
+        Could not pop_front the first {} elements; collection only has {} elements.
-    IntegrityError
+    RTError rc: 2 traceback: no
-        Data integrity error: {}
+        Runtime Error: {}
-    NoManifestError
+
-        Repository has no manifest.
+    CancelledByUser rc: 3 traceback: no
-    PlaceholderError
+        Cancelled by user.
+
+    CommandError rc: 4 traceback: no
+        Command Error: {}
+    PlaceholderError rc: 5 traceback: no
         Formatting Error: "{}".format({}): {}({})
-    KeyfileInvalidError
+    InvalidPlaceholder rc: 6 traceback: no
-        Invalid key file for repository {} found in {}.
+        Invalid placeholder "{}" in string: {}
-    KeyfileMismatchError
+
-        Mismatch between repository {} and key file {}.
+    Repository.AlreadyExists rc: 10 traceback: no
-    KeyfileNotFoundError
+        A repository already exists at {}.
-        No key file for repository {} found in {}.
+    Repository.AtticRepository rc: 11 traceback: no
-    PassphraseWrong
+        Attic repository detected. Please run "borg upgrade {}".
-        passphrase supplied in BORG_PASSPHRASE is incorrect
+    Repository.CheckNeeded rc: 12 traceback: yes
-    PasswordRetriesExceeded
+        Inconsistency detected. Please run "borg check {}".
-        exceeded the maximum password retries
+    Repository.DoesNotExist rc: 13 traceback: no
-    RepoKeyNotFoundError
+        Repository {} does not exist.
-        No key entry found in the config of repository {}.
+    Repository.InsufficientFreeSpaceError rc: 14 traceback: no
-    UnsupportedManifestError
+        Insufficient free space to complete transaction (required: {}, available: {}).
+    Repository.InvalidRepository rc: 15 traceback: no
+        {} is not a valid repository. Check repo config.
+    Repository.InvalidRepositoryConfig rc: 16 traceback: no
+        {} does not have a valid configuration. Check repo config [{}].
+    Repository.ObjectNotFound rc: 17 traceback: yes
+        Object with key {} not found in repository {}.
+    Repository.ParentPathDoesNotExist rc: 18 traceback: no
+        The parent path of the repo directory [{}] does not exist.
+    Repository.PathAlreadyExists rc: 19 traceback: no
+        There is already something at {}.
+    Repository.StorageQuotaExceeded rc: 20 traceback: no
+        The storage quota ({}) has been exceeded ({}). Try deleting some archives.
+    Repository.PathPermissionDenied rc: 21 traceback: no
+        Permission denied to {}.
+
+    MandatoryFeatureUnsupported rc: 25 traceback: no
+        Unsupported repository feature(s) {}. A newer version of Borg is required to access this repository.
+    NoManifestError rc: 26 traceback: no
+        Repository has no manifest.
+    UnsupportedManifestError rc: 27 traceback: no
         Unsupported manifest envelope. A newer version is required to access this repository.
-    UnsupportedPayloadError
+
-        Unsupported payload type {}. A newer version is required to access this repository.
+    Archive.AlreadyExists rc: 30 traceback: no
-    NotABorgKeyFile
+        Archive {} already exists
-        This file is not a borg key backup, aborting.
+    Archive.DoesNotExist rc: 31 traceback: no
-    RepoIdMismatch
+        Archive {} does not exist
+    Archive.IncompatibleFilesystemEncodingError rc: 32 traceback: no
+        Failed to encode filename "{}" into file system encoding "{}". Consider configuring the LANG environment variable.
+
+    KeyfileInvalidError rc: 40 traceback: no
+        Invalid key data for repository {} found in {}.
+    KeyfileMismatchError rc: 41 traceback: no
+        Mismatch between repository {} and key file {}.
+    KeyfileNotFoundError rc: 42 traceback: no
+        No key file for repository {} found in {}.
+    NotABorgKeyFile rc: 43 traceback: no
+        This file is not a Borg key backup, aborting.
+    RepoKeyNotFoundError rc: 44 traceback: no
+        No key entry found in the config of repository {}.
+    RepoIdMismatch rc: 45 traceback: no
         This key backup seems to be for a different backup repository, aborting.
-    UnencryptedRepo
+    UnencryptedRepo rc: 46 traceback: no
-        Keymanagement not available for unencrypted repositories.
+        Key management not available for unencrypted repositories.
-    UnknownKeyType
+    UnknownKeyType rc: 47 traceback: no
-        Keytype {0} is unknown.
+        Key type {0} is unknown.
-    LockError
+    UnsupportedPayloadError rc: 48 traceback: no
+        Unsupported payload type {}. A newer version is required to access this repository.
+
+    NoPassphraseFailure rc: 50 traceback: no
+        Cannot acquire a passphrase: {}
+    PasscommandFailure rc: 51 traceback: no
+        Passcommand supplied in BORG_PASSCOMMAND failed: {}
+    PassphraseWrong rc: 52 traceback: no
+        Passphrase supplied in BORG_PASSPHRASE, by BORG_PASSCOMMAND, or via BORG_PASSPHRASE_FD is incorrect.
+    PasswordRetriesExceeded rc: 53 traceback: no
+        Exceeded the maximum password retries.
+
+    Cache.CacheInitAbortedError rc: 60 traceback: no
+        Cache initialization aborted
+    Cache.EncryptionMethodMismatch rc: 61 traceback: no
+        Repository encryption method changed since last access, refusing to continue
+    Cache.RepositoryAccessAborted rc: 62 traceback: no
+        Repository access aborted
+    Cache.RepositoryIDNotUnique rc: 63 traceback: no
+        Cache is newer than repository - do you have multiple, independently updated repos with same ID?
+    Cache.RepositoryReplay rc: 64 traceback: no
+        Cache, or information obtained from the security directory is newer than repository - this is either an attack or unsafe (multiple repos with same ID)
+
+    LockError rc: 70 traceback: no
         Failed to acquire the lock {}.
-    LockErrorT
+    LockErrorT rc: 71 traceback: yes
         Failed to acquire the lock {}.
-    ConnectionClosed
+    LockFailed rc: 72 traceback: yes
-        Connection closed by remote host
+        Failed to create/acquire the lock {} ({}).
-    InvalidRPCMethod
+    LockTimeout rc: 73 traceback: no
-        RPC method {} is not valid
+        Failed to create/acquire the lock {} (timeout).
-    PathNotAllowed
+    NotLocked rc: 74 traceback: yes
-        Repository path not allowed
+        Failed to release the lock {} (was not locked).
-    RemoteRepository.RPCServerOutdated
+    NotMyLock rc: 75 traceback: yes
+        Failed to release the lock {} (was/is locked, but not by me).
+
+    ConnectionClosed rc: 80 traceback: no
+        Connection closed by remote host.
+    ConnectionClosedWithHint rc: 81 traceback: no
+        Connection closed by remote host. {}
+    InvalidRPCMethod rc: 82 traceback: no
+        RPC method {} is not valid.
+    PathNotAllowed rc: 83 traceback: no
+        Repository path not allowed: {}
+    RemoteRepository.RPCServerOutdated rc: 84 traceback: no
         Borg server is too old for {}. Required version {}
-    UnexpectedRPCDataFormatFromClient
+    UnexpectedRPCDataFormatFromClient rc: 85 traceback: no
         Borg {}: Got unexpected RPC data format from client.
-    UnexpectedRPCDataFormatFromServer
+    UnexpectedRPCDataFormatFromServer rc: 86 traceback: no
         Got unexpected RPC data format from server:
         {}
-    Repository.AlreadyExists
+    ConnectionBrokenWithHint rc: 87 traceback: no
-        Repository {} already exists.
+        Connection to remote host is broken. {}
-    Repository.CheckNeeded
+
-        Inconsistency detected. Please run "borg check {}".
+    IntegrityError rc: 90 traceback: yes
-    Repository.DoesNotExist
+        Data integrity error: {}
-        Repository {} does not exist.
+    FileIntegrityError rc: 91 traceback: yes
-    Repository.InsufficientFreeSpaceError
+        File failed integrity check: {}
-        Insufficient free space to complete transaction (required: {}, available: {}).
+    DecompressionError rc: 92 traceback: yes
-    Repository.InvalidRepository
+        Decompression error: {}
-        {} is not a valid repository. Check repo config.
+
-    Repository.AtticRepository
+    ArchiveTAMInvalid rc: 95 traceback: yes
-        Attic repository detected. Please run "borg upgrade {}".
+        Data integrity error: {}
-    Repository.ObjectNotFound
+    ArchiveTAMRequiredError rc: 96 traceback: yes
-        Object with key {} not found in repository {}.
+        Archive '{}' is unauthenticated, but it is required for this repository.
+    TAMInvalid rc: 97 traceback: yes
+        Data integrity error: {}
+    TAMRequiredError rc: 98 traceback: yes
+        Manifest is unauthenticated, but it is required for this repository.
+    TAMUnsupportedSuiteError rc: 99 traceback: yes
+        Could not verify manifest: Unsupported suite {!r}; a newer version is needed.
+
+Warnings
+    BorgWarning rc: 1
+        Warning: {}
+    BackupWarning rc: 1
+        {}: {}
+
+    FileChangedWarning rc: 100
+        {}: file changed while we backed it up
+    IncludePatternNeverMatchedWarning rc: 101
+        Include pattern '{}' never matched.
+    BackupError rc: 102
+        {}: backup error
+    BackupRaceConditionError rc: 103
+        {}: file type or inode changed while we backed it up (race condition, skipped file)
+    BackupOSError rc: 104
+        {}: {}
+    BackupPermissionError rc: 105
+        {}: {}
+    BackupIOError rc: 106
+        {}: {}
+    BackupFileNotFoundError rc: 107
+        {}: {}
 
 Operations
     - cache.begin_transaction
@@ -632,6 +727,7 @@ Operations
     - repository.check
     - check.verify_data
     - check.rebuild_manifest
+    - check.rebuild_refcounts
     - extract
 
       *info* is one string element, the name of the path currently extracted.

docs/internals/security.rst

@@ -30,7 +30,7 @@ Under these circumstances Borg guarantees that the attacker cannot
 
 1. modify the data of any archive without the client detecting the change
 2. rename, remove or add an archive without the client detecting the change
-3. recover plain-text data
+3. recover plaintext data
 4. recover definite (heuristics based on access patterns are possible)
    structural information such as the object graph (which archives
    refer to what chunks)
@@ -142,14 +142,17 @@ Depending on the chosen mode (see :ref:`borg_init`) different primitives are use
   and is also tracked locally on the client to avoid counter reuse.
 
 - The authentication primitive is either HMAC-SHA-256 or BLAKE2b-256
-  in a keyed mode. HMAC-SHA-256 uses 256 bit keys, while BLAKE2b-256
+  in a keyed mode.
-  uses 512 bit keys.
 
-  The latter is secure not only because BLAKE2b itself is not
+  Both HMAC-SHA-256 and BLAKE2b have undergone extensive cryptanalysis
-  susceptible to `length extension`_, but also since it truncates the
+  and have proven secure against known attacks. The known vulnerability
-  hash output from 512 bits to 256 bits, which would make the
+  of SHA-256 against length extension attacks does not apply to HMAC-SHA-256.
-  construction safe even if BLAKE2b were broken regarding length
+
-  extension or similar attacks.
+  The authentication primitive should be chosen based upon SHA hardware support:
+  all AMD Ryzen, Intel 10th+ generation mobile and Intel 11th+ generation
+  desktop processors, Apple M1+ and most current ARM64 architectures support
+  SHA extensions and are likely to perform best with HMAC-SHA-256.
+  64-bit CPUs without SHA extensions are likely to perform best with BLAKE2b.
 
 - The primitive used for authentication is always the same primitive
   that is used for deriving the chunk ID, but they are always

docs/introduction.rst

@@ -1,8 +1,8 @@
 Introduction
 ============
 
-.. this shim is here to fix the structure in the PDF
+.. This shim is here to fix the structure in the PDF
-   rendering. without this stub, the elements in the toctree of
+   rendering. Without this stub, the elements in the toctree of
-   index.rst show up a level below the README file included
+   index.rst show up a level below the README file included there.
 
 .. include:: ../README.rst

docs/man/borg-benchmark-crud.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-BENCHMARK-CRUD" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-benchmark-crud" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .SH SYNOPSIS
 .sp
@@ -37,7 +38,7 @@ borg [common options] benchmark crud [options] REPOSITORY 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
@@ -47,11 +48,9 @@ If your repository is encrypted and borg needs a passphrase to unlock the key, u
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
@@ -62,17 +61,17 @@ Also, due to the kind of content used, no compression is used in these benchmark
 .INDENT 0.0
 .TP
 .B C\- == borg create (1st archive creation, no compression, do not use files cache)
-C\-Z\- == all\-zero files. full dedup, this is primarily measuring reader/chunker/hasher.
+C\-Z\- == all\-zero files. full deduplication; this primarily measures reader/chunker/hasher.
-C\-R\- == random files. no dedup, measuring throughput through all processing stages.
+C\-R\- == random files. no deduplication, measuring throughput through all processing stages.
 .TP
 .B R\- == borg extract (extract archive, dry\-run, do everything, but do not write files to disk)
-R\-Z\- == all zero files. Measuring heavily duplicated files.
+R\-Z\- == all\-zero files. Measuring heavily duplicated files.
 R\-R\- == random files. No duplication here, measuring throughput through all processing
 stages, except writing to disk.
 .TP
 .B U\- == borg create (2nd archive creation of unchanged input files, measure files cache speed)
 The throughput value is kind of virtual here, it does not actually read the file.
-U\-Z\- == needs to check the 2 all\-zero chunks\(aq existence in the repo.
+U\-Z\- == needs to check the two all\-zero chunks\(aq existence in the repo.
 U\-R\- == needs to check existence of a lot of different chunks in the repo.
 .TP
 .B D\- == borg delete archive (delete last remaining archive, measure deletion + compaction)
@@ -81,7 +80,7 @@ D\-R\- == many chunks to delete / many segments to compact/remove.
 .UNINDENT
 .sp
 Please note that there might be quite some variance in these measurements.
-Try multiple measurements and having a otherwise idle machine (and network, if you use it).
+Try multiple measurements and have an otherwise idle machine (and network, if you use it).
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -92,12 +91,11 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 repository to use for benchmark (must exist)
 .TP
 .B PATH
-path were to create benchmark input data
+path where to create benchmark input data
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-benchmark.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-BENCHMARK" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-benchmark" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-benchmark \- benchmark command
 .SH SYNOPSIS
 .nf
@@ -37,11 +38,10 @@ borg [common options] benchmark crud ...
 .sp
 .SH DESCRIPTION
 .sp
-These commands do various benchmarks.
+These commands perform various benchmarks.
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-benchmark\-crud(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-break-lock.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-BREAK-LOCK" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-break-lock" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .SH SYNOPSIS
 .sp
@@ -36,8 +37,8 @@ borg [common options] break\-lock [options] [REPOSITORY]
 .SH DESCRIPTION
 .sp
 This command breaks the repository and cache locks.
-Please use carefully and only while no borg process (on any machine) is
+Please use with care and only when no borg process (on any machine) is
-trying to access the Cache or the Repository.
+trying to access the cache or the repository.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -50,7 +51,6 @@ repository for which to break the locks
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-check.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,99 +28,131 @@ 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 "2022-02-19" "" "borg backup tool"
+.TH "borg-check" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-check \- Check repository consistency
 .SH SYNOPSIS
 .sp
 borg [common options] check [options] [REPOSITORY_OR_ARCHIVE]
 .SH DESCRIPTION
 .sp
-The check command verifies the consistency of a repository and the corresponding archives.
+The check command verifies the consistency of a repository and its archives.
+It consists of two major steps:
+.INDENT 0.0
+.IP 1. 3
+Checking the consistency of the repository itself. This includes checking
+the segment magic headers, and both the metadata and data of all objects in
+the segments. The read data is checked by size and CRC. 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 the
+server and do not cause significant network traffic.
+.IP 2. 3
+Checking consistency and correctness of the archive metadata and optionally
+archive data (requires \fB\-\-verify\-data\fP). This includes ensuring that the
+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 cryptographically verify
+the file (content) data integrity pass \fB\-\-verify\-data\fP, but keep in mind
+that this requires reading all data and is hence very 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.
+.UNINDENT
 .sp
-check \-\-repair is a potentially dangerous function and might lead to data loss
+Both steps can also be run independently. Pass \fB\-\-repository\-only\fP to run the
-(for kinds of corruption it is not capable of dealing with). BE VERY CAREFUL!
+repository checks only, or pass \fB\-\-archives\-only\fP to run the archive checks
+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
+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
+(1 hour) would result in one full repository check per week. Doing a full
+repository check aborts any previous partial check; the next partial check will
+restart from the beginning. With partial repository checks you can run neither
+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
+\fB\-\-max\-duration\fP) can only perform non\-cryptographic checksum checks on the
+segment files. A full repository check (i.e. without \fB\-\-max\-duration\fP) can
+also do a repository index check. Enabling partial repository checks excludes
+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.
+.sp
+The \fB\-\-verify\-data\fP option will perform a full integrity verification (as
+opposed to checking the CRC32 of the segment) 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
+accidental and malicious corruption. Tamper\-resistance is only guaranteed for
+encrypted repositories against attackers without access to the keys. You cannot
+use \fB\-\-verify\-data\fP with \fB\-\-repository\-only\fP\&.
+.SS About repair mode
+.sp
+The check command is a read\-only task by default. If any corruption is found,
+Borg will report the issue and proceed with checking. To actually repair the
+issues found, pass \fB\-\-repair\fP\&.
+.sp
+\fBNote:\fP
+.INDENT 0.0
+.INDENT 3.5
+\fB\-\-repair\fP is a \fBPOTENTIALLY DANGEROUS FEATURE\fP and might lead to data
+loss! This does not just include data that was previously lost anyway, but
+might include more data for kinds of corruption it is not capable of
+dealing with. \fBBE VERY CAREFUL!\fP
+.UNINDENT
+.UNINDENT
 .sp
 Pursuant to the previous warning it is also highly recommended to test the
-reliability of the hardware running this software with stress testing software
+reliability of the hardware running Borg with stress testing software. This
-such as memory testers. Unreliable hardware can also lead to data loss especially
+especially includes storage and memory testers. Unreliable hardware might lead
-when this command is run in repair mode.
+to additional data loss.
 .sp
-First, the underlying repository data files are checked:
+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
+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.
+.sp
+In practice, repair mode hooks into both the repository and archive checks:
 .INDENT 0.0
-.IP \(bu 2
+.IP 1. 3
-For all segments, the segment magic header is checked.
+When checking the repository\(aqs consistency, repair mode will try to recover
-.IP \(bu 2
+as many objects from segments with integrity errors as possible, and ensure
-For all objects stored in the segments, all metadata (e.g. CRC and size) and
+that the index is consistent with the data stored in the segments.
-all data is read. The read data is checked by size and CRC. Bit rot and other
+.IP 2. 3
-types of accidental damage can be detected this way.
+When checking the consistency and correctness of archives, repair mode might
-.IP \(bu 2
+remove whole archives from the manifest if their archive metadata chunk is
-In repair mode, if an integrity error is detected in a segment, try to recover
+corrupt or lost. On a chunk level (i.e. the contents of files), repair mode
-as many objects from the segment as possible.
+will replace corrupt or lost chunks with a same\-size replacement chunk of
-.IP \(bu 2
+zeroes. If a previously zeroed chunk reappears, repair mode will restore
-In repair mode, make sure that the index is consistent with the data stored in
+this lost chunk using the new chunk. Lastly, repair mode will also delete
-the segments.
+orphaned chunks (e.g. caused by read errors while creating the archive).
-.IP \(bu 2
-If checking a remote repo via \fBssh:\fP, the repo check is executed on the server
-without causing significant network traffic.
-.IP \(bu 2
-The repository check can be skipped using the \fB\-\-archives\-only\fP option.
-.IP \(bu 2
-A repository check can be time consuming. Partial checks are possible with the
-\fB\-\-max\-duration\fP option.
 .UNINDENT
 .sp
-Second, the consistency and correctness of the archive metadata is verified:
+Most steps taken by repair mode have a one\-time effect on the repository, like
-.INDENT 0.0
+removing a lost archive from the repository. However, replacing a corrupt or
-.IP \(bu 2
+lost chunk with an all\-zero replacement will have an ongoing effect on the
-Is the repo manifest present? If not, it is rebuilt from archive metadata
+repository: When attempting to extract a file referencing an all\-zero chunk,
-chunks (this requires reading and decrypting of all metadata and data).
+the \fBextract\fP command will distinctly warn about it. The FUSE filesystem
-.IP \(bu 2
+created by the \fBmount\fP command will reject reading such a \(dqzero\-patched\(dq
-Check if archive metadata chunk is present; if not, remove archive from manifest.
+file unless a special mount option is given.
-.IP \(bu 2
-For all files (items) in the archive, for all chunks referenced by these
-files, check if chunk is present. In repair mode, if a chunk is not present,
-replace it with a same\-size replacement chunk of zeroes. If a previously lost
-chunk reappears (e.g. via a later backup), in repair mode the all\-zero replacement
-chunk will be replaced by the correct chunk. This requires reading of archive and
-file metadata, but not data.
-.IP \(bu 2
-In repair mode, when all the archives were checked, orphaned chunks are deleted
-from the repo. One cause of orphaned chunks are input file related errors (like
-read errors) in the archive creation process.
-.IP \(bu 2
-In verify\-data mode, a complete cryptographic verification of the archive data
-integrity is performed. This conflicts with \fB\-\-repository\-only\fP as this mode
-only makes sense if the archive checks are enabled. The full details of this mode
-are documented below.
-.IP \(bu 2
-If checking a remote repo via \fBssh:\fP, the archive check is executed on the
-client machine because it requires decryption, and this is always done client\-side
-as key access is needed.
-.IP \(bu 2
-The archive checks can be time consuming; they can be skipped using the
-\fB\-\-repository\-only\fP option.
-.UNINDENT
 .sp
-The \fB\-\-max\-duration\fP option can be used to split a long\-running repository check
+As mentioned earlier, Borg might be able to \(dqheal\(dq a \(dqzero\-patched\(dq file in
-into multiple partial checks. After the given number of seconds the check is
+repair mode, if all its previously lost chunks reappear (e.g. via a later
-interrupted. The next partial check will continue where the previous one stopped,
+backup). This is achieved by Borg not only keeping track of the all\-zero
-until the complete repository has been checked. Example: Assuming a full check took 7
+replacement chunks, but also by keeping metadata about the lost chunks. In
-hours, then running a daily check with \-\-max\-duration=3600 (1 hour) resulted in one
+repair mode Borg will check whether a previously lost chunk reappeared and will
-full check per week.
+replace the all\-zero replacement chunk by the reappeared chunk. If all lost
-.sp
+chunks of a \(dqzero\-patched\(dq file reappear, this effectively \(dqheals\(dq the file.
-Attention: Partial checks can only do way less checking than a full check (only the
+Consequently, if lost chunks were repaired earlier, it is advised to run
-CRC32 checks on segment file entries are done), and cannot be combined with the
+\fB\-\-repair\fP a second time after creating some new backups.
-\fB\-\-repair\fP option. Partial checks may therefore be useful only with very large
-repositories where a full check took too long. Doing a full repository check aborts a
-partial check; the next partial check will restart from the beginning.
-.sp
-The \fB\-\-verify\-data\fP option will perform a full integrity verification (as opposed to
-checking the CRC32 of the segment) of data, which means reading the data from the
-repository, decrypting and decompressing it. This is a cryptographic verification,
-which will detect (accidental) corruption. For encrypted repositories it is
-tamper\-resistant as well, unless the attacker has access to the keys. It is also very
-slow.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -129,7 +162,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B REPOSITORY_OR_ARCHIVE
 repository or archive to check consistency of
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-repository\-only
@@ -154,13 +187,13 @@ do only a partial repo check for max. SECONDS seconds (Default: unlimited)
 .INDENT 0.0
 .TP
 .BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX
-only consider archive names starting with this prefix.
+only consider archive names starting with this prefix. (deprecated)
 .TP
 .BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB
-only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
+only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see \(dqborg help patterns\(dq.
 .TP
 .BI \-\-sort\-by \ KEYS
-Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp
 .TP
 .BI \-\-first \ N
 consider first N archives after other filters were applied
@@ -171,7 +204,6 @@ consider last N archives after other filters were applied
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-common.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-COMMON" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-common" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-common \- Common options of Borg commands
 .SH SYNOPSIS
 .INDENT 0.0
@@ -79,7 +80,7 @@ show/log the return code (rc)
 set umask to M (local only, default: 0077)
 .TP
 .BI \-\-remote\-path \ PATH
-use PATH as borg executable on the remote (default: "borg")
+use PATH as borg executable on the remote (default: \(dqborg\(dq)
 .TP
 .BI \-\-remote\-ratelimit \ RATE
 deprecated, use \fB\-\-upload\-ratelimit\fP instead
@@ -97,7 +98,7 @@ set network upload buffer size in MiB. (default: 0=no buffer)
 treat part files like normal files (e.g. to list/extract them)
 .TP
 .BI \-\-debug\-profile \ FILE
-Write execution profile in Borg format into FILE. For local use a Python\-compatible file can be generated by suffixing FILE with ".pyprof".
+Write execution profile in Borg format into FILE. For local use a Python\-compatible file can be generated by suffixing FILE with \(dq.pyprof\(dq.
 .TP
 .BI \-\-rsh \ RSH
 Use this command to connect to the \(aqborg serve\(aq process (default: \(aqssh\(aq)
@@ -105,7 +106,6 @@ Use this command to connect to the \(aqborg serve\(aq process (default: \(aqssh\
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-compact.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-COMPACT" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-compact" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-compact \- compact segment files in the repository
 .SH SYNOPSIS
 .sp
@@ -51,9 +52,17 @@ A segment is compacted if the amount of saved space is above the percentage valu
 given by the \fB\-\-threshold\fP option. If omitted, a threshold of 10% is used.
 When using \fB\-\-verbose\fP, borg will output an estimate of the freed space.
 .sp
+For maximum compaction, use \fB\-\-threshold 0\fP\&. This will compact whenever any
+space can be saved and thus rewrites the most data; it can be much slower on
+large repositories. Using \fB\-\-threshold 1\fP usually achieves nearly the same
+result significantly faster. Higher thresholds (e.g. the default 10) trade
+compaction thoroughness for speed. Note: \fB\-\-threshold 100\fP will effectively
+compact nothing.
+.sp
 After upgrading borg (server) to 1.2+, you can use \fBborg compact \-\-cleanup\-commits\fP
-to clean up the numerous 17byte commit\-only segments that borg 1.1 did not clean up
+to clean up the numerous 17\-byte commit\-only segments that borg 1.1 did not clean up
-due to a bug. It is enough to do that once per repository.
+due to a bug. It is enough to do that once per repository. After cleaning up the
+commits, borg will also do a normal compaction.
 .sp
 See \fIseparate_compaction\fP in Additional Notes for more details.
 .SH OPTIONS
@@ -65,9 +74,12 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B REPOSITORY
 repository to compact
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
+.B  \-n\fP,\fB  \-\-dry\-run
+do nothing
+.TP
 .B  \-\-cleanup\-commits
 cleanup commit\-only 17\-byte segment files
 .TP
@@ -78,21 +90,18 @@ set minimum threshold for saved space in PERCENT (Default: 10)
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 # compact segments and free repo disk space
 $ borg compact /path/to/repo
 
-# same as above plus clean up 17byte commit\-only segments
+# same as above plus clean up 17\-byte commit\-only segments
 $ borg compact \-\-cleanup\-commits /path/to/repo
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-compression.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-COMPRESSION" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-compression" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-compression \- Details regarding compression
 .SH DESCRIPTION
 .sp
@@ -53,20 +54,20 @@ Do not compress.
 Use lz4 compression. Very high speed, very low compression. (default)
 .TP
 .B zstd[,L]
-Use zstd ("zstandard") compression, a modern wide\-range algorithm.
+Use zstd (\(dqzstandard\(dq) compression, a modern wide\-range algorithm.
 If you do not explicitly give the compression level L (ranging from 1
 to 22), it will use level 3.
 Archives compressed with zstd are not compatible with borg < 1.1.4.
 .TP
 .B zlib[,L]
-Use zlib ("gz") compression. Medium speed, medium compression.
+Use zlib (\(dqgz\(dq) compression. Medium speed, medium compression.
 If you do not explicitly give the compression level L (ranging from 0
 to 9), it will use level 6.
-Giving level 0 (means "no compression", but still has zlib protocol
+Giving level 0 (means \(dqno compression\(dq, but still has zlib protocol
-overhead) is usually pointless, you better use "none" compression.
+overhead) is usually pointless, you better use \(dqnone\(dq compression.
 .TP
 .B lzma[,L]
-Use lzma ("xz") compression. Low speed, high compression.
+Use lzma (\(dqxz\(dq) compression. Low speed, high compression.
 If you do not explicitly give the compression level L (ranging from 0
 to 9), it will use level 6.
 Giving levels above 6 is pointless and counterproductive because it does
@@ -76,43 +77,91 @@ lots of CPU cycles and RAM.
 .B auto,C[,L]
 Use a built\-in heuristic to decide per chunk whether to compress or not.
 The heuristic tries with lz4 whether the data is compressible.
-For incompressible data, it will not use compression (uses "none").
+For incompressible data, it will not use compression (uses \(dqnone\(dq).
 For compressible data, it uses the given C[,L] compression \- with C[,L]
-being any valid compression specifier.
+being any valid compression specifier. This can be helpful for media files
+which often cannot be compressed much more.
 .TP
 .B obfuscate,SPEC,C[,L]
 Use compressed\-size obfuscation to make fingerprinting attacks based on
-the observable stored chunk size more difficult.
+the observable stored chunk size more difficult. Note:
-Note:
+.INDENT 7.0
-\- you must combine this with encryption or it won\(aqt make any sense.
+.IP \(bu 2
-\- your repo size will be bigger, of course.
+You must combine this with encryption, or it won\(aqt make any sense.
+.IP \(bu 2
+Your repo size will be bigger, of course.
+.IP \(bu 2
+A chunk is limited by the constant \fBMAX_DATA_SIZE\fP (cur. ~20MiB).
+.UNINDENT
 .sp
-The SPEC value will determine how the size obfuscation will work:
+The SPEC value determines how the size obfuscation works:
+.sp
+\fIRelative random reciprocal size variation\fP (multiplicative)
 .sp
-Relative random reciprocal size variation:
 Size will increase by a factor, relative to the compressed data size.
-Smaller factors are often used, larger factors rarely.
+Smaller factors are used often, larger factors rarely.
-1: factor 0.01 .. 100.0
-2: factor 0.1 .. 1000.0
-3: factor 1.0 .. 10000.0
-4: factor 10.0 .. 100000.0
-5: factor 100.0 .. 1000000.0
-6: factor 1000.0 .. 10000000.0
 .sp
-Add a randomly sized padding up to the given size:
+Available factors:
-110: 1kiB
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.EX
+1:     0.01 ..        100
+2:     0.1  ..      1,000
+3:     1    ..     10,000
+4:    10    ..    100,000
+5:   100    ..  1,000,000
+6: 1,000    .. 10,000,000
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+Example probabilities for SPEC \fB1\fP:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.EX
+90   %  0.01 ..   0.1
+ 9   %  0.1  ..   1
+ 0.9 %  1    ..  10
+ 0.09% 10    .. 100
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+\fIRandomly sized padding up to the given size\fP (additive)
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.EX
+110: 1kiB (2 ^ (SPEC \- 100))
 \&...
 120: 1MiB
 \&...
 123: 8MiB (max.)
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+\fIPadmé padding\fP (deterministic)
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.EX
+250: pads to sums of powers of 2, max 12% overhead
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+Uses the Padmé algorithm to deterministically pad the compressed size to a sum of
+powers of 2, limiting overhead to 12%. See \%<https://\:lbarman\:.ch/\:blog/\:padme/> for details.
 .UNINDENT
 .sp
 Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 borg create \-\-compression lz4 REPO::ARCHIVE data
 borg create \-\-compression zstd REPO::ARCHIVE data
 borg create \-\-compression zstd,10 REPO::ARCHIVE data
@@ -120,14 +169,13 @@ borg create \-\-compression zlib REPO::ARCHIVE data
 borg create \-\-compression zlib,1 REPO::ARCHIVE data
 borg create \-\-compression auto,lzma,6 REPO::ARCHIVE data
 borg create \-\-compression auto,lzma ...
-borg create \-\-compression obfuscate,3,none ...
+borg create \-\-compression obfuscate,110,none ...
 borg create \-\-compression obfuscate,3,auto,zstd,10 ...
 borg create \-\-compression obfuscate,2,zstd,6 ...
-.ft P
+borg create \-\-compression obfuscate,250,zstd,3 ...
-.fi
+.EE
 .UNINDENT
 .UNINDENT
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-config.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-CONFIG" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-config" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-config \- get, set, and delete values in a repository or cache config file
 .SH SYNOPSIS
 .sp
@@ -39,10 +40,10 @@ This command gets and sets options in a local repository or cache config file.
 For security reasons, this command only works on local repositories.
 .sp
 To delete a config value entirely, use \fB\-\-delete\fP\&. To list the values
-of the configuration file or the default values, use \fB\-\-list\fP\&.  To get and existing
+of the configuration file or the default values, use \fB\-\-list\fP\&. To get an existing
 key, pass only the key name. To set a key, pass both the key name and
-the new value. Keys can be specified in the format "section.name" or
+the new value. Keys can be specified in the format \(dqsection.name\(dq or
-simply "name"; the section will default to "repository" and "cache" for
+simply \(dqname\(dq; the section will default to \(dqrepository\(dq and \(dqcache\(dq for
 the repo and cache configs, respectively.
 .sp
 By default, borg config manipulates the repository config file. Using \fB\-\-cache\fP
@@ -62,7 +63,7 @@ name of config key
 .B VALUE
 new value for key
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-c\fP,\fB  \-\-cache
@@ -76,7 +77,7 @@ list the configuration of the repo
 .UNINDENT
 .SH EXAMPLES
 .sp
-\fBNOTE:\fP
+\fBNote:\fP
 .INDENT 0.0
 .INDENT 3.5
 The repository & cache config files are some of the only directly manipulable
@@ -87,8 +88,7 @@ making changes!
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 # find cache directory
 $ cd ~/.cache/borg/$(borg config /path/to/repo id)
 
@@ -97,14 +97,12 @@ $ borg config /path/to/repo additional_free_space 2G
 
 # make a repo append\-only
 $ borg config /path/to/repo append_only 1
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-create.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-CREATE" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-create" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-create \- Create new archive
 .SH SYNOPSIS
 .sp
@@ -37,13 +38,18 @@ borg [common options] create [options] ARCHIVE [PATH...]
 .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
+which means that if relative paths are desired, the command has to be run from the correct
 directory.
 .sp
-When giving \(aq\-\(aq as path, borg will read data from standard input and create a
+The slashdot hack in paths (recursion roots) is triggered by using \fB/./\fP:
-file \(aqstdin\(aq in the created archive from that data. In some cases it\(aqs more
+\fB/this/gets/stripped/./this/gets/archived\fP means to process that filesystem object, but
-appropriate to use \-\-content\-from\-command, however. See section \fIReading from
+strip the prefix on the left side of \fB\&./\fP from the archived items (in this case,
-stdin\fP below for details.
+\fBthis/gets/archived\fP will be the path in the archived item).
+.sp
+When giving \(aq\-\(aq as a 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 is more
+appropriate to use \fB\-\-content\-from\-command\fP\&. See section \(dqReading from stdin\(dq
+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.
@@ -65,7 +71,7 @@ This comparison can operate in different modes as given by \fB\-\-files\-cache\f
 .IP \(bu 2
 ctime,size,inode (default)
 .IP \(bu 2
-mtime,size,inode (default behaviour of borg versions older than 1.1.0rc4)
+mtime,size,inode (default behavior of borg versions older than 1.1.0rc4)
 .IP \(bu 2
 ctime,size (ignore the inode number)
 .IP \(bu 2
@@ -78,42 +84,54 @@ rechunk,mtime (all files are considered modified \- rechunk, cache mtime)
 disabled (disable the files cache, all files considered modified \- rechunk)
 .UNINDENT
 .sp
-inode number: better safety, but often unstable on network filesystems
+inode number: better safety, but often unstable on network file systems
 .sp
 Normally, detecting file modifications will take inode information into
 consideration to improve the reliability of file change detection.
-This is problematic for files located on sshfs and similar network file
+This is problematic for files located on SSHFS and similar network file
-systems which do not provide stable inode numbers, such files will always
+systems which do not provide stable inode numbers; such files will always
 be considered modified. You can use modes without \fIinode\fP in this case to
-improve performance, but reliability of change detection might be reduced.
+improve performance, but the reliability of change detection might be reduced.
 .sp
 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 user space. However, 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).
+without content changes. Some file systems do not support ctime (change time).
-E.g. doing a chown or chmod to a file will change its ctime.
+For example, 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 user space, 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
 .sp
-The mount points of filesystems or filesystem snapshots should be the same for every
+The \fB\-\-files\-changed\fP option controls how Borg detects if a file has changed during backup:
+.INDENT 0.0
+.IP \(bu 2
+ctime (default): Use ctime to detect changes. This is the safest option.
+.IP \(bu 2
+mtime: Use mtime to detect changes.
+.IP \(bu 2
+disabled: Disable the \(dqfile has changed while we backed it up\(dq detection completely.
+This is not recommended unless you know what you\(aqre doing, as it could lead to
+inconsistent backups if files change during the backup process.
+.UNINDENT
+.sp
+The mount points of file systems or file system snapshots should be the same for every
 creation of a new archive to ensure fast operation. This is because the file cache that
-is used to determine changed files quickly uses absolute filenames.
+is used to determine changed files quickly uses absolute file names.
 If this is not possible, consider creating a bind mount to a stable location.
 .sp
 The \fB\-\-progress\fP option shows (from left to right) Original, Compressed and Deduplicated
-(O, C and D, respectively), then the Number of files (N) processed so far, followed by
+(O, C and D, respectively), then the number of files (N) processed so far, followed by
 the currently processed path.
 .sp
 When using \fB\-\-stats\fP, you will get some statistics about how much data was
-added \- the "This Archive" deduplicated size there is most interesting as that is
+added \- the \(dqThis Archive\(dq deduplicated size there is most interesting as that is
-how much your repository will grow. Please note that the "All archives" stats refer to
+how much your repository will grow. Please note that the \(dqAll archives\(dq stats refer to
 the state after creation. Also, the \fB\-\-stats\fP and \fB\-\-dry\-run\fP options are mutually
 exclusive because the data is not actually compressed and deduplicated during a dry run.
 .sp
@@ -132,7 +150,7 @@ name of archive to create (must be also a valid directory name)
 .B PATH
 paths to archive
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-n\fP,\fB  \-\-dry\-run
@@ -169,15 +187,15 @@ set mode to M in archive for stdin data (default: 0660)
 interpret PATH as command and store its stdout. See also section Reading from stdin below.
 .TP
 .B  \-\-paths\-from\-stdin
-read DELIM\-separated list of paths to backup from stdin. Will not recurse into directories.
+read DELIM\-separated list of paths to backup from stdin. All control is external: it will back up all files given \- no more, no less.
 .TP
 .B  \-\-paths\-from\-command
 interpret PATH as command and treat its output as \fB\-\-paths\-from\-stdin\fP
 .TP
 .BI \-\-paths\-delimiter \ DELIM
-set path delimiter for \fB\-\-paths\-from\-stdin\fP and \fB\-\-paths\-from\-command\fP (default: n)
+set path delimiter for \fB\-\-paths\-from\-stdin\fP and \fB\-\-paths\-from\-command\fP (default: \fB\en\fP)
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
@@ -193,7 +211,7 @@ include/exclude paths matching PATTERN
 read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .B  \-\-exclude\-caches
-exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP)
+exclude directories that contain a CACHEDIR.TAG file (\%<http://\:www\:.bford\:.info/\:cachedir/\:spec\:.html>)
 .TP
 .BI \-\-exclude\-if\-present \ NAME
 exclude directories that are tagged by containing a filesystem object with the given NAME
@@ -208,7 +226,7 @@ exclude files flagged NODUMP
 .INDENT 0.0
 .TP
 .B  \-x\fP,\fB  \-\-one\-file\-system
-stay in the same file system and do not store mount points of other file systems.  This might behave different from your expectations, see the docs.
+stay in the same file system and do not store mount points of other file systems \- this might behave different from your expectations, see the description below.
 .TP
 .B  \-\-numeric\-owner
 deprecated, use \fB\-\-numeric\-ids\fP instead
@@ -246,6 +264,9 @@ detect sparse holes in input (supported only by fixed chunker)
 .BI \-\-files\-cache \ MODE
 operate files cache in MODE. default: ctime,size,inode
 .TP
+.BI \-\-files\-changed \ MODE
+specify how to detect if a file has changed during backup (ctime, mtime, disabled). default: ctime
+.TP
 .B  \-\-read\-special
 open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.
 .UNINDENT
@@ -265,20 +286,22 @@ write checkpoint every SECONDS seconds (Default: 1800)
 specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095
 .TP
 .BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
-select compression algorithm, see the output of the "borg help compression" command for details.
+select compression algorithm, see the output of the \(dqborg help compression\(dq command for details.
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
+# Backup ~/Documents into an archive named \(dqmy\-documents\(dq
-# Backup ~/Documents into an archive named "my\-documents"
 $ borg create /path/to/repo::my\-documents ~/Documents
 
 # same, but list all files as we process them
 $ borg create \-\-list /path/to/repo::my\-documents ~/Documents
 
+# Backup /mnt/disk/docs, but strip path prefix using the slashdot hack
+$ borg create /path/to/repo::docs /mnt/disk/./docs
+
 # Backup ~/Documents and ~/src but exclude pyc files
 $ borg create /path/to/repo::my\-files \e
     ~/Documents                       \e
@@ -288,17 +311,17 @@ $ borg create /path/to/repo::my\-files \e
 # Backup home directories excluding image thumbnails (i.e. only
 # /home/<one directory>/.thumbnails is excluded, not /home/*/*/.thumbnails etc.)
 $ borg create /path/to/repo::my\-files /home \e
-    \-\-exclude \(aqsh:/home/*/.thumbnails\(aq
+    \-\-exclude \(aqsh:home/*/.thumbnails\(aq
 
-# Backup the root filesystem into an archive named "root\-YYYY\-MM\-DD"
+# Backup the root filesystem into an archive named \(dqroot\-YYYY\-MM\-DD\(dq
 # use zlib compression (good, but slow) \- default is lz4 (fast, low compression ratio)
 $ borg create \-C zlib,6 \-\-one\-file\-system /path/to/repo::root\-{now:%Y\-%m\-%d} /
 
-# Backup onto a remote host ("push" style) via ssh to port 2222,
+# Backup onto a remote host (\(dqpush\(dq style) via ssh to port 2222,
-# logging in as user "borg" and storing into /path/to/repo
+# logging in as user \(dqborg\(dq and storing into /path/to/repo
 $ borg create ssh://borg@backup.example.org:2222/path/to/repo::{fqdn}\-root\-{now} /
 
-# Backup a remote host locally ("pull" style) using sshfs
+# Backup a remote host locally (\(dqpull\(dq style) using sshfs
 $ mkdir sshfs\-mount
 $ sshfs root@example.com:/ sshfs\-mount
 $ cd sshfs\-mount
@@ -341,7 +364,7 @@ $ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f} ~
 
 # Backing up relative paths by moving into the correct directory first
 $ cd /home/user/Documents
-# The root directory of the archive will be "projectA"
+# The root directory of the archive will be \(dqprojectA\(dq
 $ borg create /path/to/repo::daily\-projectA\-{now:%Y\-%m\-%d} projectA
 
 # Use external command to determine files to archive
@@ -352,10 +375,9 @@ $ borg create \-\-paths\-from\-command /path/to/repo::joes\-files \-\- find /srv
 # Use \-\-paths\-from\-stdin with \-\-paths\-delimiter (for example, for filenames with newlines in them)
 $ find ~ \-size \-1000k \-print0 | borg create \e
     \-\-paths\-from\-stdin \e
-    \-\-paths\-delimiter "\e0" \e
+    \-\-paths\-delimiter \(dq\e0\(dq \e
     /path/to/repo::smallfiles\-handle\-newline
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .SH NOTES
@@ -373,16 +395,16 @@ only include the objects specified by \fB\-\-exclude\-if\-present\fP in your bac
 and not include any other contents of the containing folder, this can be enabled
 through using the \fB\-\-keep\-exclude\-tags\fP option.
 .sp
-The \fB\-x\fP or \fB\-\-one\-file\-system\fP option excludes directories, that are mountpoints (and everything in them).
+The \fB\-x\fP or \fB\-\-one\-file\-system\fP option excludes directories that are mount points (and everything in them).
-It detects mountpoints by comparing the device number from the output of \fBstat()\fP of the directory and its
+It detects mount points by comparing the device number from the output of \fBstat()\fP of the directory and its
 parent directory. Specifically, it excludes directories for which \fBstat()\fP reports a device number different
-from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories
+from the device number of their parent.
-with device number different from their parent, which the kernel does not consider a mountpoint and also the
+In general: be aware that there are directories with device numbers different from their parent, which the kernel
-other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL
+does not consider mount points, and vice versa.
-subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when
+Linux examples for this are bind mounts (possibly same device number, but always a mount point) and all
-using \fB\-\-one\-file\-system\fP, one should make doubly sure that the backup works as intended especially when using
+subvolumes of a Btrfs file system (different device numbers from the parent but not necessarily mount points).
-btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution
+macOS examples are the APFS mounts of a typical macOS installation.
-installer.
+Therefore, when using \fB\-\-one\-file\-system\fP, you should double\-check that the backup works as intended.
 .SS Item flags
 .sp
 \fB\-\-list\fP outputs a list of all files, directories and other
@@ -395,7 +417,7 @@ If you are interested only in a subset of that output, you can give e.g.
 below).
 .sp
 A uppercase character represents the status of a regular file relative to the
-"files" cache (not relative to the repo \-\- this is an issue if the files cache
+\(dqfiles\(dq cache (not relative to the repo \-\- this is an issue if the files cache
 is not used). Metadata is stored in any case and for \(aqA\(aq and \(aqM\(aq also new data
 chunks are stored. For \(aqU\(aq all data chunks refer to already existing chunks.
 .INDENT 0.0
@@ -439,18 +461,16 @@ Other flags used include:
 .IP \(bu 2
 \(aq?\(aq = missing status code (if you see this, please file a bug report!)
 .UNINDENT
-.SS Reading from stdin
+.SS Reading backup data from stdin
 .sp
 There are two methods to read from stdin. Either specify \fB\-\fP as path and
 pipe directly to borg:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 backup\-vm \-\-id myvm \-\-stdout | borg create REPO::ARCHIVE \-
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
@@ -461,11 +481,9 @@ to the command:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 borg create \-\-content\-from\-command REPO::ARCHIVE \-\- backup\-vm \-\-id myvm \-\-stdout
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
@@ -486,10 +504,22 @@ creation a bit.
 .sp
 By default, the content read from stdin is stored in a file called \(aqstdin\(aq.
 Use \fB\-\-stdin\-name\fP to change the name.
+.SS Feeding all file paths from externally
+.sp
+Usually, you give a starting path (recursion root) to borg and then borg
+automatically recurses, finds and backs up all fs objects contained in
+there (optionally considering include/exclude rules).
+.sp
+If you need more control and you want to give every single fs object path
+to borg (maybe implementing your own recursion or your own rules), you can use
+\fB\-\-paths\-from\-stdin\fP or \fB\-\-paths\-from\-command\fP (with the latter, borg will
+fail to create an archive should the command fail).
+.sp
+Borg supports paths with the slashdot hack to strip path prefixes here also.
+So, be careful not to unintentionally trigger that.
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-check(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-delete.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-DELETE" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-delete" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-delete \- Delete an existing repository or archives
 .SH SYNOPSIS
 .sp
@@ -48,15 +49,13 @@ with the \fB\-\-cache\-only\fP option, or keep the security info with the
 When in doubt, use \fB\-\-dry\-run \-\-list\fP to see what would be deleted.
 .sp
 When using \fB\-\-stats\fP, you will get some statistics about how much data was
-deleted \- the "Deleted data" deduplicated size there is most interesting as
+deleted \- the \(dqDeleted data\(dq deduplicated size there is most interesting as
 that is how much your repository will shrink.
-Please note that the "All archives" stats refer to the state after deletion.
+Please note that the \(dqAll archives\(dq stats refer to the state after deletion.
 .sp
-You can delete multiple archives by specifying their common prefix, if they
+You can delete multiple archives by specifying a shell pattern to match
-have one, using the \fB\-\-prefix PREFIX\fP option. You can also specify a shell
+multiple archives using the \fB\-\-glob\-archives GLOB\fP option (for more info on
-pattern to match multiple archives using the \fB\-\-glob\-archives GLOB\fP option
+these patterns, see \fIborg_patterns\fP).
-(for more info on these patterns, see \fIborg_patterns\fP). Note that these
-two options are mutually exclusive.
 .sp
 To avoid accidentally deleting archives, especially when using glob patterns,
 it might be helpful to use the \fB\-\-dry\-run\fP to test out the command without
@@ -73,7 +72,7 @@ repository or archive to delete
 .B ARCHIVE
 archives to delete
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-n\fP,\fB  \-\-dry\-run
@@ -96,18 +95,21 @@ keep the local security info when deleting a repository
 .TP
 .B  \-\-save\-space
 work slower, but using less space
+.TP
+.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS
+write checkpoint every SECONDS seconds (Default: 1800)
 .UNINDENT
 .SS Archive filters
 .INDENT 0.0
 .TP
 .BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX
-only consider archive names starting with this prefix.
+only consider archive names starting with this prefix. (deprecated)
 .TP
 .BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB
-only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
+only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see \(dqborg help patterns\(dq.
 .TP
 .BI \-\-sort\-by \ KEYS
-Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp
 .TP
 .BI \-\-first \ N
 consider first N archives after other filters were applied
@@ -119,20 +121,19 @@ consider last N archives after other filters were applied
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 # delete a single backup archive:
 $ borg delete /path/to/repo::Monday
 # actually free disk space:
 $ borg compact /path/to/repo
 
-# delete all archives whose names begin with the machine\(aqs hostname followed by "\-"
+# delete all archives whose names begin with the machine\(aqs hostname followed by \(dq\-\(dq
-$ borg delete \-\-prefix \(aq{hostname}\-\(aq /path/to/repo
+$ borg delete \-\-glob\-archives \(aq{hostname}\-*\(aq /path/to/repo
 
-# delete all archives whose names contain "\-2012\-"
+# delete all archives whose names contain \(dq\-2012\-\(dq
 $ borg delete \-\-glob\-archives \(aq*\-2012\-*\(aq /path/to/repo
 
-# see what would be deleted if delete was run without \-\-dry\-run
+# see what would be deleted if delete were run without \-\-dry\-run
 $ borg delete \-\-list \-\-dry\-run \-a \(aq*\-May\-*\(aq /path/to/repo
 
 # delete the whole repository and the related local cache:
@@ -142,14 +143,12 @@ repo                                 Mon, 2016\-02\-15 19:26:54
 root\-2016\-02\-15                      Mon, 2016\-02\-15 19:36:29
 newname                              Mon, 2016\-02\-15 19:50:19
 Type \(aqYES\(aq if you understand this and want to continue: YES
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-compact(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-diff.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-DIFF" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-diff" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-diff \- Diff contents of two archives
 .SH SYNOPSIS
 .sp
@@ -38,17 +39,84 @@ borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
 This command finds differences (file contents, user/group/mode) between archives.
 .sp
 A repository location and an archive name must be specified for REPO::ARCHIVE1.
-ARCHIVE2 is just another archive name in same repository (no repository location
+ARCHIVE2 is just another archive name in the same repository (no repository location
 allowed).
+.SS What is compared
 .sp
-For archives created with Borg 1.1 or newer diff automatically detects whether
+For each matching item in both archives, Borg reports:
-the archives are created with the same chunker params. If so, only chunk IDs
+.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
+.sp
+Only actual changes are included in the \(dqchanges\(dq list. For example, a modified entry with
+added=0 and removed=0 is omitted.
+.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
+.sp
+The \fB\-\-sort\fP option is deprecated and only sorts by path.
+.SS Performance considerations
+.sp
+For archives created with Borg 1.1 or newer, diff automatically detects whether
+the archives were created with the same chunker parameters. If so, only chunk IDs
 are compared, which is very fast.
 .sp
-For archives prior to Borg 1.1 chunk contents are compared by default.
+For archives prior to Borg 1.1, chunk contents are compared by default.
-If you did not create the archives with different chunker params,
+If you did not create the archives with different chunker parameters,
 pass \fB\-\-same\-chunker\-params\fP\&.
-Note that the chunker params changed from Borg 0.xx to 1.0.
+Note that the chunker parameters changed from Borg 0.xx to 1.0.
 .sp
 For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
 .SH OPTIONS
@@ -66,7 +134,7 @@ ARCHIVE2 name (no repository location allowed)
 .B PATH
 paths of items inside the archives to compare; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-numeric\-owner
@@ -79,12 +147,15 @@ only consider numeric user and group identifiers
 Override check of chunker parameters.
 .TP
 .B  \-\-sort
-Sort the output lines by file path.
+Sort the output by path (deprecated, use \-\-sort\-by=path).
-.TP
-.B  \-\-json\-lines
-Format output as JSON Lines.
 .UNINDENT
-.SS Exclusion options
+.IP "System Message: WARNING/2 (docs/borg-diff.rst:, line 119)"
+Option list ends without a blank line; unexpected unindent.
+.sp
+\-\-sort\-by FIELD[,FIELD...]      Advanced sorting: specify field(s) to sort by. Accepts a comma\-separated list. Prefix with > for descending or < for ascending (default).
+\-\-content\-only                  Only compare differences in content (exclude metadata differences)
+\-\-json\-lines                    Format output as JSON Lines.
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
@@ -103,8 +174,7 @@ read include/exclude patterns from PATTERNFILE, one per line
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ borg init \-e=none testrepo
 $ mkdir testdir
 $ cd testdir
@@ -114,10 +184,10 @@ $ touch file3
 $ borg create ../testrepo::archive1 .
 
 $ chmod a+x file1
-$ echo "something" >> file2
+$ echo \(dqsomething\(dq >> file2
 $ borg create ../testrepo::archive2 .
 
-$ echo "testing 123" >> file1
+$ echo \(dqtesting 123\(dq >> file1
 $ rm file3
 $ touch file4
 $ borg create ../testrepo::archive3 .
@@ -139,18 +209,24 @@ added           0 B file4
 removed         0 B file3
 
 $ borg diff \-\-json\-lines testrepo::archive1 archive3
-{"path": "file1", "changes": [{"type": "modified", "added": 17, "removed": 5}, {"type": "mode", "old_mode": "\-rw\-r\-\-r\-\-", "new_mode": "\-rwxr\-xr\-x"}]}
+{\(dqpath\(dq: \(dqfile1\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: 17, \(dqremoved\(dq: 5}, {\(dqtype\(dq: \(dqmode\(dq, \(dqold_mode\(dq: \(dq\-rw\-r\-\-r\-\-\(dq, \(dqnew_mode\(dq: \(dq\-rwxr\-xr\-x\(dq}]}
-{"path": "file2", "changes": [{"type": "modified", "added": 135, "removed": 252}]}
+{\(dqpath\(dq: \(dqfile2\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: 135, \(dqremoved\(dq: 252}]}
-{"path": "file4", "changes": [{"type": "added", "size": 0}]}
+{\(dqpath\(dq: \(dqfile4\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqadded\(dq, \(dqsize\(dq: 0}]}
-{"path": "file3", "changes": [{"type": "removed", "size": 0}]
+{\(dqpath\(dq: \(dqfile3\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqremoved\(dq, \(dqsize\(dq: 0}]}
-.ft P
+
-.fi
+# 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 testrepo::archive1 archive3
+    +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 SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-export-tar.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-EXPORT-TAR" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-export-tar" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-export-tar \- Export archive contents as a tarball
 .SH SYNOPSIS
 .sp
@@ -50,7 +51,7 @@ before writing it to FILE:
 .IP \(bu 2
 \&.tar.xz or .txz: xz
 .IP \(bu 2
-\&.tar.zstd: zstd
+\&.tar.zstd or .tar.zst: zstd
 .IP \(bu 2
 \&.tar.lz4: lz4
 .UNINDENT
@@ -66,7 +67,7 @@ BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported.
 Timestamp resolution is limited to whole seconds, not the nanosecond resolution
 otherwise supported by Borg.
 .sp
-A \fB\-\-sparse\fP option (as found in borg extract) is not supported.
+A \fB\-\-sparse\fP option (as found in \fBborg extract\fP) is not supported.
 .sp
 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.
@@ -86,12 +87,12 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 archive to export
 .TP
 .B FILE
-output tar file. "\-" to write to stdout instead.
+output tar file. \(dq\-\(dq to write to stdout instead.
 .TP
 .B PATH
 paths to extract; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-tar\-filter
@@ -100,7 +101,7 @@ filter program to pipe data through
 .B  \-\-list
 output verbose list of items (files, dirs, ...)
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
@@ -122,31 +123,28 @@ Remove the specified number of leading path elements. Paths with fewer elements
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
+# Export as an uncompressed tar.
-# export as uncompressed tar
 $ borg export\-tar /path/to/repo::Monday Monday.tar
 
-# exclude some types, compress using gzip
+# Exclude some types; compress using gzip.
 $ borg export\-tar /path/to/repo::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="gzip \-9" testrepo::linux Monday.tar.gz
+$ borg export\-tar \-\-tar\-filter=\(dqgzip \-9\(dq testrepo::linux Monday.tar.gz
 
-# export a tar, but instead of storing it on disk,
+# Export a tar, but instead of storing it on disk,
 # upload it to a remote site using curl.
 $ borg export\-tar /path/to/repo::Monday \- | curl \-\-data\-binary @\- https://somewhere/to/POST
 
-# remote extraction via "tarpipe"
+# Remote extraction via \(dqtarpipe\(dq.
-$ borg export\-tar /path/to/repo::Monday \- | ssh somewhere "cd extracted; tar x"
+$ borg export\-tar /path/to/repo::Monday \- | ssh somewhere \(dqcd extracted; tar x\(dq
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-extract.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,37 +28,41 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-EXTRACT" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-extract" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-extract \- Extract archive contents
 .SH SYNOPSIS
 .sp
 borg [common options] extract [options] ARCHIVE [PATH...]
 .SH DESCRIPTION
 .sp
-This command extracts the contents of an archive. By default the entire
+This command extracts the contents of an archive.
-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.
 .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,
+output data: reading metadata and data chunks from the repository, checking the hash/HMAC,
-decrypting, decompressing.
+decrypting, and decompressing.
 .sp
 \fB\-\-progress\fP can be slower than no progress display, since it makes one additional
 pass over the archive metadata.
 .sp
-\fBNOTE:\fP
+\fBNote:\fP
 .INDENT 0.0
 .INDENT 3.5
-Currently, extract always writes into the current working directory ("."),
+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,
+or any other reason), Borg cannot restore parent directories\(aq metadata, e.g., owner,
-group, permission, etc.
+group, permissions, etc.
 .UNINDENT
 .UNINDENT
 .SH OPTIONS
@@ -72,7 +77,7 @@ archive to extract
 .B PATH
 paths to extract; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-list
@@ -105,7 +110,7 @@ write all extracted data to stdout
 .B  \-\-sparse
 create holes in output sparse file from all\-zero chunks
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
@@ -127,8 +132,7 @@ Remove the specified number of leading path elements. Paths with fewer elements
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 # Extract entire archive
 $ borg extract /path/to/repo::my\-files
 
@@ -138,22 +142,23 @@ $ borg extract \-\-list /path/to/repo::my\-files
 # Verify whether an archive could be successfully extracted, but do not write files to disk
 $ borg extract \-\-dry\-run /path/to/repo::my\-files
 
-# Extract the "src" directory
+# Extract the \(dqsrc\(dq directory
 $ borg extract /path/to/repo::my\-files home/USERNAME/src
 
-# Extract the "src" directory but exclude object files
+# Extract the \(dqsrc\(dq directory but exclude object files
 $ borg extract /path/to/repo::my\-files home/USERNAME/src \-\-exclude \(aq*.o\(aq
 
+# Extract only the C files
+$ borg extract /path/to/repo::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 /path/to/repo::my\-sdx | dd of=/dev/sdx bs=10M
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-mount(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-import-tar.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-IMPORT-TAR" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-import-tar" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-import-tar \- Create a backup archive from a tarball
 .SH SYNOPSIS
 .sp
@@ -37,9 +38,9 @@ borg [common options] import\-tar [options] ARCHIVE TARFILE
 .sp
 This command creates a backup archive from a tarball.
 .sp
-When giving \(aq\-\(aq as path, Borg will read a tar stream from standard input.
+When giving \(aq\-\(aq as a path, Borg will read a tar stream from standard input.
 .sp
-By default (\-\-tar\-filter=auto) Borg will detect whether the file is compressed
+By default (\fB\-\-tar\-filter=auto\fP) Borg will detect whether the file is compressed
 based on its file extension and pipe the file through an appropriate filter:
 .INDENT 0.0
 .IP \(bu 2
@@ -49,16 +50,16 @@ based on its file extension and pipe the file through an appropriate filter:
 .IP \(bu 2
 \&.tar.xz or .txz: xz \-d
 .IP \(bu 2
-\&.tar.zstd: zstd \-d
+\&.tar.zstd or .tar.zst: zstd \-d
 .IP \(bu 2
 \&.tar.lz4: lz4 \-d
 .UNINDENT
 .sp
-Alternatively, a \-\-tar\-filter program may be explicitly specified. It should
+Alternatively, a \fB\-\-tar\-filter\fP program may be explicitly specified. It should
 read compressed data from stdin and output an uncompressed tar stream on
 stdout.
 .sp
-Most documentation of borg create applies. Note that this command does not
+Most documentation of \fBborg create\fP applies. Note that this command does not
 support excluding files.
 .sp
 import\-tar is a lossy conversion:
@@ -70,6 +71,10 @@ A \fB\-\-sparse\fP option (as found in borg create) is not supported.
 .sp
 import\-tar reads POSIX.1\-1988 (ustar), POSIX.1\-2001 (pax), GNU tar, UNIX V7 tar
 and SunOS tar with extended attributes.
+.sp
+To import multiple tarballs into a single archive, they can be simply
+concatenated (e.g. using \(dqcat\(dq) into a single file, and imported with an
+\fB\-\-ignore\-zeros\fP option to skip through the stop markers between them.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -80,9 +85,9 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 name of archive to create (must be also a valid directory name)
 .TP
 .B TARFILE
-input tar file. "\-" to read from stdin instead.
+input tar file. \(dq\-\(dq to read from stdin instead.
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-tar\-filter
@@ -99,6 +104,9 @@ only display items with the given status characters
 .TP
 .B  \-\-json
 output stats as JSON (implies \-\-stats)
+.TP
+.B  \-\-ignore\-zeros
+ignore zero\-filled blocks in the input tarball
 .UNINDENT
 .SS Archive options
 .INDENT 0.0
@@ -116,12 +124,11 @@ write checkpoint every SECONDS seconds (Default: 1800)
 specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095
 .TP
 .BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
-select compression algorithm, see the output of the "borg help compression" command for details.
+select compression algorithm, see the output of the \(dqborg help compression\(dq command for details.
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-info.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-INFO" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-info" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-info \- Show archive details such as disk space used
 .SH SYNOPSIS
 .sp
@@ -38,12 +39,12 @@ borg [common options] info [options] [REPOSITORY_OR_ARCHIVE]
 This command displays detailed information about the specified archive or repository.
 .sp
 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
+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.
 .sp
 Borg archives can only contain a limited amount of file metadata.
@@ -59,7 +60,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B REPOSITORY_OR_ARCHIVE
 repository or archive to display information about
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-json
@@ -69,13 +70,13 @@ format output as JSON
 .INDENT 0.0
 .TP
 .BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX
-only consider archive names starting with this prefix.
+only consider archive names starting with this prefix. (deprecated)
 .TP
 .BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB
-only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
+only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see \(dqborg help patterns\(dq.
 .TP
 .BI \-\-sort\-by \ KEYS
-Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp
 .TP
 .BI \-\-first \ N
 consider first N archives after other filters were applied
@@ -87,8 +88,7 @@ consider last N archives after other filters were applied
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ borg info /path/to/repo::2017\-06\-29T11:00\-srv
 Archive name: 2017\-06\-29T11:00\-srv
 Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
@@ -141,14 +141,12 @@ All archives:              121.82 TB            112.41 TB            215.42 GB
 
                        Unique chunks         Total chunks
 Chunk index:                 1015213            626934122
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-list(1)\fP, \fIborg\-diff(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-init.1

@@ -1,4 +1,6 @@
-.\" Man page generated from reStructuredText.
+'\" t
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,135 +29,151 @@ 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-INIT" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-init" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-init \- Initialize an empty repository
 .SH SYNOPSIS
 .sp
 borg [common options] init [options] [REPOSITORY]
 .SH DESCRIPTION
 .sp
-This command initializes an empty repository. A repository is a filesystem
+This command initializes an empty repository. A repository is a
-directory containing the deduplicated data from zero or more archives.
+filesystem directory containing the deduplicated data from zero or more
-.SS Encryption mode TLDR
+archives.
+.SS Encryption mode TL;DR
 .sp
-The encryption mode can only be configured when creating a new repository \-
+The encryption mode can only be configured when creating a new
-you can neither configure it on a per\-archive basis nor change the
+repository. You can neither configure encryption on a per\-archive
-encryption mode of an existing repository.
+basis, nor change the encryption mode of an existing repository. You
+should thus take possible future use into account when deciding on an
+encryption mode.
 .sp
-Use \fBrepokey\fP:
+As a general rule of thumb, use \fBrepokey\fP with a strong passphrase:
 .INDENT 0.0
 .INDENT 3.5
-.sp
-.nf
-.ft C
 borg init \-\-encryption repokey /path/to/repo
-.ft P
-.fi
 .UNINDENT
 .UNINDENT
 .sp
-Or \fBrepokey\-blake2\fP depending on which is faster on your client machines (see below):
+However, there are many reasons to choose differently. See the section
-.INDENT 0.0
+below for details. In any case, Borg will:
-.INDENT 3.5
-.sp
-.nf
-.ft C
-borg init \-\-encryption repokey\-blake2 /path/to/repo
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Borg will:
 .INDENT 0.0
 .IP 1. 3
-Ask you to come up with a passphrase.
+Ask you to enter a unique and strong passphrase.
 .IP 2. 3
-Create a borg key (which contains 3 random secrets. See \fIkey_files\fP).
+Create a random Borg key (which actually consists of three random
+secrets, see \fIkey_files\fP for details).
 .IP 3. 3
-Encrypt the key with your passphrase.
+Encrypt the Borg key with your passphrase.
 .IP 4. 3
-Store the encrypted borg key inside the repository directory (in the repo config).
+Store the encrypted Borg key inside the repository directory (with
-This is why it is essential to use a secure passphrase.
+\fBrepokey\fP and \fBrepokey\-blake2\fP modes; with \fBkeyfile\fP and
+\fBkeyfile\-blake2\fP modes the Borg key is stored in your home
+directory instead, see below). Since we usually have to assume that
+an attacker could gain access to the repository (that\(aqs why we
+encrypt the data in the first place), choosing a strong and unique
+passphrase is absolutely crucial.
 .IP 5. 3
-Encrypt and sign your backups to prevent anyone from reading or forging them unless they
+Encrypt and sign your backups with the Borg key to prevent anyone
-have the key and know the passphrase. Make sure to keep a backup of
+from reading or forging them unless they have the Borg key \fIand\fP
-your key \fBoutside\fP the repository \- do not lock yourself out by
+know the passphrase.
-"leaving your keys inside your car" (see \fIborg_key_export\fP).
-For remote backups the encryption is done locally \- 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
-your privacy.
 .IP 6. 3
-Use the key when extracting files to decrypt them and to verify that the contents of
+Use the Borg key to decrypt and thus access the data stored in your
-the backups have not been accidentally or maliciously altered.
+repository, e.g. when extracting files. The contents can also be
+verified to detect accidental corruption or malicious tampering.
 .UNINDENT
+.sp
+As you can see, you always need \fIboth\fP the Borg key and passphrase to
+access your data. Thus it\(aqs crucial to keep a backup of your key
+\fIoutside\fP both the repository and the system you create backups of.
+You can easily run into a \(dqleaving your keys inside your car\(dq situation
+otherwise. See \fIborg_key_export\fP to create a backup of your key
+(e.g., by printing it on paper).
+.sp
+Encryption is done locally \- i.e., if you back up to a remote machine,
+the remote machine neither sees your passphrase, nor your unencrypted
+Borg key, nor your unencrypted files. Chunking and ID generation are
+based on your key to improve privacy.
+.sp
+\fBAbout hardware acceleration:\fP
+.sp
+Borg encrypts data with AES, which is pretty fast thanks to hardware
+acceleration on basically all modern Intel, AMD, and ARM CPUs since
+around the early 2010s (very cheap models since the mid\-2010s).
+.sp
+As the hashing algorithm, Borg can use either SHA256 or BLAKE2b. ARM
+CPUs support hardware\-accelerated SHA256 hashing since ARMv7 with NEON
+(around 2011), or ARMv8 (around 2013). AMD CPUs support it since Zen 1
+(around 2017), i.e. all AMD Ryzen CPUs. Intel CPUs support it since Ice
+Lake on mobile (10th gen, around 2021), and Rocket Lake on desktop
+(11th gen, around 2021). Very cheap models have received support a few
+years later. If your CPU doesn\(aqt support hardware\-accelerated SHA256
+hashing, you might want to give BLAKE2b hashing a try \- it\(aqs likely
+faster then. So, instead of \fBrepokey\fP mode, use \fBrepokey\-blake2\fP
+(or any of the other \fB\-blake2\fP modes for that matter).
+.sp
+Hardware acceleration is always used automatically when available.
 .SS Picking a passphrase
 .sp
-Make sure you use a good passphrase. Not too short, not too simple. The real
+Make sure you use a good passphrase. Not too short, not too simple. The
-encryption / decryption key is encrypted with / locked by your passphrase.
+real encryption / decryption key is encrypted with / locked by your
-If an attacker gets your key, he can\(aqt unlock and use it without knowing the
+passphrase. If an attacker gets your borg key, they can\(aqt unlock and use
-passphrase.
+it without knowing the passphrase.
 .sp
-Be careful with special or non\-ascii characters in your passphrase:
+Be careful with special or non\-ASCII characters in your passphrase:
 .INDENT 0.0
 .IP \(bu 2
-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
-so it does not have problems dealing with even the strangest characters.
+it does not have problems dealing with even the strangest characters.
 .IP \(bu 2
-BUT: that does not necessarily apply to your OS / VM / keyboard configuration.
+BUT: that does not necessarily apply to your OS / VM / keyboard
+configuration.
 .UNINDENT
 .sp
-So better use a long passphrase made from simple ascii chars than one that
+So it is better to use a long passphrase made from simple ASCII
-includes non\-ascii stuff or characters that are hard/impossible to enter on
+characters than one that includes non\-ASCII characters or characters
-a different keyboard layout.
+that are hard or impossible to enter on a different keyboard layout.
 .sp
-You can change your passphrase for existing repos at any time, it won\(aqt affect
+You can change your passphrase for existing repositories at any time; it
-the encryption/decryption key or other secrets.
+won\(aqt affect the encryption/decryption key or other secrets. See
-.SS More encryption modes
+\fIborg_key_change\-passphrase\fP\&.
+.SS More about encryption modes
 .sp
-Only use \fB\-\-encryption none\fP if you are OK with anyone who has access to
+Choosing the right encryption mode isn\(aqt always easy and many factors
-your repository being able to read your backups and tamper with their
+can change which mode is best for you. However, note that you can\(aqt
-contents without you noticing.
+really do anything \fIwrong\fP if you choose \fBrepokey\fP with a strong
+passphrase. So, if you\(aqre not sure, choose \fBrepokey\fP (or
+\fBrepokey\-blake2\fP, depending on your hardware, see above).
 .sp
-If you want "passphrase and having\-the\-key" security, use \fB\-\-encryption keyfile\fP\&.
+Borg supports the following encryption modes:
-The key will be stored in your home directory (in \fB~/.config/borg/keys\fP).
-.sp
-If you do \fBnot\fP want to encrypt the contents of your backups, but still
-want to detect malicious tampering use \fB\-\-encryption authenticated\fP\&.
-.sp
-If \fBBLAKE2b\fP is faster than \fBSHA\-256\fP on your hardware, use \fB\-\-encryption authenticated\-blake2\fP,
-\fB\-\-encryption repokey\-blake2\fP or \fB\-\-encryption keyfile\-blake2\fP\&. Note: for remote backups
-the hashing is done on your local machine.
 .\" nanorst: inline-fill
 .
 .TS
-center;
+box center;
-|l|l|l|l|.
+l|l|l|l.
-_
 T{
 Hash/MAC
 T}	T{
-Not encrypted
+Not Encrypted
-no auth
-T}	T{
-Not encrypted,
-but authenticated
 T}	T{
 Encrypted (AEAD w/ AES)
-and authenticated
+T}
+_
+T{
+Not Authenticated
+T}	T{
+Authenticated
 T}
 _
 T{
 SHA\-256
 T}	T{
-none
+\fBnone\fP
 T}	T{
-\fIauthenticated\fP
+\fBauthenticated\fP
 T}	T{
-repokey
+\fBrepokey\fP
-keyfile
+\fBkeyfile\fP
 T}
 _
 T{
@@ -163,57 +181,106 @@ BLAKE2b
 T}	T{
 n/a
 T}	T{
-\fIauthenticated\-blake2\fP
+\fBauthenticated\-blake2\fP
 T}	T{
-\fIrepokey\-blake2\fP
+\fBrepokey\-blake2\fP
-\fIkeyfile\-blake2\fP
+\fBkeyfile\-blake2\fP
 T}
-_
 .TE
 .\" nanorst: inline-replace
 .
 .sp
-Modes \fImarked like this\fP in the above table are new in Borg 1.1 and are not
+Borg 1.0 and older support \fBnone\fP, \fBrepokey\fP, and \fBkeyfile\fP
-backwards\-compatible with Borg 1.0.x.
+modes only. If you need such old clients to be able to access your
+repo, you can\(aqt use any of the other modes.
 .sp
-On modern Intel/AMD CPUs (except very cheap ones), AES is usually
+\fBAbout modes without encryption:\fP
-hardware\-accelerated.
-BLAKE2b is faster than SHA256 on Intel/AMD 64\-bit CPUs
-(except AMD Ryzen and future CPUs with SHA extensions),
-which makes \fIauthenticated\-blake2\fP faster than \fInone\fP and \fIauthenticated\fP\&.
 .sp
-On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster
+Avoid using \fBnone\fP mode. If you think about using \fBnone\fP mode,
-than BLAKE2b\-256 there. NEON accelerates AES as well.
+please reconsider and be absolutely sure. Using any mode other than
+\fBnone\fP allows Borg to detect accidental corruption or malicious
+tampering with the repo. It also prevents denial\-of\-service attacks
+against clients. Instead of \fBnone\fP mode, you likely want to use
+\fBauthenticated\fP mode, or \fBrepokey\fP or \fBkeyfile\fP modes with an
+empty passphrase instead (see below).
 .sp
-Hardware acceleration is always used automatically when available.
+If you don\(aqt want to encrypt your data, use \fBauthenticated\fP or
+\fBauthenticated\-blake2\fP modes. These modes require a passphrase in
+normal operation, but in emergency situations you can access the repo
+without the passphrase with \fBBORG_WORKAROUNDS=authenticated_no_key\fP
+(see \fIenvironment\-variables\fP).
 .sp
-\fIrepokey\fP and \fIkeyfile\fP use AES\-CTR\-256 for encryption and HMAC\-SHA256 for
+If you just don\(aqt want to choose a passphrase, use \fBkeyfile\fP or
-authentication in an encrypt\-then\-MAC (EtM) construction. The chunk ID hash
+\fBkeyfile\-blake2\fP modes with an empty passphrase. These modes are
-is HMAC\-SHA256 as well (with a separate key).
+generally safe even without a passphrase, but keeping an offsite
-These modes are compatible with Borg 1.0.x.
+backup of the Borg key is also important then. See below for details.
 .sp
-\fIrepokey\-blake2\fP and \fIkeyfile\-blake2\fP are also authenticated encryption modes,
+If you can assure that an attacker can\(aqt gain access to your repo, e.g.
-but use BLAKE2b\-256 instead of HMAC\-SHA256 for authentication. The chunk ID
+when independently encrypting your repository disk or filesystem, you
-hash is a keyed BLAKE2b\-256 hash.
+can think about using \fBrepokey\fP or \fBrepokey\-blake2\fP modes with an
-These modes are new and \fInot\fP compatible with Borg 1.0.x.
+empty passphrase. However, keep in mind that if an attacker still
+somehow manages to gain access, they have full access to your repo. In
+such situations choosing \fBrepokey\fP over \fBauthenticated\fP mode has
+the advantage of allowing you to add a passphrase later using
+\fIborg_key_change\-passphrase\fP\&.
 .sp
-\fIauthenticated\fP mode uses no encryption, but authenticates repository contents
+\fBAbout modes with encryption:\fP
-through the same HMAC\-SHA256 hash as the \fIrepokey\fP and \fIkeyfile\fP modes (it uses it
-as the chunk ID hash). The key is stored like \fIrepokey\fP\&.
-This mode is new and \fInot\fP compatible with Borg 1.0.x.
 .sp
-\fIauthenticated\-blake2\fP is like \fIauthenticated\fP, but uses the keyed BLAKE2b\-256 hash
+With \fBrepokey\fP and \fBrepokey\-blake2\fP modes the key is stored with
-from the other blake2 modes.
+the repo and encrypted with your passphrase. If an attacker gains
-This mode is new and \fInot\fP compatible with Borg 1.0.x.
+access to your repo and knows the passphrase, he can access and tamper
+with the repo. The repo\(aqs security thus relies on the strength of your
+passphrase. Creating an offsite backup of your Borg key (e.g., by
+printing it on paper) is recommended, see \fIborg_key_export\fP\&.
 .sp
-\fInone\fP mode uses no encryption and no authentication. It uses SHA256 as chunk
+If you\(aqre thinking about storing the passphrase on the disk of the
-ID hash. This mode is not recommended, you should rather consider using an authenticated
+system you\(aqre backing up, consider using the \fBkeyfile\fP method
-or authenticated/encrypted mode. This mode has possible denial\-of\-service issues
+instead. It generally provides the same or better security then.
-when running \fBborg create\fP on contents controlled by an attacker.
+.sp
-Use it only for new repositories where no encryption is wanted \fBand\fP when compatibility
+With \fBkeyfile\fP and \fBkeyfile\-blake2\fP modes the key is stored on your
-with 1.0.x is important. If compatibility with 1.0.x is not important, use
+local machine (in \fB~/.config/borg/keys\fP) instead. An attacker gaining
-\fIauthenticated\-blake2\fP or \fIauthenticated\fP instead.
+access to your repo then needs both the Borg key, and your passphrase to
-This mode is compatible with Borg 1.0.x.
+access and tamper with the repo. However, if you lose the key, you lose
+access to the repo, too. You \fBmust\fP create an offsite backup of your
+Borg key, e.g. by printing it on paper. Storing a copy of the Borg key
+on the system you\(aqre creating backups of is \fBNOT\fP sufficient. Use
+\fIborg_key_export\fP to create the backup.
+.sp
+The \fBkeyfile\fP and \fBkeyfile\-blake2\fP modes allow for \(dqpassphrase and
+having\-the\-key\(dq security when using a strong passphrase, but can also
+be used with an empty passphrase. Storing a (easily readable)
+passphrase on the disk of the system you\(aqre backing up with
+\fBkeyfile\fP and \fBkeyfile\-blake2\fP modes adds no security over using an
+empty passphrase.
+.sp
+\fBTechnical details:\fP
+.sp
+\fBrepokey\fP and \fBkeyfile\fP use AES\-CTR\-256 for encryption and
+HMAC\-SHA256 for authentication in an encrypt\-then\-MAC (EtM)
+construction. The chunk ID hash is HMAC\-SHA256 (with a separate key).
+These modes are compatible with all Borg versions.
+.sp
+\fBrepokey\-blake2\fP and \fBkeyfile\-blake2\fP are also authenticated
+encryption modes, but use BLAKE2b\-256 instead of HMAC\-SHA256 for
+authentication. The chunk ID hash is a keyed BLAKE2b\-256 hash. These
+modes are only compatible with Borg 1.1 and later.
+.sp
+\fBauthenticated\fP mode uses no encryption, but authenticates repo
+contents through the same HMAC\-SHA256 hash as the \fBrepokey\fP and
+\fBkeyfile\fP modes (it uses it as the chunk ID hash). The key is stored
+like \fBrepokey\fP within the repo. This mode is only compatible with
+Borg 1.1 and later.
+.sp
+\fBauthenticated\-blake2\fP is like \fBauthenticated\fP, but uses the keyed
+BLAKE2b\-256 hash from the other BLAKE2b modes. This mode is only
+compatible with Borg 1.1 and later.
+.sp
+\fBnone\fP mode uses no encryption and no authentication. It uses SHA256
+as chunk ID hash. This mode is not recommended. You should instead
+consider using an authenticated or authenticated/encrypted mode. This
+mode has possible denial\-of\-service issues when running \fBborg create\fP
+on contents controlled by an attacker. See above for alternatives.
+This mode is compatible with all Borg versions.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -223,7 +290,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B REPOSITORY
 repository to create
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .BI \-e \ MODE\fR,\fB \ \-\-encryption \ MODE
@@ -242,8 +309,7 @@ create the parent directories of the repository directory, if they are missing.
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 # Local repository, repokey encryption, BLAKE2b (often faster, since Borg 1.1)
 $ borg init \-\-encryption=repokey\-blake2 /path/to/repo
 
@@ -257,14 +323,12 @@ $ borg init \-\-encryption=repokey\-blake2 user@hostname:backup
 # Remote repository (accesses a remote borg via ssh)
 # keyfile: stores the (encrypted) key into ~/.config/borg/keys/
 $ borg init \-\-encryption=keyfile user@hostname:backup
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-create(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-check(1)\fP, \fIborg\-list(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-key-change-passphrase.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,20 +28,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-PASSPHRASE" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-key-change-passphrase" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-key-change-passphrase \- Change repository key file passphrase
 .SH SYNOPSIS
 .sp
 borg [common options] key change\-passphrase [options] [REPOSITORY]
 .SH DESCRIPTION
 .sp
-The key files used for repository encryption are optionally passphrase
+The key files used for repository encryption are optionally passphrase\-
 protected. This command can be used to change this passphrase.
 .sp
 Please note that this command only changes the passphrase, but not any
-secret protected by it (like e.g. encryption/MAC keys or chunker seed).
+secret protected by it (e.g., encryption/MAC keys or the chunker seed).
-Thus, changing the passphrase after passphrase and borg key got compromised
+Thus, changing the passphrase after the passphrase and Borg key were compromised
 does not protect future (nor past) backups to the same repository.
 .SH OPTIONS
 .sp
@@ -52,15 +53,14 @@ REPOSITORY
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 # Create a key file protected repository
 $ borg init \-\-encryption=keyfile \-v /path/to/repo
-Initializing repository at "/path/to/repo"
+Initializing repository at \(dq/path/to/repo\(dq
 Enter new passphrase:
 Enter same passphrase again:
 Remember your passphrase. Your data will be inaccessible without it.
-Key in "/root/.config/borg/keys/mnt_backup" created.
+Key in \(dq/root/.config/borg/keys/mnt_backup\(dq created.
 Keep this key safe. Your data will be inaccessible without it.
 Synchronizing chunks cache...
 Archives: 0, w/ cached Idx: 0, w/ outdated Idx: 0, w/o cached Idx: 0.
@@ -78,8 +78,7 @@ Key updated
 # key file (creating or overwriting the output key)
 # (keyfile repositories only)
 $ BORG_KEY_FILE=/path/to/output\-key borg key import /path/to/repo /path/to/exported
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
@@ -87,20 +86,17 @@ Fully automated using environment variables:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ BORG_NEW_PASSPHRASE=old borg init \-e=repokey repo
-# now "old" is the current passphrase.
+# now \(dqold\(dq is the current passphrase.
 $ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change\-passphrase repo
-# now "new" is the current passphrase.
+# now \(dqnew\(dq is the current passphrase.
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-key-export.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,19 +28,35 @@ 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 "2022-02-19" "" "borg backup tool"
+.TH "borg-key-export" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-key-export \- Export the repository key for backup
 .SH SYNOPSIS
 .sp
 borg [common options] key export [options] [REPOSITORY] [PATH]
 .SH DESCRIPTION
 .sp
+This command backs up the borg key.
+.sp
 If repository encryption is used, the repository is inaccessible
-without the key. This command allows one to backup this essential key.
+without the borg key (and the passphrase that protects the borg key).
+If a repository is not encrypted, but authenticated, the borg key is
+still needed to access the repository normally.
+.sp
+For repositories using \fBkeyfile\fP encryption the key is kept locally
+on the system that is capable of doing backups. To guard against loss
+or corruption of this key, the key needs to be backed up independently
+of the main data backup.
+.sp
+For repositories using \fBrepokey\fP encryption or \fBauthenticated\fP mode
+the key is kept in the repository. A backup is thus not strictly needed,
+but guards against the repository becoming inaccessible if the key is
+corrupted or lost.
+.sp
 Note that the backup produced does not include the passphrase itself
 (i.e. the exported key stays encrypted). In order to regain access to a
 repository, one needs both the exported key and the original passphrase.
+Keep the exported key and the passphrase at safe places.
 .sp
 There are three backup formats. The normal backup format is suitable for
 digital storage as a file. The \fB\-\-paper\fP backup format is optimized
@@ -47,22 +64,11 @@ for printing and typing in while importing, with per line checks to
 reduce problems with manual input. The \fB\-\-qr\-html\fP creates a printable
 HTML template with a QR code and a copy of the \fB\-\-paper\fP\-formatted key.
 .sp
-For repositories using keyfile encryption the key is saved locally
-on the system that is capable of doing backups. To guard against loss
-of this key, the key needs to be backed up independently of the main
-data backup.
-.sp
-For repositories using the repokey encryption the key is saved in the
-repository in the config file. A backup is thus not strictly needed,
-but guards against the repository becoming inaccessible if the file
-is damaged for some reason.
-.sp
 Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 borg key export /path/to/repo > encrypted\-key\-backup
 borg key export \-\-paper /path/to/repo > encrypted\-key\-backup.txt
 borg key export \-\-qr\-html /path/to/repo > encrypted\-key\-backup.html
@@ -70,8 +76,7 @@ borg key export \-\-qr\-html /path/to/repo > encrypted\-key\-backup.html
 borg key export /path/to/repo encrypted\-key\-backup
 borg key export \-\-paper /path/to/repo encrypted\-key\-backup.txt
 borg key export \-\-qr\-html /path/to/repo encrypted\-key\-backup.html
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .SH OPTIONS
@@ -85,7 +90,7 @@ REPOSITORY
 .B PATH
 where to store the backup
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-paper
@@ -97,7 +102,6 @@ Create an html file suitable for printing and later type\-in or qr scan
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-key\-import(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-key-import.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY-IMPORT" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-key-import" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-key-import \- Import the repository key from backup
 .SH SYNOPSIS
 .sp
@@ -39,12 +40,12 @@ This command restores a key previously backed up with the export command.
 .sp
 If the \fB\-\-paper\fP option is given, the import will be an interactive
 process in which each line is checked for plausibility before
-proceeding to the next line. For this format PATH must not be given.
+proceeding to the next line. For this format, PATH must not be provided.
 .sp
 For repositories using keyfile encryption, the key file which \fBborg key
 import\fP writes to depends on several factors. If the \fBBORG_KEY_FILE\fP
 environment variable is set and non\-empty, \fBborg key import\fP creates
-or overwrites that file named by \fB$BORG_KEY_FILE\fP\&. Otherwise, \fBborg
+or overwrites the file named by \fB$BORG_KEY_FILE\fP\&. Otherwise, \fBborg
 key import\fP searches in the \fB$BORG_KEYS_DIR\fP directory for a key file
 associated with the repository. If a key file is found in
 \fB$BORG_KEYS_DIR\fP, \fBborg key import\fP overwrites it; otherwise, \fBborg
@@ -60,7 +61,7 @@ REPOSITORY
 .B PATH
 path to the backup (\(aq\-\(aq to read from stdin)
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-paper
@@ -69,7 +70,6 @@ interactively import from a backup done with \fB\-\-paper\fP
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-key\-export(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-key-migrate-to-repokey.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-key-migrate-to-repokey" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
 .SH SYNOPSIS
 .sp
@@ -38,10 +39,10 @@ borg [common options] key migrate\-to\-repokey [options] [REPOSITORY]
 This command migrates a repository from passphrase mode (removed in Borg 1.0)
 to repokey mode.
 .sp
-You will be first asked for the repository passphrase (to open it in passphrase
+You will first be asked for the repository passphrase (to open it in passphrase
-mode). This is the same passphrase as you used to use for this repo before 1.0.
+mode). This is the same passphrase you used for this repository before 1.0.
 .sp
-It will then derive the different secrets from this passphrase.
+The different secrets will then be derived from this passphrase.
 .sp
 Then you will be asked for a new passphrase (twice, for safety). This
 passphrase will be used to protect the repokey (which contains these same
@@ -49,7 +50,7 @@ secrets in encrypted form). You may use the same passphrase as you used to
 use, but you may also use a different one.
 .sp
 After migrating to repokey mode, you can change the passphrase at any time.
-But please note: the secrets will always stay the same and they could always
+Please note: the secrets will always stay the same, and they could always
 be derived from your (old) passphrase\-mode passphrase.
 .SH OPTIONS
 .sp
@@ -60,7 +61,6 @@ REPOSITORY
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-key.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-key" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-key \- Manage a keyfile or repokey of a repository
 .SH SYNOPSIS
 .nf
@@ -41,7 +42,6 @@ borg [common options] key migrate\-to\-repokey ...
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP, \fIborg\-key\-migrate\-to\-repokey(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-list.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-LIST" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-list" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-list \- List archive or repository contents
 .SH SYNOPSIS
 .sp
@@ -50,7 +51,7 @@ repository or archive to list contents of
 .B PATH
 paths to list; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-consider\-checkpoints
@@ -60,25 +61,25 @@ Show checkpoint archives in the repository contents list (default: hidden).
 only print file/directory names, nothing else
 .TP
 .BI \-\-format \ FORMAT
-specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}")
+specify format for file or archive listing (default for files: \(dq{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}\(dq; for archives: \(dq{archive:<36} {time} [{id}]{NL}\(dq)
 .TP
 .B  \-\-json
-Only valid for listing repository contents. Format output as JSON. 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. A "barchive" key is therefore not available.
+Only valid for listing repository contents. Format output as JSON. 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. A \(dqbarchive\(dq key is therefore not available.
 .TP
 .B  \-\-json\-lines
-Only valid for listing archive contents. 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. A "bpath" key is therefore not available.
+Only valid for listing archive contents. 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. A \(dqbpath\(dq key is therefore not available.
 .UNINDENT
 .SS Archive filters
 .INDENT 0.0
 .TP
 .BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX
-only consider archive names starting with this prefix.
+only consider archive names starting with this prefix. (deprecated)
 .TP
 .BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB
-only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
+only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see \(dqborg help patterns\(dq.
 .TP
 .BI \-\-sort\-by \ KEYS
-Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp
 .TP
 .BI \-\-first \ N
 consider first N archives after other filters were applied
@@ -86,7 +87,7 @@ consider first N archives after other filters were applied
 .BI \-\-last \ N
 consider last N archives after other filters were applied
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
@@ -105,8 +106,7 @@ read include/exclude patterns from PATTERNFILE, one per line
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ borg list /path/to/repo
 Monday                               Mon, 2016\-02\-15 19:15:11
 repo                                 Mon, 2016\-02\-15 19:26:54
@@ -122,14 +122,14 @@ lrwxrwxrwx root   root          0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdif
 \-rwxr\-xr\-x root   root       2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
 \&...
 
-$ borg list /path/to/repo::root\-2016\-02\-15 \-\-pattern "\- bin/ba*"
+$ borg list /path/to/repo::root\-2016\-02\-15 \-\-pattern \(dq\- bin/ba*\(dq
 drwxr\-xr\-x root   root          0 Mon, 2016\-02\-15 17:44:27 .
 drwxrwxr\-x root   root          0 Mon, 2016\-02\-15 19:04:49 bin
 lrwxrwxrwx root   root          0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff
 \-rwxr\-xr\-x root   root       2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
 \&...
 
-$ borg list /path/to/repo::archiveA \-\-format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
+$ borg list /path/to/repo::archiveA \-\-format=\(dq{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}\(dq
 drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 .
 drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code
 drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code/myproject
@@ -137,29 +137,27 @@ drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code/myproject
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text
 \&...
 
-$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:\e.ext$\(aq
+$ borg list /path/to/repo/::archiveA \-\-pattern \(aq+ re:\e.ext$\(aq \-\-pattern \(aq\- re:^.*$\(aq
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
 \&...
 
-$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:.ext$\(aq
+$ borg list /path/to/repo/::archiveA \-\-pattern \(aq+ re:.ext$\(aq \-\-pattern \(aq\- re:^.*$\(aq
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text
 \&...
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .SH NOTES
 .SS The FORMAT specifier syntax
 .sp
-The \fB\-\-format\fP option uses python\(aqs \fI\%format string syntax\fP\&.
+The \fB\-\-format\fP option uses Python\(aqs format string syntax \%<https://\:docs\:.python\:.org/\:3\:.10/\:library/\:string\:.html#\:formatstrings>\&.
 .sp
 Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ borg list \-\-format \(aq{archive}{NL}\(aq /path/to/repo
 ArchiveFoo
 ArchiveBar
@@ -179,8 +177,7 @@ $ borg list \-\-format \(aq{mode} {user:6} {group:6} {size:8} {mtime} {path}{ext
 $ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}\(aq /path/to/repo::ArchiveFoo
 \-rw\-rw\-r\-\-   user   user 1024     Thu, 2021\-12\-09 10:22:17 file\-foo
 \&...
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
@@ -207,7 +204,7 @@ Keys available only when listing archives in a repository:
 .IP \(bu 2
 archive: archive name interpreted as text (might be missing non\-text characters, see barchive)
 .IP \(bu 2
-name: alias of "archive"
+name: alias of \(dqarchive\(dq
 .IP \(bu 2
 barchive: verbatim archive name, can contain any character except NUL
 .IP \(bu 2
@@ -217,9 +214,11 @@ bcomment: verbatim archive comment, can contain any character except NUL
 .IP \(bu 2
 id: internal ID of the archive
 .IP \(bu 2
+tam: TAM authentication state of this archive
+.IP \(bu 2
 start: time (start) of creation of the archive
 .IP \(bu 2
-time: alias of "start"
+time: alias of \(dqstart\(dq
 .IP \(bu 2
 end: time (end) of creation of the archive
 .IP \(bu 2
@@ -309,14 +308,13 @@ archiveid
 .IP \(bu 2
 archivename
 .IP \(bu 2
-extra: prepends {source} with " \-> " for soft links and " link to " for hard links
+extra: prepends {source} with \(dq \-> \(dq for soft links and \(dq link to \(dq for hard links
 .IP \(bu 2
-health: either "healthy" (file ok) or "broken" (if file has all\-zero replacement chunks)
+health: either \(dqhealthy\(dq (file ok) or \(dqbroken\(dq (if file has all\-zero replacement chunks)
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-info(1)\fP, \fIborg\-diff(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-patterns(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-mount.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,18 +28,42 @@ 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 "2022-02-19" "" "borg backup tool"
+.TH "borg-mount" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
 .sp
 borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
 .SH DESCRIPTION
 .sp
-This command mounts an archive as a FUSE filesystem. This can be useful for
+This command mounts a repository or an archive as a FUSE filesystem.
-browsing an archive or restoring individual files. Unless the \fB\-\-foreground\fP
+This can be useful for browsing or restoring individual files.
-option is given the command will run in the background until the filesystem
+.sp
-is \fBumounted\fP\&.
+When restoring, take into account that the current FUSE implementation does
+not support special filesystem flags and ACLs.
+.sp
+When mounting a repository, the top directories will be named like the
+archives and the directory structure below these will be loaded on\-demand from
+the repository when entering these directories, so expect some delay.
+.sp
+Care should be taken, as Borg backs up symlinks as\-is. When an archive
+or repository is mounted, it is possible to “jump” outside the mount point
+by following a symlink. If this happens, files or directories (or versions of them)
+that are not part of the archive or repository may appear to be within the mount point.
+.sp
+Unless the \fB\-\-foreground\fP option is given the command will run in the
+background until the filesystem is \fBunmounted\fP\&.
+.sp
+Performance tips:
+.INDENT 0.0
+.IP \(bu 2
+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.
+.IP \(bu 2
+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
 used in fstab entries:
@@ -59,7 +84,7 @@ 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
+(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
 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,
@@ -69,16 +94,16 @@ manually. Unlike the \fBuid\fP and \fBgid\fP mount options which affect all file
 Additional mount options supported by borg:
 .INDENT 0.0
 .IP \(bu 2
-versions: when used with a repository mount, this gives a merged, versioned
+\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; the layout may change in the future.
 .IP \(bu 2
-allow_damaged_files: by default damaged files (where missing chunks were
+\fBallow_damaged_files\fP: by default damaged files (where missing chunks were
-replaced with runs of zeros by borg check \fB\-\-repair\fP) are not readable and
+replaced with runs of zeros by \fBborg check \-\-repair\fP) are not readable and
 return EIO (I/O error). Set this option to read such files.
 .IP \(bu 2
-ignore_permissions: for security reasons the "default_permissions" mount
+\fBignore_permissions\fP: for security reasons the \fBdefault_permissions\fP mount
-option is internally enforced by borg. "ignore_permissions" can be given to
+option is internally enforced by borg. \fBignore_permissions\fP can be given to
-not enforce "default_permissions".
+not enforce \fBdefault_permissions\fP\&.
 .UNINDENT
 .sp
 The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users
@@ -90,8 +115,15 @@ When the daemonized process receives a signal or crashes, it does not unmount.
 Unmounting in these cases could cause an active rsync or similar process
 to unintentionally delete data.
 .sp
-When running in the foreground ^C/SIGINT unmounts cleanly, but other
+When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
-signals or crashes do not.
+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.
@@ -107,7 +139,7 @@ where to mount filesystem
 .B PATH
 paths to extract; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-consider\-checkpoints
@@ -129,13 +161,13 @@ use numeric user and group identifiers from archive(s)
 .INDENT 0.0
 .TP
 .BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX
-only consider archive names starting with this prefix.
+only consider archive names starting with this prefix. (deprecated)
 .TP
 .BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB
-only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
+only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see \(dqborg help patterns\(dq.
 .TP
 .BI \-\-sort\-by \ KEYS
-Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp
 .TP
 .BI \-\-first \ N
 consider first N archives after other filters were applied
@@ -143,7 +175,7 @@ consider first N archives after other filters were applied
 .BI \-\-last \ N
 consider last N archives after other filters were applied
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
@@ -164,7 +196,6 @@ Remove the specified number of leading path elements. Paths with fewer elements
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-umount(1)\fP, \fIborg\-extract(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-patterns.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,48 +28,45 @@ 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 "2022-02-19" "" "borg backup tool"
+.TH "borg-patterns" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-patterns \- Details regarding patterns
 .SH DESCRIPTION
 .sp
-The path/filenames used as input for the pattern matching start from the
+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
-So, when you give \fIrelative/\fP as root, the paths going into the matcher
+Be careful, your patterns must match the archived paths:
-will look like \fIrelative/.../file.ext\fP\&. When you give \fI/absolute/\fP as
+.INDENT 0.0
-root, they will look like \fI/absolute/.../file.ext\fP\&.
+.IP \(bu 2
-.sp
+Archived paths never start with a leading slash (\(aq/\(aq), nor with \(aq.\(aq, nor with \(aq..\(aq.
-File paths in Borg archives are always stored normalized and relative.
+.INDENT 2.0
-This means that e.g. \fBborg create /path/to/repo ../some/path\fP will
+.IP \(bu 2
-store all files as \fIsome/path/.../file.ext\fP and \fBborg create
+When you back up absolute paths like \fB/home/user\fP, the archived
-/path/to/repo /home/user\fP will store all files as
+paths start with \fBhome/user\fP\&.
-\fIhome/user/.../file.ext\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
 A directory exclusion pattern can end either with or without a slash (\(aq/\(aq).
 If it ends with a slash, such as \fIsome/path/\fP, the directory will be
 included but not its content. If it does not end with a slash, such as
 \fIsome/path\fP, both the directory and content will be excluded.
 .sp
-File patterns support these styles: fnmatch, shell, regular expressions,
+Borg supports different pattern styles. To define a non\-default
-path prefixes and path full\-matches. By default, fnmatch is used for
+style for a specific pattern, prefix it with two characters followed
-\fB\-\-exclude\fP patterns and shell\-style is used for the \fB\-\-pattern\fP
+by a colon \(aq:\(aq (i.e. \fBfm:path/*\fP, \fBsh:path/**\fP).
-option. For commands that support patterns in their \fBPATH\fP argument
-like (\fBborg list\fP), the default pattern is path prefix.
 .sp
-Starting with Borg 1.2, for all but regular expression pattern matching
+The default pattern style for \fB\-\-exclude\fP differs from \fB\-\-pattern\fP, see below.
-styles, all paths are treated as relative, meaning that a leading path
-separator is removed after normalizing and before matching. This allows
-you to use absolute or relative patterns arbitrarily.
-.sp
-If followed by a colon (\(aq:\(aq) the first two characters of a pattern are
-used as a style selector. Explicit style selection is necessary when a
-non\-default style is desired or when the desired pattern starts with
-two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP).
 .INDENT 0.0
 .TP
-.B \fI\%Fnmatch\fP, selector \fIfm:\fP
+.B Fnmatch \%<https://\:docs\:.python\:.org/\:3/\:library/\:fnmatch\:.html>, selector \fIfm:\fP
 This is the default style for \fB\-\-exclude\fP and \fB\-\-exclude\-from\fP\&.
 These patterns use a variant of shell pattern syntax, with \(aq*\(aq matching
 any number of characters, \(aq?\(aq matching any single character, \(aq[...]\(aq
@@ -98,8 +96,8 @@ path and any substring match is sufficient. It is strongly recommended to
 anchor patterns to the start (\(aq^\(aq), to the end (\(aq$\(aq) or both. Path
 separators (backslash for Windows and \(aq/\(aq on other systems) in paths are
 always normalized to a forward slash (\(aq/\(aq) before applying a pattern. The
-regular expression syntax is described in the \fI\%Python documentation for
+regular expression syntax is described in the Python documentation for
-the re module\fP\&.
+the re module \%<https://\:docs\:.python\:.org/\:3/\:library/\:re\:.html>\&.
 .TP
 .B Path prefix, selector \fIpp:\fP
 This pattern style is useful to match whole sub\-directories. The pattern
@@ -122,7 +120,7 @@ Other include/exclude patterns that would normally match will be ignored.
 Same logic applies for exclude.
 .UNINDENT
 .sp
-\fBNOTE:\fP
+\fBNote:\fP
 .INDENT 0.0
 .INDENT 3.5
 \fIre:\fP, \fIsh:\fP and \fIfm:\fP patterns are all implemented on top of the Python SRE
@@ -138,6 +136,15 @@ 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
+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:
+\fB\-\-pattern=\(aq\-path/item name\(aq\fP
+Note that when patterns are used within a pattern file directly read by borg,
+e.g. when using \fB\-\-exclude\-from\fP or \fB\-\-patterns\-from\fP, there is no shell
+involved and thus no quotation marks are required.
+.sp
 The \fB\-\-exclude\-from\fP option permits loading exclusion patterns from a text
 file with one pattern per line. Lines empty or starting with the number sign
 (\(aq#\(aq) after removing whitespace on both ends are ignored. The optional style
@@ -152,50 +159,80 @@ Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
+# 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 backup /
+
+# Exclude the contents of \(ga\(ga/home/user/.cache\(ga\(ga:
+$ borg create \-e \(aqsh:home/user/.cache/**\(aq backup /home/user
+$ borg create \-e home/user/.cache/ backup /home/user
+
+# The file \(aq/home/user/.cache/important\(aq is *not* backed up:
+$ borg create \-e home/user/.cache/ backup / /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 backup /
 
 # Exclude \(aq/home/user/junk\(aq and \(aq/home/user/subdir/junk\(aq but
 # not \(aq/home/user/importantjunk\(aq or \(aq/etc/junk\(aq:
-$ borg create \-e \(aq/home/*/junk\(aq backup /
+$ borg create \-e \(aqhome/*/junk\(aq backup /
-
-# Exclude the contents of \(aq/home/user/cache\(aq but not the directory itself:
-$ borg create \-e home/user/cache/ backup /
-
-# The file \(aq/home/user/cache/important\(aq is *not* backed up:
-$ borg create \-e /home/user/cache/ backup / /home/user/cache/important
 
 # The contents of directories in \(aq/home\(aq are not backed up when their name
 # ends in \(aq.tmp\(aq
-$ borg create \-\-exclude \(aqre:^/home/[^/]+\e.tmp/\(aq backup /
+$ borg create \-\-exclude \(aqre:^home/[^/]+\e.tmp/\(aq backup /
 
 # Load exclusions from file
 $ cat >exclude.txt <<EOF
 # Comment line
-/home/*/junk
+home/*/junk
 *.tmp
 fm:aa:something/*
-re:^/home/[^/]+\e.tmp/
+re:^home/[^/]+\e.tmp/
-sh:/home/*/.thumbnails
+sh:home/*/.thumbnails
 # Example with spaces, no need to escape as it is processed by borg
 some file with spaces.txt
 EOF
 $ borg create \-\-exclude\-from exclude.txt backup /
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
-A more general and easier to use way to define filename matching patterns exists
+A more general and easier to use way to define filename matching patterns
-with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using these, you may
+exists with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using
-specify the backup roots (starting points) and patterns for inclusion/exclusion.
+these, you may specify the backup roots, default pattern styles and
-A root path starts with the prefix \fIR\fP, followed by a path (a plain path, not a
+patterns for inclusion and exclusion.
-file pattern). An include rule starts with the prefix +, an exclude rule starts
+.INDENT 0.0
-with the prefix \-, an exclude\-norecurse rule starts with !, all followed by a pattern.
+.TP
+.B Root path prefix \fBR\fP
+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 (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 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.
+This has the same effect as the \fB\-\-exclude\fP option.
+.TP
+.B Exclude no\-recurse pattern prefix \fB!\fP
+Use the prefix \fB!\fP, followed by a pattern, to define an exclusion
+that does not recurse into subdirectories. This saves time, but
+prevents include patterns to match any files in subdirectories.
+.TP
+.B Include pattern prefix \fB+\fP
+Use the prefix \fB+\fP, followed by a pattern, to define inclusions.
+This is useful to include paths that are covered in an exclude
+pattern and would otherwise not be backed up.
+.UNINDENT
 .sp
-\fBNOTE:\fP
+\fBNote:\fP
 .INDENT 0.0
 .INDENT 3.5
 Via \fB\-\-pattern\fP or \fB\-\-patterns\-from\fP you can define BOTH inclusion and exclusion
@@ -204,13 +241,37 @@ of files using pattern prefixes \fB+\fP and \fB\-\fP\&. With \fB\-\-exclude\fP a
 .UNINDENT
 .UNINDENT
 .sp
-Inclusion patterns are useful to include paths that are contained in an excluded
+The first matching pattern is used, so if an include pattern matches
-path. The first matching pattern is used so if an include pattern matches before
+before an exclude pattern, the file is backed up. Note that a no\-recurse
-an exclude pattern, the file is backed up. If an exclude\-norecurse pattern matches
+exclude stops examination of subdirectories so that potential includes
-a directory, it won\(aqt recurse into it and won\(aqt discover any potential matches for
+will not match \- use normal excludes for such use cases.
-include rules below that directory.
 .sp
-\fBNOTE:\fP
+Example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+# Define the recursion root
+R /
+# Exclude all iso files in any directory
+\- **/*.iso
+# Explicitly include all inside etc and root
++ etc/**
++ root/**
+# Exclude a specific directory under each user\(aqs home directories
+\- home/*/.cache
+# Explicitly include everything in /home
++ home/**
+# Explicitly exclude some directories without recursing into them
+! re:^(dev|proc|run|sys|tmp)
+# Exclude all other files and directories
+# that are not specifically included earlier.
+\- **
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+\fBNote:\fP
 .INDENT 0.0
 .INDENT 3.5
 It\(aqs possible that a sub\-directory/file is matched while parent directories are not.
@@ -231,16 +292,14 @@ Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 # backup pics, but not the ones from 2018, except the good ones:
 # note: using = is essential to avoid cmdline argument parsing issues.
 borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 repo::arch pics
 
 # use a file with patterns:
 borg create \-\-patterns\-from patterns.lst repo::arch
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
@@ -248,26 +307,24 @@ The patterns.lst file could look like that:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
+# \(dqsh:\(dq pattern style is the default, so the following line is not needed:
-# "sh:" pattern style is the default, so the following line is not needed:
 P sh
 R /
 # can be rebuild
-\- /home/*/.cache
+\- home/*/.cache
 # they\(aqre downloads for a reason
-\- /home/*/Downloads
+\- home/*/Downloads
 # susan is a nice person
 # include susans home
-+ /home/susan
++ home/susan
 # also back up this exact file
-+ pf:/home/bobby/specialfile.txt
++ pf:home/bobby/specialfile.txt
 # don\(aqt backup the other home directories
-\- /home/*
+\- home/*
 # don\(aqt even look in /proc
-! /proc
+! proc
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
@@ -275,13 +332,11 @@ You can specify recursion roots either on the command line or in a patternfile:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 # these two commands do the same thing
-borg create \-\-exclude /home/bobby/junk repo::arch /home/bobby /home/susan
+borg create \-\-exclude home/bobby/junk repo::arch /home/bobby /home/susan
 borg create \-\-patterns\-from patternfile.lst repo::arch
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
@@ -289,23 +344,20 @@ The patternfile:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 # note that excludes use fm: by default and patternfiles use sh: by default.
 # therefore, we need to specify fm: to have the same exact behavior.
 P fm
 R /home/bobby
 R /home/susan
 
-\- /home/bobby/junk
+\- home/bobby/junk
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
 This allows you to share the same patterns between multiple repositories
 without needing to specify them on the command line.
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-placeholders.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-PLACEHOLDERS" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-placeholders" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-placeholders \- Details regarding placeholders
 .SH DESCRIPTION
 .sp
@@ -47,11 +48,11 @@ The full name of the machine in reverse domain name notation.
 .TP
 .B {now}
 The current local date and time, by default in ISO\-8601 format.
-You can also supply your own \fI\%format string\fP, e.g. {now:%Y\-%m\-%d_%H:%M:%S}
+You can also supply your own format string \%<https://\:docs\:.python\:.org/\:3\:.10/\:library/\:datetime\:.html#\:strftime-and-strptime-behavior>, 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 \fI\%format string\fP, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S}
+You can also supply your own format string \%<https://\:docs\:.python\:.org/\:3\:.10/\:library/\:datetime\:.html#\:strftime-and-strptime-behavior>, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S}
 .TP
 .B {user}
 The user name (or UID, if no name is available) of the user running borg.
@@ -76,11 +77,9 @@ If literal curly braces need to be used, double them for escaping:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 borg create /path/to/repo::{{literal_text}}
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
@@ -88,17 +87,15 @@ Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 borg create /path/to/repo::{hostname}\-{user}\-{utcnow} ...
 borg create /path/to/repo::{hostname}\-{now:%Y\-%m\-%d_%H:%M:%S} ...
-borg prune \-\-prefix \(aq{hostname}\-\(aq ...
+borg prune \-\-glob\-archives \(aq{hostname}\-*\(aq ...
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
-\fBNOTE:\fP
+\fBNote:\fP
 .INDENT 0.0
 .INDENT 3.5
 systemd uses a difficult, non\-standard syntax for command lines in unit files (refer to
@@ -111,7 +108,6 @@ double all percent signs (\fB{hostname}\-{now:%Y\-%m\-%d_%H:%M:%S}\fP
 becomes \fB{hostname}\-{now:%%Y\-%%m\-%%d_%%H:%%M:%%S}\fP).
 .UNINDENT
 .UNINDENT
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-prune.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-PRUNE" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-prune" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-prune \- Prune repository archives according to specified rules
 .SH SYNOPSIS
 .sp
@@ -42,7 +43,7 @@ Important: Repository disk space is \fBnot\fP freed until you run \fBborg compac
 .sp
 This command is normally used by automated backup scripts wanting to keep a
 certain number of historic backups. This retention policy is commonly referred to as
-\fI\%GFS\fP
+GFS \%<https://\:en\:.wikipedia\:.org/\:wiki/\:Backup_rotation_scheme#\:Grandfather-father-son>
 (Grandfather\-father\-son) backup rotation scheme.
 .sp
 Also, prune automatically removes checkpoint archives (incomplete archives left
@@ -61,10 +62,10 @@ If you have multiple sequences of archives with different data sets (e.g.
 from different machines) in one shared repository, use one prune call per
 data set that matches only the respective archives using the \-P option.
 .sp
-The \fB\-\-keep\-within\fP option takes an argument of the form "<int><char>",
+The \fB\-\-keep\-within\fP option takes an argument of the form \(dq<int><char>\(dq,
-where char is "H", "d", "w", "m", "y". For example, \fB\-\-keep\-within 2d\fP means
+where char is \(dqH\(dq, \(dqd\(dq, \(dqw\(dq, \(dqm\(dq, \(dqy\(dq. For example, \fB\-\-keep\-within 2d\fP means
 to keep all archives that were created within the past 48 hours.
-"1m" is taken to mean "31d". The archives kept with this option do not
+\(dq1m\(dq is taken to mean \(dq31d\(dq. The archives kept with this option do not
 count towards the totals specified by any other options.
 .sp
 A good procedure is to thin out more and more the older your backups get.
@@ -73,21 +74,25 @@ up to 7 most recent days with backups (days without backups do not count).
 The rules are applied from secondly to yearly, and backups selected by previous
 rules do not count towards those of later rules. The time that each backup
 starts is used for pruning purposes. Dates and times are interpreted in
-the local timezone, and weeks go from Monday to Sunday. Specifying a
+the local time zone, and weeks go from Monday to Sunday. Specifying a
-negative number of archives to keep means that there is no limit. As of borg
+negative number of archives to keep means that there is no limit. As of Borg
-1.2.0, borg will retain the oldest archive if any of the secondly, minutely,
+1.2.0, Borg will retain the oldest archive if any of the secondly, minutely,
-hourly, daily, weekly, monthly, or yearly rules was not otherwise able to meet
+hourly, daily, weekly, monthly, quarterly, or yearly rules was not otherwise
-its retention target. This enables the first chronological archive to continue
+able to meet its retention target. This enables the first chronological archive
-aging until it is replaced by a newer archive that meets the retention criteria.
+to continue aging until it is replaced by a newer archive that meets the
+retention criteria.
+.sp
+The \fB\-\-keep\-13weekly\fP and \fB\-\-keep\-3monthly\fP rules are two different
+strategies for keeping archives every quarter year.
 .sp
 The \fB\-\-keep\-last N\fP option is doing the same as \fB\-\-keep\-secondly N\fP (and it will
 keep the last N archives under the assumption that you do not create more than one
 backup archive in the same second).
 .sp
 When using \fB\-\-stats\fP, you will get some statistics about how much data was
-deleted \- the "Deleted data" deduplicated size there is most interesting as
+deleted \- the \(dqDeleted data\(dq deduplicated size there is most interesting as
 that is how much your repository will shrink.
-Please note that the "All archives" stats refer to the state after pruning.
+Please note that the \(dqAll archives\(dq stats refer to the state after pruning.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -97,7 +102,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B REPOSITORY
 repository to prune
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-n\fP,\fB  \-\-dry\-run
@@ -133,65 +138,71 @@ number of weekly archives to keep
 .B  \-m\fP,\fB  \-\-keep\-monthly
 number of monthly archives to keep
 .TP
+.B  \-\-keep\-13weekly
+number of quarterly archives to keep (13 week strategy)
+.TP
+.B  \-\-keep\-3monthly
+number of quarterly archives to keep (3 month strategy)
+.TP
 .B  \-y\fP,\fB  \-\-keep\-yearly
 number of yearly archives to keep
 .TP
 .B  \-\-save\-space
 work slower, but using less space
+.TP
+.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS
+write checkpoint every SECONDS seconds (Default: 1800)
 .UNINDENT
 .SS Archive filters
 .INDENT 0.0
 .TP
 .BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX
-only consider archive names starting with this prefix.
+only consider archive names starting with this prefix. (deprecated)
 .TP
 .BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB
-only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
+only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see \(dqborg help patterns\(dq.
 .UNINDENT
 .SH EXAMPLES
 .sp
-Be careful, prune is a potentially dangerous command, it will remove backup
+Be careful: prune is a potentially dangerous command; it will remove backup
 archives.
 .sp
-The default of prune is to apply to \fBall archives in the repository\fP unless
+By default, prune applies to \fBall archives in the repository\fP unless you
-you restrict its operation to a subset of the archives using \fB\-\-prefix\fP\&.
+restrict its operation to a subset of the archives using \fB\-\-glob\-archives\fP\&.
-When using \fB\-\-prefix\fP, be careful to choose a good prefix \- e.g. do not use a
+When using \fB\-\-glob\-archives\fP, be careful to choose a good matching pattern —
-prefix "foo" if you do not also want to match "foobar".
+for example, do not use \(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 can see what it would do without actually doing anything.
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
+# Keep 7 end\-of\-day and 4 additional end\-of\-week archives.
-# Keep 7 end of day and 4 additional end of week archives.
 # Do a dry\-run without actually deleting anything.
 $ borg prune \-v \-\-list \-\-dry\-run \-\-keep\-daily=7 \-\-keep\-weekly=4 /path/to/repo
 
 # Same as above but only apply to archive names starting with the hostname
-# of the machine followed by a "\-" character:
+# of the machine followed by a \(dq\-\(dq character:
-$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-prefix=\(aq{hostname}\-\(aq /path/to/repo
+$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-glob\-archives=\(aq{hostname}\-*\(aq /path/to/repo
-# actually free disk space:
+# Actually free disk space:
 $ borg compact /path/to/repo
 
-# Keep 7 end of day, 4 additional end of week archives,
+# Keep 7 end\-of\-day, 4 additional end\-of\-week archives,
-# and an end of month archive for every month:
+# and an end\-of\-month archive for every month:
 $ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo
 
-# Keep all backups in the last 10 days, 4 additional end of week archives,
+# Keep all backups in the last 10 days, 4 additional end\-of\-week archives,
-# and an end of month archive for every month:
+# and an end\-of\-month archive for every month:
 $ borg prune \-v \-\-list \-\-keep\-within=10d \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
-There is also a visualized prune example in \fBdocs/misc/prune\-example.txt\fP\&.
+There is also a visual example of pruning in \fBdocs/misc/prune\-example.txt\fP\&.
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-compact(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-recreate.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-RECREATE" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-recreate" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-recreate \- Re-create archives
 .SH SYNOPSIS
 .sp
@@ -37,13 +38,13 @@ borg [common options] recreate [options] [REPOSITORY_OR_ARCHIVE] [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 operation 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 "borg create", but they only check
+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.
 .sp
@@ -55,34 +56,34 @@ Due to how Borg stores compressed size information this might display
 incorrect information for archives that were not recreated at the same time.
 There is no risk of data loss by this.
 .sp
-\fB\-\-chunker\-params\fP will re\-chunk all files in the archive, this can be
+\fB\-\-chunker\-params\fP will re\-chunk all files in the archive; this can be
 used to have upgraded Borg 0.xx or Attic archives deduplicate with
 Borg 1.x archives.
 .sp
 \fBUSE WITH CAUTION.\fP
 Depending on the PATHs and patterns given, recreate can be used to permanently
 delete files from archives.
-When in doubt, use \fB\-\-dry\-run \-\-verbose \-\-list\fP to see how patterns/PATHS are
+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
 archive that is built during the operation exists at the same time at
-"<ARCHIVE>.recreate". The new archive will have a different archive ID.
+\(dq<ARCHIVE>.recreate\(dq. The new archive will have a different archive ID.
 .sp
-With \fB\-\-target\fP the original archive is not replaced, instead a new archive is created.
+With \fB\-\-target\fP the original archive is not replaced; instead, a new archive is created.
 .sp
 When rechunking (or recompressing), space usage can be substantial \- expect
 at least the entire deduplicated size of the archives using the previous
-chunker (or compression) params.
+chunker (or compression) parameters.
 .sp
-If you recently ran borg check \-\-repair and it had to fix lost chunks with all\-zero
+If you recently ran \fBborg check \-\-repair\fP and it had to fix lost chunks with all\-zero
 replacement chunks, please first run another backup for the same data and re\-run
-borg check \-\-repair afterwards to heal any archives that had lost chunks which are
+\fBborg check \-\-repair\fP afterwards to heal any archives that had lost chunks which are
 still generated from the input data.
 .sp
-Important: running borg recreate to re\-chunk will remove the chunks_healthy
+Important: running \fBborg recreate\fP to re\-chunk will remove the \fBchunks_healthy\fP
 metadata of all items with replacement chunks, so healing will not be possible
-any more after re\-chunking (it is also unlikely it would ever work: due to the
+anymore after re\-chunking (it is also unlikely it would ever work: due to the
 change of chunking parameters, the missing chunk likely will never be seen again
 even if you still have the data that produced it).
 .SH OPTIONS
@@ -97,7 +98,7 @@ repository or archive to recreate
 .B PATH
 paths to recreate; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-list
@@ -112,7 +113,7 @@ do not change anything
 .B  \-s\fP,\fB  \-\-stats
 print statistics at end
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
@@ -128,7 +129,7 @@ include/exclude paths matching PATTERN
 read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .B  \-\-exclude\-caches
-exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP)
+exclude directories that contain a CACHEDIR.TAG file (\%<http://\:www\:.bford\:.info/\:cachedir/\:spec\:.html>)
 .TP
 .BI \-\-exclude\-if\-present \ NAME
 exclude directories that are tagged by containing a filesystem object with the given NAME
@@ -152,56 +153,53 @@ add a comment text to the archive
 manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss format). alternatively, give a reference file/directory.
 .TP
 .BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
-select compression algorithm, see the output of the "borg help compression" command for details.
+select compression algorithm, see the output of the \(dqborg help compression\(dq command for details.
 .TP
 .BI \-\-recompress \ MODE
-recompress data chunks according to \fIMODE\fP and \fB\-\-compression\fP\&. Possible modes are \fIif\-different\fP: recompress if current compression is with a different compression algorithm (the level is not considered); \fIalways\fP: recompress even if current compression is with the same compression algorithm (use this to change the compression level); and \fInever\fP: do not recompress (use this option to explicitly prevent recompression). If no MODE is given, \fIif\-different\fP will be used. Not passing \-\-recompress is equivalent to "\-\-recompress never".
+recompress data chunks according to \fIMODE\fP and \fB\-\-compression\fP\&. Possible modes are \fIif\-different\fP: recompress if current compression is with a different compression algorithm (the level is not considered); \fIalways\fP: recompress even if current compression is with the same compression algorithm (use this to change the compression level); and \fInever\fP: do not recompress (use this option to explicitly prevent recompression). If no MODE is given, \fIif\-different\fP will be used. Not passing \-\-recompress is equivalent to \(dq\-\-recompress never\(dq.
 .TP
 .BI \-\-chunker\-params \ PARAMS
-specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or \fIdefault\fP to use the current defaults. default: buzhash,19,23,21,4095
+rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or \fIdefault\fP to use the chunker defaults. default: do not rechunk
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
+# Make old (Attic/Borg 0.xx) archives deduplicate with Borg 1.x archives.
-# Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives.
 # Archives created with Borg 1.1+ and the default chunker params are skipped
 # (archive ID stays the same).
 $ borg recreate /mnt/backup \-\-chunker\-params default \-\-progress
 
-# Create a backup with little but fast compression
+# Create a backup with low but fast compression.
 $ borg create /mnt/backup::archive /some/files \-\-compression lz4
-# Then compress it \- this might take longer, but the backup has already completed,
+# Then compress it — this might take longer, but the backup has already completed,
 # so no inconsistencies from a long\-running backup job.
 $ borg recreate /mnt/backup::archive \-\-recompress \-\-compression zlib,9
 
 # Remove unwanted files from all archives in a repository.
-# Note the relative path for the \-\-exclude option \- archives only contain relative paths.
+# Note the relative path for the \-\-exclude option — archives only contain relative paths.
 $ borg recreate /mnt/backup \-\-exclude home/icke/Pictures/drunk_photos
 
-# Change archive comment
+# Change the archive comment.
-$ borg create \-\-comment "This is a comment" /mnt/backup::archivename ~
+$ borg create \-\-comment \(dqThis is a comment\(dq /mnt/backup::archivename ~
 $ borg info /mnt/backup::archivename
 Name: archivename
 Fingerprint: ...
 Comment: This is a comment
 \&...
-$ borg recreate \-\-comment "This is a better comment" /mnt/backup::archivename
+$ borg recreate \-\-comment \(dqThis is a better comment\(dq /mnt/backup::archivename
 $ borg info /mnt/backup::archivename
 Name: archivename
 Fingerprint: ...
 Comment: This is a better comment
 \&...
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-rename.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-RENAME" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-rename" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-rename \- Rename an existing archive
 .SH SYNOPSIS
 .sp
@@ -54,8 +55,7 @@ the new archive name to use
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ borg create /path/to/repo::archivename ~
 $ borg list /path/to/repo
 archivename                          Mon, 2016\-02\-15 19:50:19
@@ -63,14 +63,12 @@ archivename                          Mon, 2016\-02\-15 19:50:19
 $ borg rename /path/to/repo::archivename newname
 $ borg list /path/to/repo
 newname                              Mon, 2016\-02\-15 19:50:19
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-serve.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-SERVE" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-serve" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-serve \- Start in server mode. This command is usually not used manually.
 .SH SYNOPSIS
 .sp
@@ -39,7 +40,7 @@ This command starts a repository server process. This command is usually not use
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .BI \-\-restrict\-to\-path \ PATH
@@ -49,14 +50,14 @@ restrict repository access to PATH. Can be specified multiple times to allow the
 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 directly point 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.
 .TP
 .B  \-\-append\-only
-only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running \fIdelete\fP or \fIprune\fP will still be allowed. See \fIappend_only_mode\fP in Additional Notes for more details.
+only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running \fIdelete\fP or \fIprune\fP or reading from the repository will still be allowed. See \fIappend_only_mode\fP in Additional Notes for more details.
 .TP
 .BI \-\-storage\-quota \ QUOTA
 Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.
 .UNINDENT
 .SH EXAMPLES
 .sp
-\fBborg serve\fP has special support for ssh forced commands (see \fBauthorized_keys\fP
+\fBborg serve\fP has special support for SSH forced commands (see \fBauthorized_keys\fP
 example below): if the environment variable SSH_ORIGINAL_COMMAND is set it will
 ignore some options given on the command line and use the values from the
 variable instead. This only applies to a carefully controlled allowlist of safe
@@ -71,44 +72,43 @@ giving up and aborting the operation when another process is holding a lock.
 .UNINDENT
 .sp
 Environment variables (such as BORG_XXX) contained in the original
-command sent by the client are \fInot\fP interpreted, but ignored. If BORG_XXX environment
+command sent by the client are \fInot\fP interpreted; they are ignored. If BORG_XXX environment
-variables should be set on the \fBborg serve\fP side, then these must be set in system\-specific
+variables need to be set on the \fBborg serve\fP side, then these must be set in system\-specific
 locations like \fB/etc/environment\fP or in the forced command itself (example below).
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
+# Allow an SSH key pair to only run borg, and only have access to /path/to/repo.
-# Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
 # Use key options to disable unneeded and potentially dangerous SSH functionality.
-# This will help to secure an automated remote backup system.
+# This helps secure an automated remote backup system.
 $ cat ~/.ssh/authorized_keys
-command="borg serve \-\-restrict\-to\-path /path/to/repo",restrict ssh\-rsa AAAAB3[...]
+command=\(dqborg serve \-\-restrict\-to\-path /path/to/repo\(dq,restrict ssh\-rsa AAAAB3[...]
 
-# Set a BORG_XXX environment variable on the "borg serve" side
+# Set a BORG_XXX environment variable on the \(ga\(gaborg serve\(ga\(ga side.
 $ cat ~/.ssh/authorized_keys
-command="export BORG_XXX=value; borg serve [...]",restrict ssh\-rsa [...]
+command=\(dqBORG_XXX=value borg serve [...]\(dq,restrict ssh\-rsa [...]
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
-\fBNOTE:\fP
+\fBNote:\fP
 .INDENT 0.0
 .INDENT 3.5
-The examples above use the \fBrestrict\fP directive. This does automatically
+The examples above use the \fBrestrict\fP directive and assume a POSIX\-compliant
-block potential dangerous ssh features, even when they are added in a future
+shell set as the user\(aqs login shell.
-update. Thus, this option should be preferred.
+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 explicitly specify
+If you\(aqre using OpenSSH server < 7.2, however, you have to explicitly specify
-the ssh features to restrict and cannot simply use the restrict option as it
+the SSH features to restrict and cannot simply use the \fBrestrict\fP option as it
-has been introduced in v7.2. We recommend to use
+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
 .UNINDENT
 .sp
-Details about sshd usage: \fI\%sshd(8)\fP
+Details about sshd usage: sshd(8) \%<https://\:www\:.openbsd\:.org/\:cgi-bin/\:man\:.cgi/\:OpenBSD-current/\:man8/\:sshd.8>
 .SS SSH Configuration
 .sp
 \fBborg serve\fP\(aqs pipes (\fBstdin\fP/\fBstdout\fP/\fBstderr\fP) are connected to the \fBsshd\fP process on the server side. In the event that the SSH connection between \fBborg serve\fP and the client is disconnected or stuck abnormally (for example, due to a network outage), it can take a long time for \fBsshd\fP to notice the client is disconnected. In the meantime, \fBsshd\fP continues running, and as a result so does the \fBborg serve\fP process holding the lock on the repository. This can cause subsequent \fBborg\fP operations on the remote repository to fail with the error: \fBFailed to create/acquire the lock\fP\&.
@@ -119,42 +119,56 @@ Either in the client side\(aqs \fB~/.ssh/config\fP file, or in the client\(aqs \
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 Host backupserver
         ServerAliveInterval 10
         ServerAliveCountMax 30
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
-Replacing \fBbackupserver\fP with the hostname, FQDN or IP address of the borg server.
+Replace \fBbackupserver\fP with the hostname, FQDN, or IP address of the Borg server.
 .sp
-This will cause the client to send a keepalive to the server every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the ssh client process will be terminated, causing the borg process to terminate gracefully.
+This will cause the client to send a keepalive to the server every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the SSH client process will be terminated, causing the Borg process to terminate gracefully.
 .sp
 On the server side\(aqs \fBsshd\fP configuration file (typically \fB/etc/ssh/sshd_config\fP):
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 ClientAliveInterval 10
 ClientAliveCountMax 30
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
-This will cause the server to send a keep alive to the client every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the server\(aqs sshd process will be terminated, causing the \fBborg serve\fP process to terminate gracefully and release the lock on the repository.
+This will cause the server to send a keepalive to the client every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the server\(aqs sshd process will be terminated, causing the \fBborg serve\fP process to terminate gracefully and release the lock on the repository.
 .sp
-If you then run borg commands with \fB\-\-lock\-wait 600\fP, this gives sufficient time for the borg serve processes to terminate after the SSH connection is torn down after the 300 second wait for the keepalives to fail.
+If you then run Borg commands with \fB\-\-lock\-wait 600\fP, this gives sufficient time for the \fBborg serve\fP processes to terminate after the SSH connection is torn down following the 300\-second wait for the keepalives to fail.
 .sp
 You may, of course, modify the timeout values demonstrated above to values that suit your environment and use case.
+.sp
+When the client is untrusted, it is a good idea to set the backup
+user\(aqs shell to a simple implementation (\fB/bin/sh\fP is only an example and may or may
+not be such a simple implementation):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+chsh \-s /bin/sh BORGUSER
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+Because the configured shell is used by openssh \%<https://\:www\:.openssh\:.com/>
+to execute the command configured through the \fBauthorized_keys\fP file
+using \fB\(dq$SHELL\(dq \-c \(dq$COMMAND\(dq\fP,
+setting a minimal shell implementation reduces the attack surface
+compared to when a feature\-rich and complex shell implementation is
+used.
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-umount.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,15 +28,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 "2022-02-19" "" "borg backup tool"
+.TH "borg-umount" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-umount \- un-mount 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.
@@ -52,8 +53,7 @@ mountpoint of the filesystem to umount
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 # Mounting the repository shows all archives.
 # Archives are loaded lazily, expect some delay when navigating to an archive
 # for the first time.
@@ -69,7 +69,7 @@ bin  boot  etc      home  lib  lib64  lost+found  media  mnt  opt
 root  sbin  srv  tmp  usr  var
 $ borg umount /tmp/mymountpoint
 
-# The "versions view" merges all archives in the repository
+# The \(dqversions view\(dq merges all archives in the repository
 # and provides a versioned view on files.
 $ borg mount \-o versions /path/to/repo /tmp/mymountpoint
 $ ls \-l /tmp/mymountpoint/home/user/doc.txt/
@@ -79,7 +79,7 @@ total 24
 $ borg umount /tmp/mymountpoint
 
 # Archive filters are supported.
-# These are especially handy for the "versions view",
+# These are especially handy for the \(dqversions view\(dq,
 # which does not support lazy processing of archives.
 $ borg mount \-o versions \-\-glob\-archives \(aq*\-my\-home\(aq \-\-last 10 /path/to/repo /tmp/mymountpoint
 
@@ -87,42 +87,44 @@ $ borg mount \-o versions \-\-glob\-archives \(aq*\-my\-home\(aq \-\-last 10 /pa
 # These can speed up mounting and lower memory needs significantly.
 $ borg mount /path/to/repo /tmp/mymountpoint only/that/path
 $ borg mount \-\-exclude \(aq...\(aq /path/to/repo /tmp/mymountpoint
-.ft P
+
-.fi
+# When using BORG_REPO env var, use :: as positional argument:
+export BORG_REPO=/path/to/repo
+# Mount the whole repo:
+borg mount :: /tmp/mymountpoint
+# Mount some specific archive:
+borg mount ::root\-2016\-02\-15 /tmp/mymountpoint
+.EE
 .UNINDENT
 .UNINDENT
 .SS borgfs
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ echo \(aq/mnt/backup /tmp/myrepo fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab
 $ echo \(aq/mnt/backup::root\-2016\-02\-15 /tmp/myarchive fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab
 $ mount /tmp/myrepo
 $ mount /tmp/myarchive
 $ ls /tmp/myrepo
-root\-2016\-02\-01 root\-2016\-02\-2015
+root\-2016\-02\-01 root\-2016\-02\-15
 $ ls /tmp/myarchive
 bin  boot  etc      home  lib  lib64  lost+found  media  mnt  opt  root  sbin  srv  tmp  usr  var
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
-\fBNOTE:\fP
+\fBNote:\fP
 .INDENT 0.0
 .INDENT 3.5
 \fBborgfs\fP will be automatically provided if you used a distribution
-package, \fBpip\fP or \fBsetup.py\fP to install Borg. Users of the
+package or \fBpip\fP to install Borg. Users of the standalone binary will have
-standalone binary will have to manually create a symlink (see
+to manually create a symlink (see \fIpyinstaller\-binary\fP).
-\fIpyinstaller\-binary\fP).
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-mount(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-upgrade.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +28,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-UPGRADE" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg-upgrade" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-upgrade \- upgrade a repository from a previous version
 .SH SYNOPSIS
 .sp
@@ -53,6 +54,23 @@ except when noted otherwise in the changelog
 .UNINDENT
 .SS Borg 1.x.y upgrades
 .sp
+Archive TAM authentication:
+.sp
+Use \fBborg upgrade \-\-archives\-tam REPO\fP to add archive TAMs to all
+archives that are not TAM authenticated yet.
+This is a convenient method to just trust all archives present \- if
+an archive does not have TAM authentication yet, a TAM will be added.
+Archives created by old borg versions < 1.0.9 do not have TAMs.
+Archives created by newer borg versions should have TAMs already.
+If you have a high\-risk environment, you should not just run this,
+but first verify that the archives are authentic and not malicious
+(== have good content, have a good timestamp).
+Borg 1.2.5+ needs all archives to be TAM authenticated for safety reasons.
+.sp
+This upgrade needs to be done once per repository.
+.sp
+Manifest TAM authentication:
+.sp
 Use \fBborg upgrade \-\-tam REPO\fP to require manifest authentication
 introduced with Borg 1.0.9 to address security issues. This means
 that modifying the repository after doing this with a version prior
@@ -69,7 +87,7 @@ If you routinely do this you might not want to enable this upgrade
 reverse the upgrade by issuing \fBborg upgrade \-\-disable\-tam REPO\fP\&.
 .sp
 See
-\fI\%https://borgbackup.readthedocs.io/en/stable/changes.html#pre\-1\-0\-9\-manifest\-spoofing\-vulnerability\fP
+\%<https://\:borgbackup\:.readthedocs\:.io/\:en/\:stable/\:changes\:.html#\:pre-1-0-9-manifest-spoofing-vulnerability>
 for details.
 .SS Attic and Borg 0.xx to Borg 1.x
 .sp
@@ -84,7 +102,7 @@ with the old chunks in the upgraded repository.
 See \fB\-\-chunker\-params\fP option of \fBborg create\fP and \fBborg recreate\fP\&.
 .sp
 \fBborg upgrade\fP will change the magic strings in the repository\(aqs
-segments to match the new Borg magic strings. The keyfiles found in
+segments to match the new Borg magic strings. The key files found in
 $ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and
 copied to $BORG_KEYS_DIR or ~/.config/borg/keys.
 .sp
@@ -92,20 +110,18 @@ The cache files are converted, from $ATTIC_CACHE_DIR or
 ~/.cache/attic to $BORG_CACHE_DIR or ~/.cache/borg, but the
 cache layout between Borg and Attic changed, so it is possible
 the first backup after the conversion takes longer than expected
-due to the cache resync.
+due to the cache re\-sync.
 .sp
 Upgrade should be able to resume if interrupted, although it
 will still iterate over all segments. If you want to start
-from scratch, use \fIborg delete\fP over the copied repository to
+from scratch, use \fBborg delete\fP over the copied repository to
 make sure the cache files are also removed:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 borg delete borg
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
@@ -131,7 +147,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B REPOSITORY
 path to the repository to be upgraded
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-n\fP,\fB  \-\-dry\-run
@@ -146,15 +162,23 @@ Force upgrade
 .B  \-\-tam
 Enable manifest authentication (in key and cache) (Borg 1.0.9 and later).
 .TP
+.B  \-\-check\-tam
+check manifest authentication (in key and cache).
+.TP
 .B  \-\-disable\-tam
 Disable manifest authentication (in key and cache).
+.TP
+.B  \-\-check\-archives\-tam
+check TAM authentication for all archives.
+.TP
+.B  \-\-archives\-tam
+add TAM authentication for all archives.
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 # Upgrade the borg repository to the most recent version.
 $ borg upgrade \-v /path/to/repo
 making a hardlink copy in /path/to/repo.before\-upgrade\-2016\-02\-15\-20:51:55
@@ -164,17 +188,16 @@ converting repo index /path/to/repo/index.0
 converting 1 segments...
 converting borg 0.xx to borg current
 no key file found for repository
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
-.SS Upgrading a passphrase encrypted attic repo
+.SS Upgrading a passphrase\-encrypted Attic repo
 .sp
-attic offered a "passphrase" encryption mode, but this was removed in borg 1.0
+Attic offered a \(dqpassphrase\(dq encryption mode, but this was removed in Borg 1.0
-and replaced by the "repokey" mode (which stores the passphrase\-protected
+and replaced by the \(dqrepokey\(dq mode (which stores the passphrase\-protected
-encryption key into the repository config).
+encryption key in the repository config).
 .sp
-Thus, to upgrade a "passphrase" attic repo to a "repokey" borg repo, 2 steps
+Thus, to upgrade a \(dqpassphrase\(dq Attic repo to a \(dqrepokey\(dq Borg repo, two steps
 are needed, in this order:
 .INDENT 0.0
 .IP \(bu 2
@@ -185,7 +208,6 @@ borg key migrate\-to\-repokey repo
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg-version.1

@@ -0,0 +1,81 @@
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "borg-version" "1" "2026-03-18" "" "borg backup tool"
+.SH Name
+borg-version \- Display the borg client / borg server version
+.SH SYNOPSIS
+.sp
+borg [common options] version [options] [REPOSITORY]
+.SH DESCRIPTION
+.sp
+This command displays the Borg client version / Borg server version.
+.sp
+If a local repository is given, the client code directly accesses the repository,
+thus we show the client version also as the server version.
+.sp
+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:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+# local repo (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)
+$ 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
+a simplified version is displayed (as provided by \fBborg.version.format_version\fP).
+.sp
+There is also \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.
+.SS arguments
+.INDENT 0.0
+.TP
+.B REPOSITORY
+repository (used to determine client/server situation)
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH Author
+The Borg Collective
+.\" End of generated man page.

docs/man/borg-with-lock.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,27 +28,35 @@ 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 "2022-02-19" "" "borg backup tool"
+.TH "borg-with-lock" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg-with-lock \- run a user specified command with the repository lock held
 .SH SYNOPSIS
 .sp
 borg [common options] with\-lock [options] REPOSITORY COMMAND [ARGS...]
 .SH DESCRIPTION
 .sp
-This command runs a user\-specified command while the repository lock is held.
+This command runs a user\-specified command while locking the repository. For example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ borg with\-lock /mnt/borgrepo rsync \-av /mnt/borgrepo /somewhere/else/borgrepo
+.EE
+.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
+running in the repository), then execute the given command as a subprocess and wait
-for its termination, release the lock and return the user command\(aqs return
+for its termination, release the lock, and return the user command\(aqs return
-code as borg\(aqs return code.
+code as Borg\(aqs return code.
 .sp
-\fBNOTE:\fP
+\fBNote:\fP
 .INDENT 0.0
 .INDENT 3.5
 If you copy a repository with the lock held, the lock will be present in
-the copy. Thus, before using borg on the copy from a different host,
+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
+you need to use \(dqborg break\-lock\(dq on the copied repository, because
 Borg is cautious and does not automatically remove stale locks made by a different host.
 .UNINDENT
 .UNINDENT
@@ -69,7 +78,6 @@ command arguments
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borg.1

@@ -1,4 +1,6 @@
-.\" Man page generated from reStructuredText.
+'\" t
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,8 +29,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG" 1 "2022-02-19" "" "borg backup tool"
+.TH "borg" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borg \- deduplicating and encrypting backup tool
 .SH SYNOPSIS
 .sp
@@ -58,11 +60,9 @@ Before a backup can be made a repository has to be initialized:
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ borg init \-\-encryption=repokey /path/to/repo
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .IP 2. 3
@@ -71,11 +71,9 @@ Backup the \fB~/src\fP and \fB~/Documents\fP directories into an archive called
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ borg create /path/to/repo::Monday ~/src ~/Documents
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .IP 3. 3
@@ -83,11 +81,9 @@ The next day create a new archive called \fITuesday\fP:
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ borg create \-\-stats /path/to/repo::Tuesday ~/src ~/Documents
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
@@ -98,8 +94,7 @@ data (not shared with other archives):
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 Archive name: Tuesday
 Archive fingerprint: bd31004d58f51ea06ff735d2e5ac49376901b21d58035f8fb05dbf866566e3c2
@@ -116,8 +111,7 @@ All archives:                8.33 MB              8.34 MB              4.19 MB
                       Unique chunks         Total chunks
 Chunk index:                     132                  261
 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .IP 4. 3
@@ -125,13 +119,11 @@ List all archives in the repository:
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ borg list /path/to/repo
 Monday                               Mon, 2016\-02\-15 19:14:44
 Tuesday                              Tue, 2016\-02\-16 19:15:11
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .IP 5. 3
@@ -139,14 +131,12 @@ List the contents of the \fIMonday\fP archive:
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ borg list /path/to/repo::Monday
 drwxr\-xr\-x user   group          0 Mon, 2016\-02\-15 18:22:30 home/user/Documents
 \-rw\-r\-\-r\-\- user   group       7961 Mon, 2016\-02\-15 18:22:30 home/user/Documents/Important.doc
 \&...
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .IP 6. 3
@@ -154,28 +144,34 @@ Restore the \fIMonday\fP archive by extracting the files relative to the current
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ borg extract /path/to/repo::Monday
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .IP 7. 3
-Recover disk space by manually deleting the \fIMonday\fP archive:
+Delete the \fIMonday\fP archive (please note that this does \fBnot\fP free repo disk space):
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 $ borg delete /path/to/repo::Monday
-.ft P
+.EE
-.fi
+.UNINDENT
+.UNINDENT
+.IP 8. 3
+Recover disk space by compacting the segment files in the repo:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.EX
+$ borg compact /path/to/repo
+.EE
 .UNINDENT
 .UNINDENT
 .UNINDENT
 .sp
-\fBNOTE:\fP
+\fBNote:\fP
 .INDENT 0.0
 .INDENT 3.5
 Borg is quiet by default (it works on WARNING log level).
@@ -194,18 +190,16 @@ in the example), but not in between them:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 borg create \-s \-\-progress repo::archive path  # good and preferred
 borg create repo::archive path \-s \-\-progress  # also works
 borg create \-s repo::archive path \-\-progress  # works, but ugly
 borg create repo::archive \-s \-\-progress path  # BAD
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
-This is due to a problem in the argparse module: \fI\%https://bugs.python.org/issue15112\fP
+This is due to a problem in the argparse module: \%<https://\:bugs\:.python\:.org/\:issue15112>
 .SS Repository URLs
 .sp
 \fBLocal filesystem\fP (or locally mounted network filesystem):
@@ -219,13 +213,21 @@ expanded by your shell).
 .sp
 Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style.
 .sp
-\fBRemote repositories\fP accessed via ssh \fI\%user@host\fP:
+\fBRemote repositories\fP accessed via ssh \%<user@\:host>:
 .sp
-\fBuser@host:/path/to/repo\fP \- remote repo, absolute path
+\fBssh://user@host:port/path/to/repo\fP \- remote repo, absolute path, port can be given
 .sp
-\fBssh://user@host:port/path/to/repo\fP \- same, alternative syntax, port can be given
+\fBuser@host:/path/to/repo\fP \- remote repo, absolute path, deprecated syntax
 .sp
-\fBRemote repositories with relative paths\fP can be given using this syntax:
+\fBRemote repositories with relative paths, URL style syntax with port\fP:
+.sp
+\fBssh://user@host:port/./path/to/repo\fP \- path relative to current directory
+.sp
+\fBssh://user@host:port/~/path/to/repo\fP \- path relative to user\(aqs home directory
+.sp
+\fBssh://user@host:port/~other/path/to/repo\fP \- path relative to other\(aqs home directory (deprecated)
+.sp
+\fBRemote repositories with relative paths, deprecated SCP style syntax\fP:
 .sp
 \fBuser@host:path/to/repo\fP \- path relative to current directory
 .sp
@@ -236,24 +238,14 @@ Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style
 Note: giving \fBuser@host:/./path/to/repo\fP or \fBuser@host:/~/path/to/repo\fP or
 \fBuser@host:/~other/path/to/repo\fP is also supported, but not required here.
 .sp
-\fBRemote repositories with relative paths, alternative syntax with port\fP:
-.sp
-\fBssh://user@host:port/./path/to/repo\fP \- path relative to current directory
-.sp
-\fBssh://user@host:port/~/path/to/repo\fP \- path relative to user\(aqs home directory
-.sp
-\fBssh://user@host:port/~other/path/to/repo\fP \- path relative to other\(aqs home directory
-.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:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 export BORG_REPO=\(aqssh://user@host:port/path/to/repo\(aq
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
@@ -285,11 +277,9 @@ If you want to capture the log output to a file, just redirect it:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
+.EX
-.ft C
 borg create repo::archive myfiles 2>> logfile
-.ft P
+.EE
-.fi
 .UNINDENT
 .UNINDENT
 .sp
@@ -320,7 +310,7 @@ to get critical level output.
 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.
 .sp
-\fBWARNING:\fP
+\fBWarning:\fP
 .INDENT 0.0
 .INDENT 3.5
 Options \fB\-\-critical\fP and \fB\-\-error\fP are provided for completeness,
@@ -331,9 +321,8 @@ their usage is not recommended as you might miss important information.
 .sp
 Borg can exit with the following return codes (rc):
 .TS
-center;
+box center;
-|l|l|.
+l|l.
-_
 T{
 Return code
 T}	T{
@@ -349,27 +338,40 @@ _
 T{
 1
 T}	T{
-warning (operation reached its normal end, but there were warnings \-\-
+generic warning (operation reached its normal end, but there were warnings \-\-
 you should check the log, logged as WARNING)
 T}
 _
 T{
 2
 T}	T{
-error (like a fatal error, a local or remote exception, the operation
+generic error (like a fatal error, a local or remote exception, the operation
 did not reach its normal end, logged as ERROR)
 T}
 _
 T{
+3..99
+T}	T{
+specific error (enabled by BORG_EXIT_CODES=modern)
+T}
+_
+T{
+100..127
+T}	T{
+specific warning (enabled by BORG_EXIT_CODES=modern)
+T}
+_
+T{
 128+N
 T}	T{
 killed by signal N (e.g. 137 == kill \-9)
 T}
-_
 .TE
 .sp
 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
 .SS Environment Variables
 .sp
 Borg uses some environment variables for automation:
@@ -413,7 +415,11 @@ be checked.
 Main usecase for this is to fully automate \fBborg change\-passphrase\fP\&.
 .TP
 .B BORG_DISPLAY_PASSPHRASE
-When set, use the value to answer the "display the passphrase for verification" question when defining a new passphrase for encrypted repositories.
+When set, use the value to answer the \(dqdisplay the passphrase for verification\(dq question when defining a new passphrase for encrypted repositories.
+.TP
+.B BORG_EXIT_CODES
+When set to \(dqmodern\(dq, the borg process will return more specific exit codes (rc).
+Default is \(dqlegacy\(dq and returns rc 2 for all errors, 1 for all warnings, 0 for success.
 .TP
 .B BORG_HOST_ID
 Borg usually computes a host id from the FQDN plus the results of \fBuuid.getnode()\fP (which usually returns
@@ -421,10 +427,10 @@ a unique id based on the MAC address of the network interface. Except if that MA
 that case it returns a random value, which is not what we want (because it kills automatic stale lock removal).
 So, if you have a all\-zero MAC address or other reasons to better externally control the host id, just set this
 environment variable to a unique value. If all your FQDNs are unique, you can just use the FQDN. If not,
-use \fI\%fqdn@uniqueid\fP\&.
+use \%<fqdn@\:uniqueid>\&.
 .TP
 .B BORG_LOGGING_CONF
-When set, use the given filename as \fI\%INI\fP\-style logging configuration.
+When set, use the given filename as INI \%<https://\:docs\:.python\:.org/\:3/\:library/\:logging\:.config\:.html#\:configuration-file-format>\-style logging configuration.
 A basic example conf can be found at \fBdocs/misc/logging.conf\fP\&.
 .TP
 .B BORG_RSH
@@ -433,7 +439,7 @@ a custom identity file \fBssh \-i /path/to/private/key\fP\&. See \fBman ssh\fP f
 the \fB\-\-rsh CMD\fP commandline option overrides the environment variable.
 .TP
 .B BORG_REMOTE_PATH
-When set, use the given path as borg executable on the remote (defaults to "borg" if unset).
+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.
 .TP
 .B BORG_FILES_CACHE_SUFFIX
@@ -442,15 +448,25 @@ When set to a value at least one character long, instructs borg to use a specifi
 cache entries for backup sources other than the current sources.
 .TP
 .B BORG_FILES_CACHE_TTL
-When set to a numeric value, this determines the maximum "time to live" for the files cache
+When set to a numeric value, this determines the maximum \(dqtime to live\(dq for the files cache
 entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
 The FAQ explains this more detailed in: \fIalways_chunking\fP
 .TP
+.B BORG_USE_CHUNKS_ARCHIVE
+When set to no (default: yes), the \fBchunks.archive.d\fP folder will not be used. This reduces
+disk space usage but slows down cache resyncs.
+.TP
 .B BORG_SHOW_SYSINFO
 When set to no (default: yes), system information (like OS, Python version, ...) in
 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\&.
 This is a comma\-separated list of implementation names, they are tried in the
@@ -495,23 +511,59 @@ write to disk behaviour (not continuously streaming to disk).
 Retry opening a file without O_NOATIME if opening a file with O_NOATIME
 caused EROFS. You will need this to make archives from volume shadow copies
 in WSL1 (Windows Subsystem for Linux 1).
+.TP
+.B authenticated_no_key
+Work around a lost passphrase or key for an \fBauthenticated\fP mode repository
+(these are only authenticated, but not encrypted).
+If the key is missing in the repository config, add \fBkey = anything\fP there.
+.sp
+This workaround is \fBonly\fP for emergencies and \fBonly\fP to extract data
+from an affected repository (read\-only access):
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.EX
+BORG_WORKAROUNDS=authenticated_no_key borg extract repo::archive
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+After you have extracted all data you need, you MUST delete the repository:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.EX
+BORG_WORKAROUNDS=authenticated_no_key borg delete repo
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+Now you can init a fresh repo. Make sure you do not use the workaround any more.
+.TP
+.B ignore_invalid_archive_tam
+Work around invalid archive TAMs created by borg < 1.2.5, see #7791\&.
+.sp
+This workaround likely needs to get used only once when following the upgrade
+instructions for CVE\-2023\-36811, see \fIarchives_tam_vuln\fP\&.
+.sp
+In normal production operations, this workaround should never be used.
 .UNINDENT
 .UNINDENT
 .TP
-.B Some automatic "answerers" (if set, they automatically answer confirmation questions):
+.B Some automatic \(dqanswerers\(dq (if set, they automatically answer confirmation questions):
 .INDENT 7.0
 .TP
 .B BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no (or =yes)
-For "Warning: Attempting to access a previously unknown unencrypted repository"
+For \(dqWarning: Attempting to access a previously unknown unencrypted repository\(dq
 .TP
 .B BORG_RELOCATED_REPO_ACCESS_IS_OK=no (or =yes)
-For "Warning: The repository at location ... was previously located at ..."
+For \(dqWarning: The repository at location ... was previously located at ...\(dq
 .TP
 .B BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
-For "This is a potentially dangerous function..." (check \-\-repair)
+For \(dqThis is a potentially dangerous function...\(dq (check \-\-repair)
 .TP
 .B BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
-For "You requested to completely DELETE the repository \fIincluding\fP all archives it contains:"
+For \(dqYou requested to completely DELETE the repository \fIincluding\fP all archives it contains:\(dq
 .UNINDENT
 .sp
 Note: answers are case sensitive. setting an invalid answer value might either give the default
@@ -531,32 +583,49 @@ to modify \fBBORG_BASE_DIR\fP: the other paths for cache, config etc. will adapt
 .TP
 .B BORG_CACHE_DIR
 Defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
-\fI\%XDG env var\fP \fBXDG_CACHE_HOME\fP is set, then \fB$XDG_CACHE_HOME/borg\fP is being used instead.
+XDG env var \%<https://\:specifications\:.freedesktop\:.org/\:basedir-spec/\:0\:.6/\:ar01s03\:.html> \fBXDG_CACHE_HOME\fP is set, then \fB$XDG_CACHE_HOME/borg\fP is being used instead.
 This directory contains the local cache and might need a lot
 of space for dealing with big repositories. Make sure you\(aqre aware of the associated
 security aspects of the cache location: \fIcache_security\fP
 .TP
 .B BORG_CONFIG_DIR
 Defaults to \fB$BORG_BASE_DIR/.config/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
-\fI\%XDG env var\fP \fBXDG_CONFIG_HOME\fP is set, then \fB$XDG_CONFIG_HOME/borg\fP is being used instead.
+XDG env var \%<https://\:specifications\:.freedesktop\:.org/\:basedir-spec/\:0\:.6/\:ar01s03\:.html> \fBXDG_CONFIG_HOME\fP is set, then \fB$XDG_CONFIG_HOME/borg\fP is being used instead.
 This directory contains all borg configuration directories, see the FAQ
 for a security advisory about the data in this directory: \fIhome_config_borg\fP
 .TP
 .B BORG_SECURITY_DIR
 Defaults to \fB$BORG_CONFIG_DIR/security\fP\&.
-This directory contains information borg uses to track its usage of NONCES ("numbers used
+This directory contains information borg uses to track its usage of NONCES (\(dqnumbers used
-once" \- usually in encryption context) and other security relevant data.
+once\(dq \- usually in encryption context) and other security relevant data.
 .TP
 .B BORG_KEYS_DIR
 Defaults to \fB$BORG_CONFIG_DIR/keys\fP\&.
 This directory contains keys for encrypted repositories.
 .TP
 .B BORG_KEY_FILE
-When set, use the given filename as repository key file.
+When set, use the given path as repository key file. Please note that this is only
+for rather special applications that externally fully manage the key files:
+.INDENT 7.0
+.IP \(bu 2
+this setting only applies to the keyfile modes (not to the repokey modes).
+.IP \(bu 2
+using a full, absolute path to the key file is recommended.
+.IP \(bu 2
+all directories in the given path must exist.
+.IP \(bu 2
+this setting forces borg to use the key file at the given location.
+.IP \(bu 2
+the key file must either exist (for most commands) or will be created (\fBborg init\fP).
+.IP \(bu 2
+you need to give a different path for different repositories.
+.IP \(bu 2
+you need to point to the correct key file matching the repository the command will operate on.
+.UNINDENT
 .TP
 .B TMPDIR
 This is where temporary files are stored (might need a lot of temporary space for some
-operations), see \fI\%tempfile\fP for details.
+operations), see tempfile \%<https://\:docs\:.python\:.org/\:3/\:library/\:tempfile\:.html#\:tempfile\:.gettempdir> for details.
 .UNINDENT
 .TP
 .B Building:
@@ -569,10 +638,6 @@ Adds given OpenSSL header file directory to the default locations (setup.py).
 Adds given prefix directory to the default locations. If a \(aqinclude/lz4.h\(aq is found Borg
 will be linked against the system liblz4 instead of a bundled implementation. (setup.py)
 .TP
-.B BORG_LIBB2_PREFIX
-Adds given prefix directory to the default locations. If a \(aqinclude/blake2.h\(aq is found Borg
-will be linked against the system libb2 instead of a bundled implementation. (setup.py)
-.TP
 .B BORG_LIBZSTD_PREFIX
 Adds given prefix directory to the default locations. If a \(aqinclude/zstd.h\(aq is found Borg
 will be linked against the system libzstd instead of a bundled implementation. (setup.py)
@@ -582,7 +647,7 @@ will be linked against the system libzstd instead of a bundled implementation. (
 Please note:
 .INDENT 0.0
 .IP \(bu 2
-Be very careful when using the "yes" sayers, the warnings with prompt exist for your / your data\(aqs security/safety.
+Be very careful when using the \(dqyes\(dq sayers, the warnings with prompt exist for your / your data\(aqs security/safety.
 .IP \(bu 2
 Also be very careful when putting your passphrase into a script, make sure it has appropriate file permissions (e.g.
 mode 600, root:root).
@@ -612,7 +677,7 @@ At least three directory levels with short names
 Typically, file sizes up to a few hundred MB.
 Large repositories may require large files (>2 GB).
 .IP \(bu 2
-Up to 1000 files per directory (10000 for repositories initialized with Borg 1.0)
+Up to 1000 files per directory.
 .IP \(bu 2
 rename(2) / MoveFile(Ex) should work as specified, i.e. on the same file system
 it should be a move (not a copy) operation, and in case of a directory
@@ -626,16 +691,16 @@ config file), but the code tries to work also if hardlinks are not supported.
 .SS Units
 .sp
 To display quantities, Borg takes care of respecting the
-usual conventions of scale. Disk sizes are displayed in \fI\%decimal\fP, using powers of ten (so
+usual conventions of scale. Disk sizes are displayed in decimal \%<https://\:en\:.wikipedia\:.org/\:wiki/\:Decimal>, using powers of ten (so
-\fBkB\fP means 1000 bytes). For memory usage, \fI\%binary prefixes\fP are used, and are
+\fBkB\fP means 1000 bytes). For memory usage, binary prefixes \%<https://\:en\:.wikipedia\:.org/\:wiki/\:Binary_prefix> are used, and are
-indicated using the \fI\%IEC binary prefixes\fP,
+indicated using the IEC binary prefixes \%<https://\:en\:.wikipedia\:.org/\:wiki/\:IEC_80000-13#\:Prefixes_for_binary_multiples>,
 using powers of two (so \fBKiB\fP means 1024 bytes).
 .SS Date and Time
 .sp
 We format date and time conforming to ISO\-8601, that is: YYYY\-MM\-DD and
 HH:MM:SS (24h clock).
 .sp
-For more information about that, see: \fI\%https://xkcd.com/1179/\fP
+For more information about that, see: \%<https://\:xkcd\:.com/\:1179/>
 .sp
 Unless otherwise noted, we display local date and time.
 Internally, we store and process date and time as UTC.
@@ -682,7 +747,7 @@ 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 \fI\%ssh:\-type\fP repo, the ssh
+When using borg in a client/server way with a \%<ssh:-type> repo, 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.
@@ -727,7 +792,7 @@ 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
 other cases it may be necessary to first enable \fBPermitUserEnvironment yes\fP
-in your \fBsshd_config\fP file, then add \fBenvironment="TMPDIR=/my/big/tmpdir"\fP
+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.
 .TP
 .B Cache files (client only):
@@ -755,7 +820,7 @@ special files:
 .IP \(bu 2
 character and block device files (restored via mknod)
 .IP \(bu 2
-FIFOs ("named pipes")
+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.
@@ -782,9 +847,8 @@ On some platforms additional features are supported:
 .\" Yes/No's are grouped by reason/mechanism/reference.
 .
 .TS
-center;
+box center;
-|l|l|l|l|.
+l|l|l|l.
-_
 T{
 Platform
 T}	T{
@@ -809,7 +873,7 @@ Yes [1]
 T}
 _
 T{
-Mac OS X
+macOS
 T}	T{
 Yes
 T}	T{
@@ -867,7 +931,6 @@ No
 T}	T{
 No
 T}
-_
 .TE
 .sp
 Other Unix\-like operating systems may work as well, but have not been tested at all.
@@ -875,7 +938,7 @@ Other Unix\-like operating systems may work as well, but have not been tested at
 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.
 .IP [1] 5
-Only "nodump", "immutable", "compressed" and "append" are supported.
+Only \(dqnodump\(dq, \(dqimmutable\(dq, \(dqcompressed\(dq and \(dqappend\(dq are supported.
 Feature request #618 for more flags.
 .IP [2] 5
 Feature request #1332
@@ -894,7 +957,7 @@ aka \fIBSD flags\fP\&. The Linux set of flags [1] is portable across platforms.
 The BSDs define additional flags.
 .SH SEE ALSO
 .sp
-\fIborg\-common(1)\fP for common command line options
+\fIborg\-common(1)\fP for common command\-line options
 .sp
 \fIborg\-init(1)\fP,
 \fIborg\-create(1)\fP, \fIborg\-mount(1)\fP, \fIborg\-extract(1)\fP,
@@ -905,19 +968,18 @@ The BSDs define additional flags.
 \fIborg\-compression(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP
 .INDENT 0.0
 .IP \(bu 2
-Main web site \fI\%https://www.borgbackup.org/\fP
+Main web site \%<https://\:www\:.borgbackup\:.org/>
 .IP \(bu 2
-Releases \fI\%https://github.com/borgbackup/borg/releases\fP
+Releases \%<https://\:github\:.com/\:borgbackup/\:borg/\:releases>
 .IP \(bu 2
-Changelog \fI\%https://github.com/borgbackup/borg/blob/master/docs/changes.rst\fP
+Changelog \%<https://\:github\:.com/\:borgbackup/\:borg/\:blob/\:master/\:docs/\:changes\:.rst>
 .IP \(bu 2
-GitHub \fI\%https://github.com/borgbackup/borg\fP
+GitHub \%<https://\:github\:.com/\:borgbackup/\:borg>
 .IP \(bu 2
-Security contact \fI\%https://borgbackup.readthedocs.io/en/latest/support.html#security\-contact\fP
+Security contact \%<https://\:borgbackup\:.readthedocs\:.io/\:en/\:latest/\:support\:.html#\:security-contact>
 .UNINDENT
-.SH AUTHOR
+.SH Author
 The Borg Collective
 
 orphan: 
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man/borgfs.1

@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -27,18 +28,42 @@ 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 "2022-02-19" "" "borg backup tool"
+.TH "borgfs" "1" "2026-03-18" "" "borg backup tool"
-.SH NAME
+.SH Name
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
 .sp
 borgfs [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
 .SH DESCRIPTION
 .sp
-This command mounts an archive as a FUSE filesystem. This can be useful for
+This command mounts a repository or an archive as a FUSE filesystem.
-browsing an archive or restoring individual files. Unless the \fB\-\-foreground\fP
+This can be useful for browsing or restoring individual files.
-option is given the command will run in the background until the filesystem
+.sp
-is \fBumounted\fP\&.
+When restoring, take into account that the current FUSE implementation does
+not support special filesystem flags and ACLs.
+.sp
+When mounting a repository, the top directories will be named like the
+archives and the directory structure below these will be loaded on\-demand from
+the repository when entering these directories, so expect some delay.
+.sp
+Care should be taken, as Borg backs up symlinks as\-is. When an archive
+or repository is mounted, it is possible to “jump” outside the mount point
+by following a symlink. If this happens, files or directories (or versions of them)
+that are not part of the archive or repository may appear to be within the mount point.
+.sp
+Unless the \fB\-\-foreground\fP option is given the command will run in the
+background until the filesystem is \fBunmounted\fP\&.
+.sp
+Performance tips:
+.INDENT 0.0
+.IP \(bu 2
+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.
+.IP \(bu 2
+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
 used in fstab entries:
@@ -59,7 +84,7 @@ 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
+(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
 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,
@@ -69,16 +94,16 @@ manually. Unlike the \fBuid\fP and \fBgid\fP mount options which affect all file
 Additional mount options supported by borg:
 .INDENT 0.0
 .IP \(bu 2
-versions: when used with a repository mount, this gives a merged, versioned
+\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; the layout may change in the future.
 .IP \(bu 2
-allow_damaged_files: by default damaged files (where missing chunks were
+\fBallow_damaged_files\fP: by default damaged files (where missing chunks were
-replaced with runs of zeros by borg check \fB\-\-repair\fP) are not readable and
+replaced with runs of zeros by \fBborg check \-\-repair\fP) are not readable and
 return EIO (I/O error). Set this option to read such files.
 .IP \(bu 2
-ignore_permissions: for security reasons the "default_permissions" mount
+\fBignore_permissions\fP: for security reasons the \fBdefault_permissions\fP mount
-option is internally enforced by borg. "ignore_permissions" can be given to
+option is internally enforced by borg. \fBignore_permissions\fP can be given to
-not enforce "default_permissions".
+not enforce \fBdefault_permissions\fP\&.
 .UNINDENT
 .sp
 The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users
@@ -90,8 +115,15 @@ When the daemonized process receives a signal or crashes, it does not unmount.
 Unmounting in these cases could cause an active rsync or similar process
 to unintentionally delete data.
 .sp
-When running in the foreground ^C/SIGINT unmounts cleanly, but other
+When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
-signals or crashes do not.
+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.
@@ -107,7 +139,7 @@ where to mount filesystem
 .B PATH
 paths to extract; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-V\fP,\fB  \-\-version
@@ -132,13 +164,13 @@ use numeric user and group identifiers from archive(s)
 .INDENT 0.0
 .TP
 .BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX
-only consider archive names starting with this prefix.
+only consider archive names starting with this prefix. (deprecated)
 .TP
 .BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB
-only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
+only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see \(dqborg help patterns\(dq.
 .TP
 .BI \-\-sort\-by \ KEYS
-Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp
 .TP
 .BI \-\-first \ N
 consider first N archives after other filters were applied
@@ -146,7 +178,7 @@ consider first N archives after other filters were applied
 .BI \-\-last \ N
 consider last N archives after other filters were applied
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
@@ -167,7 +199,6 @@ Remove the specified number of leading path elements. Paths with fewer elements
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP
-.SH AUTHOR
+.SH Author
 The Borg Collective
-.\" Generated by docutils manpage writer.
+.\" End of generated man page.
-.

docs/man_intro.rst

@@ -40,7 +40,7 @@ NOTES
 SEE ALSO
 --------
 
-`borg-common(1)` for common command line options
+`borg-common(1)` for common command-line options
 
 `borg-init(1)`,
 `borg-create(1)`, `borg-mount(1)`, `borg-extract(1)`,

docs/misc/asciinema/README

@@ -0,0 +1,4 @@
+Do NOT run the examples without isolation (e.g Vagrant) or
+this code may make undesirable changes to your host.
+
+Running `vagrant up` in this directory will update the screencasts.

docs/misc/asciinema/Vagrantfile

@@ -0,0 +1,75 @@
+Vagrant.configure("2") do |config|
+  config.vm.box = "debian/bullseye64"
+  config.vm.provision "install dependencies", type: "shell", inline: <<-SHELL
+    apt-get update
+    apt-get install -y wget expect gpg asciinema ssh adduser fuse
+    mkdir -p /wallpaper
+    wget \
+        --user-agent="borgbackup demo screencast" \
+        --input-file=/vagrant/sample-wallpapers.txt \
+        --directory-prefix=/wallpaper
+  SHELL
+  config.vm.provision "record install", type: "shell", inline: <<-SHELL
+  	gpg --recv-keys "6D5B EF9A DD20 7580 5747 B70F 9F88 FB52 FAF7 B393"
+    asciinema rec -c 'expect /vagrant/install.tcl' --overwrite /vagrant/install.json < /dev/null
+  SHELL
+  config.vm.provision "record basic usage", type: "shell", inline: <<-SHELL
+    # `rm` below allows quick re-exec via:
+    # vagrant vagrant provision --provision-with "record basic usage"
+    # this is useful when testing changes
+    rm -r /media/backup/borgdemo || true
+    rm -r ~/.ssh/ || true
+    rm -r Wallpaper || true
+    deluser --remove-home borgdemo || true
+
+    # In case we have skipped "record install"
+    if [ ! -e /usr/local/bin/borg ] ; then
+      wget https://github.com/borgbackup/borg/releases/download/1.2.1/borg-linux64
+      install --owner root --group root --mode 755 borg-linux64 /usr/local/bin/borg
+    fi
+
+    mkdir -p /media/backup/borgdemo
+    mkdir Wallpaper
+    cp -r /wallpaper Wallpaper/bigcollection
+    cp /wallpaper/Trapper_cabin.jpg Wallpaper/deer.jpg
+
+    adduser --disabled-password borgdemo
+    echo '127.0.0.1 remoteserver.example' >> /etc/hosts
+    ssh-keygen -f ~/.ssh/id_rsa -N ''
+    ssh-keyscan remoteserver.example > ~/.ssh/known_hosts
+    runuser -u borgdemo mkdir ~borgdemo/.ssh
+    runuser -u borgdemo tee ~borgdemo/.ssh/authorized_keys < ~/.ssh/id_rsa.pub
+
+    asciinema rec -c 'expect /vagrant/basic.tcl' --overwrite /vagrant/basic.json < /dev/null
+  SHELL
+  config.vm.provision "record advanced usage", type: "shell", inline: <<-SHELL
+    rm -r /media/backup/borgdemo || true
+    rm -r Wallpaper || true
+
+    # In case we have skipped "record install"
+    if [ ! -e /usr/local/bin/borg ] ; then
+      wget https://github.com/borgbackup/borg/releases/download/1.2.1/borg-linux64
+      install --owner root --group root --mode 755 borg-linux64 /usr/local/bin/borg
+    fi
+
+    mkdir -p /media/backup/borgdemo
+    mkdir Wallpaper
+    cp -r /wallpaper Wallpaper/bigcollection
+    cp /wallpaper/Trapper_cabin.jpg Wallpaper/deer.jpg
+    mkdir -p ~/Downloads/big
+    dd if=/dev/zero of=loopbackfile.img bs=100M count=4
+    losetup /dev/loop0 loopbackfile.img
+
+	# Make it look as if the adv. usage screencast was recorded after basic usage
+    export BORG_PASSPHRASE='1234'
+    borg init --encryption=repokey /media/backup/borgdemo
+    borg create --compression lz4 /media/backup/borgdemo::backup1 Wallpaper
+    echo "new nice file" > Wallpaper/newfile.txt
+    borg create --compression lz4 /media/backup/borgdemo::backup2 Wallpaper
+    mv Wallpaper/bigcollection Wallpaper/bigcollection_NEW
+    borg create --compression lz4 /media/backup/borgdemo::backup3 Wallpaper
+    unset BORG_PASSPHRASE
+
+    asciinema rec -c 'expect /vagrant/advanced.tcl' --overwrite /vagrant/advanced.json < /dev/null
+  SHELL
+end

docs/misc/asciinema/advanced.tcl

@@ -1,5 +1,11 @@
+# Configuration for send -h
+# Tries to emulate a human typing
+# Tweak this if typing is too fast or too slow
+set send_human {.05 .1 1 .01 .2}
+
+set script {
 # For the pro users, here are some advanced features of borg, so you can impress your friends. ;)
-# Note: This screencast was made with borg version 1.1.0 – older or newer borg versions may behave differently.
+# Note: This screencast was made with __BORG_VERSION__ – older or newer borg versions may behave differently.
 
 # First of all, we can use several environment variables for borg.
 # E.g. we do not want to type in our repo path and password again and again…
@@ -27,13 +33,12 @@ borg info :: --last 1
 
 # So let's rename our last archive:
 borg rename ::specialbackup backup-block-device
-<up>
+
 borg info :: --last 1
 
 # A very important step if you choose keyfile mode (where the keyfile is only saved locally) is to export your keyfile and possibly print it, etc.
-borg key export :: --qr-code file.html # this creates a nice HTML, but when you want something simpler…
+borg key export --qr-html :: file.html  # this creates a nice HTML, but when you want something simpler…
-< remove comment >
+borg key export --paper ::  # this is a "manual input"-only backup (but it is also included in the --qr-code option)
-< let there: borg check > --paper # this is a "manual input"-only backup (but it is also included in the --qr-code option)
 
 ## MAINTENANCE ##
 # Sometimes backups get broken or we want a regular "checkup" that everything is okay…
@@ -63,3 +68,18 @@ ls -la /tmp/mount
 borg umount /tmp/mount
 
 # That's it, but of course there is more to explore, so have a look at the docs.
+}
+
+set script [string trim $script]
+set script [string map [list __BORG_VERSION__ [exec borg -V]] $script]
+set script [split $script \n]
+
+set ::env(PS1) "$ "
+set stty_init -echo
+spawn -noecho /bin/sh
+foreach line $script {
+	expect "$ "
+	send_user -h $line\n
+	send $line\n
+}
+expect "$ "

docs/misc/asciinema/basic.tcl

@@ -1,5 +1,11 @@
+# Configuration for send -h
+# Tries to emulate a human typing
+# Tweak this if typing is too fast or too slow
+set send_human {.05 .1 1 .01 .2}
+
+set script {
 # Here you'll see some basic commands to start working with borg.
-# Note: This teaser screencast was made with borg version 1.1.0 – older or newer borg versions may behave differently.
+# Note: This teaser screencast was made with __BORG_VERSION__ – older or newer borg versions may behave differently.
 # But let's start.
 
 # First of all, you can always get help:
@@ -16,7 +22,6 @@ borg create --stats --progress --compression lz4 /media/backup/borgdemo::backup1
 # So let's add a new file…
 echo "new nice file" > Wallpaper/newfile.txt
 
-<up>
 borg create --stats --progress --compression lz4 /media/backup/borgdemo::backup2 Wallpaper
 
 # Wow, this was a lot faster!
@@ -24,7 +29,7 @@ borg create --stats --progress --compression lz4 /media/backup/borgdemo::backup2
 # Borg recognized that most files did not change and deduplicated them.
 
 # But what happens, when we move a dir and create a new backup?
-mv …
+mv Wallpaper/bigcollection Wallpaper/bigcollection_NEW
 
 borg create --stats --progress --compression lz4 /media/backup/borgdemo::backup3 Wallpaper
 
@@ -40,7 +45,8 @@ borg list /media/backup/borgdemo::backup3 | grep 'deer.jpg'
 
 # Oh, we found our picture. Now extract it…
 mv Wallpaper Wallpaper.orig
-borg extract /media/backup/borgdemo::backup3 <copy>
+borg extract /media/backup/borgdemo::backup3 Wallpaper/deer.jpg
+
 
 # And check that it's the same:
 diff -s Wallpaper/deer.jpg Wallpaper.orig/deer.jpg
@@ -51,3 +57,33 @@ borg init --encryption=repokey borgdemo@remoteserver.example:./demo
 # Easy, isn't it? That's all you need to know for basic usage.
 # If you want to see more, have a look at the screencast showing the "advanced usage".
 # In any case, enjoy using borg!
+}
+
+set script [string trim $script]
+set script [string map [list __BORG_VERSION__ [exec borg -V]] $script]
+set script [split $script \n]
+
+foreach line $script {
+  send_user "$ "
+  send_user -h $line\n
+  spawn -noecho /bin/sh -c $line
+  expect {
+    "Enter new passphrase: " {
+      send -h "correct horse battery staple\n"
+      exp_continue
+    }
+    "Enter same passphrase again: " {
+      send -h "correct horse battery staple\n"
+      exp_continue
+    }
+    "Enter passphrase for key /media/backup/borgdemo: " {
+      send -h "correct horse battery staple\n"
+      exp_continue
+    }
+    -ex {Do you want your passphrase to be displayed for verification? [yN]: } {
+      send \n
+      exp_continue
+    }
+    eof
+  }
+}

docs/misc/asciinema/install.tcl

@@ -1,9 +1,15 @@
+# Configuration for send -h
+# Tries to emulate a human typing
+# Tweak this if typing is too fast or too slow
+set send_human {.05 .1 1 .01 .2}
+
+set script [string trim {
 # This asciinema will show you the installation of borg as a standalone binary. Usually you only need this if you want to have an up-to-date version of borg or no package is available for your distro/OS.
 
 # First, we need to download the version, we'd like to install…
-wget -q --show-progress https://github.com/borgbackup/borg/releases/download/1.1.0b6/borg-linux64
+wget -q --show-progress https://github.com/borgbackup/borg/releases/download/1.2.1/borg-linux64
 # and do not forget the GPG signature…!
-wget -q --show-progress https://github.com/borgbackup/borg/releases/download/1.1.0b6/borg-linux64.asc
+wget -q --show-progress https://github.com/borgbackup/borg/releases/download/1.2.1/borg-linux64.asc
 
 # In this case, we have already imported the public key of a borg developer. So we only need to verify it:
 gpg --verify borg-linux64.asc
@@ -19,3 +25,14 @@ sudo chmod 755 /usr/local/bin/borg
 borg -V
 
 # That's it! Check out the other screencasts to see how to actually use borgbackup.
+}]
+
+# wget may be slow
+set timeout -1
+
+foreach line [split $script \n] {
+	send_user "$ "
+	send_user -h $line\n
+	spawn -noecho /bin/sh -c $line
+	expect eof
+}

docs/misc/asciinema/sample-wallpapers.txt

@@ -0,0 +1,30 @@
+https://upload.wikimedia.org/wikipedia/commons/2/22/Pseudo_kleinian_001_OpenCL_45154214_8K.jpg
+https://upload.wikimedia.org/wikipedia/commons/d/da/Mengerschwamm_Iteration_5_x_Mandelbulb_OpenCL_528814521414_8K.jpg
+https://upload.wikimedia.org/wikipedia/commons/e/eb/Blixos_logon_screen.jpg
+https://upload.wikimedia.org/wikipedia/commons/9/90/Great_smokey_mountains_national_park_with_woman_sitting_under_tree_in_foreground.jpg
+https://upload.wikimedia.org/wikipedia/commons/d/d2/Mengerschwamm_x_Generalized_Fold_Box_OpenCL_18915424_8K.jpg
+https://upload.wikimedia.org/wikipedia/commons/3/3d/Red_interesting_background.jpg
+https://upload.wikimedia.org/wikipedia/commons/4/43/KIFS_OpenCL_54815_5K.jpg
+https://upload.wikimedia.org/wikipedia/commons/a/a1/ProjectStealth.png
+https://upload.wikimedia.org/wikipedia/commons/8/8d/KIFS_OpenCL_5434735835_5K.jpg
+https://upload.wikimedia.org/wikipedia/commons/d/db/Harvett_Fox_-_Wallpaper_%2816x9_ratio%2C_without_character_logo%2C_transparent_variant%29_%28vector_version%29.svg
+https://upload.wikimedia.org/wikipedia/commons/7/7f/Generalized_Fold_Box_OpenCL_4258952414_8K.jpg
+https://upload.wikimedia.org/wikipedia/commons/5/58/Mandelbox_Vary_Scale_4D_OpenCL_9648145412_8K.jpg
+https://upload.wikimedia.org/wikipedia/commons/6/62/Trapper_cabin.jpg
+https://upload.wikimedia.org/wikipedia/commons/f/fd/Openarch.png
+https://upload.wikimedia.org/wikipedia/commons/a/a5/Mandelbox_-_Variable_8K_6595424.jpg
+https://upload.wikimedia.org/wikipedia/commons/d/d6/Mengerschwamm_Iteration_6_x_Generalized_Fold_Box_OpenCL_14048152404910_8K.jpg
+https://upload.wikimedia.org/wikipedia/commons/c/cf/Sierp_Oktaeder_x_Menger_4D_OpenCL_51241841541_8K.jpg
+https://upload.wikimedia.org/wikipedia/commons/5/59/Airbus_Wing_01798_changed.jpg
+https://upload.wikimedia.org/wikipedia/commons/8/8a/Holytrinfruitlandpark1b.jpg
+https://upload.wikimedia.org/wikipedia/commons/5/5c/Abox_-_Mod_12_OpenCL_45184521485_5K.jpg
+https://upload.wikimedia.org/wikipedia/commons/d/d2/Menger_4D_x_Quaternion_OpenCL_644289452_8K.jpg
+https://upload.wikimedia.org/wikipedia/commons/3/3e/Gabrielsond.jpg
+https://upload.wikimedia.org/wikipedia/commons/8/80/Mix_Pinski_4D_x_Mengerschwamm_OpenCL_461481542_8K.jpg
+https://upload.wikimedia.org/wikipedia/commons/8/84/Belinda_Vixen_-_Wallpaper_%28without_character_wordmark_and_hair_variant%29_%2816x9_ratio%29.jpg
+https://upload.wikimedia.org/wikipedia/commons/0/00/Sierp_Oktaeder_Iteration_7_x_Menger_4D_OpenCL_2154188450481_8K.jpg
+https://upload.wikimedia.org/wikipedia/commons/2/24/Abox_4D_OpenCL_545185481_8K.jpg
+https://upload.wikimedia.org/wikipedia/commons/0/08/Sierpinski_4D_OpenCL_485274854_5K.jpg
+https://upload.wikimedia.org/wikipedia/commons/0/09/Vereinigung_Sierpinski_4D_und_Mengerschwamm_OpenCl_6184524.jpg
+https://upload.wikimedia.org/wikipedia/commons/a/ae/Mengerschwamm_OpenCL_955141845_8K.jpg
+https://upload.wikimedia.org/wikipedia/commons/6/64/Free_high-resolution_pictures_you_can_use_on_your_personal_and_commercial_projects._%2814168975789%29.jpg

docs/misc/create_chunker-params.txt

@@ -18,7 +18,7 @@ determined by the windows contents rather than the min/max. chunk size).
 Default: 21 (statistically, chunks will be about 2^21 == 2MiB in size)
 
 HASH_WINDOW_SIZE: the size of the window used for the rolling hash computation.
-Default: 4095B
+Must be an odd number. Default: 4095B
 
 
 Trying it out
@@ -114,4 +114,3 @@ $ ls -l /extra/repo-xl/index*
 
 $ du -sk /extra/repo-xl/
 14253464    /extra/repo-xl/
-

docs/misc/prune-example.txt

@@ -100,3 +100,27 @@ example simple. They all work in basically the same way.
 
 The weekly rule is easy to understand roughly, but hard to understand in all
 details. If interested, read "ISO 8601:2000 standard week-based year".
+
+The 13weekly and 3monthly rules are two different strategies for keeping one
+every quarter of a year. There are `multiple ways` to define a quarter-year;
+borg prune recognizes two:
+
+* --keep-13weekly keeps one backup every 13 weeks using ISO 8601:2000's
+  definition of the week-based year. January 4th is always included in the
+  first week of a year, and January 1st to 3rd may be in week 52 or 53 of the
+  previous year. Week 53 is also in the fourth quarter of the year.
+* --keep-3monthly keeps one backup every 3 months. January 1st to
+  March 31, April 1st to June 30th, July 1st to September 30th, and October 1st
+  to December 31st form the quarters.
+
+If the subtleties of the definition of a quarter year don't matter to you, a
+short summary of behavior is:
+
+* --keep-13weekly favors keeping backups at the beginning of Jan, Apr, July,
+  and Oct.
+* --keep-3monthly favors keeping backups at the end of Dec, Mar, Jun, and Sept.
+* Both strategies will have some overlap in which backups are kept.
+* The differences are negligible unless backups considered for deletion were
+  created weekly or more frequently.
+
+.. _multiple ways: https://en.wikipedia.org/wiki/Calendar_year#Quarter_year

docs/quickstart.rst

@@ -8,7 +8,7 @@ Quick Start
 This chapter will get you started with Borg and covers
 various use cases.
 
-A step by step example
+A step-by-step example
 ----------------------
 
 .. include:: quickstart_example.rst.inc
@@ -20,12 +20,14 @@ A *Borg archive* is the result of a single backup (``borg create``). An archive
 stores a snapshot of the data of the files "inside" it. One can later extract or
 mount an archive to restore from a backup.
 
-*Repositories* are filesystem directories acting as self-contained stores of archives.
+*Repositories* are file system directories acting as self-contained stores of archives.
-Repositories can be accessed locally via path or remotely via ssh. Under the hood,
+Repositories can be accessed locally via path or remotely via SSH. Under the hood,
 repositories contain data blocks and a manifest tracking which blocks are in each
 archive. If some data hasn't changed from one backup to another, Borg can simply
 reference an already uploaded data chunk (deduplication).
 
+.. _about_free_space:
+
 Important note about free space
 -------------------------------
 
@@ -35,7 +37,7 @@ a good amount of free space on the filesystem that has your backup repository
 repositories. See also :ref:`cache-memory-usage`.
 
 Borg doesn't use space reserved for root on repository disks (even when run as root),
-on file systems which do not support this mechanism (e.g. XFS) we recommend to reserve
+on file systems which do not support this mechanism (e.g., XFS) we recommend reserving
 some space in Borg itself just to be safe by adjusting the ``additional_free_space``
 setting (a good starting point is ``2G``)::
 
@@ -47,7 +49,7 @@ by deleting/pruning archives. This mechanism is not bullet-proof in some
 circumstances [1]_.
 
 If you *really* run out of disk space, it can be hard or impossible to free space,
-because Borg needs free space to operate - even to delete backup
+because Borg needs free space to operate — even to delete backup
 archives.
 
 You can use some monitoring process or just include the free space information
@@ -56,38 +58,38 @@ in your backup log files (you check them regularly anyway, right?).
 Also helpful:
 
 - create a big file as a "space reserve", that you can delete to free space
-- if you use LVM: use a LV + a filesystem that you can resize later and have
+- if you use LVM: use an LV + a file system that you can resize later and have
   some unallocated PEs you can add to the LV.
 - consider using quotas
 - use `prune` and `compact` regularly
 
-.. [1] This failsafe can fail in these circumstances:
+.. [1] This fail-safe can fail in these circumstances:
 
-    - The underlying file system doesn't support statvfs(2), or returns incorrect
+    - The underlying file system does not support statvfs(2), or returns incorrect
-      data, or the repository doesn't reside on a single file system
+      data, or the repository does not reside on a single file system
     - Other tasks fill the disk simultaneously
     - Hard quotas (which may not be reflected in statvfs(2))
 
 Important note about permissions
 --------------------------------
 
-To avoid permissions issues (in your borg repository or borg cache), **always
+To avoid permissions issues (in your Borg repository or Borg cache), **always
 access the repository using the same user account**.
 
-If you want to backup files of other users or the operating system, running
+If you want to back up files of other users or the operating system, running
-borg as root likely will be required (otherwise you'ld get `Permission denied`
+Borg as root likely will be required (otherwise you'd get `Permission denied`
 errors).
-If you only back up your own files, you neither need nor want to run borg as
+If you only back up your own files, you neither need nor want to run Borg as
 root, just run it as your normal user.
 
-For a local repository just always use the same user to invoke borg.
+For a local repository just always use the same user to invoke Borg.
 
 For a remote repository: always use e.g. borg@remote_host. You can use this
-from different local users, the remote user running borg and accessing the
+from different local users; the remote user running Borg and accessing the
 repo will always be `borg`.
 
 If you need to access a local repository from different users, you can use the
-same method by using ssh to borg@localhost.
+same method by using SSH to borg@localhost.
 
 Important note about files changing during the backup process
 -------------------------------------------------------------
@@ -182,31 +184,31 @@ backed up and that the ``prune`` command is keeping and deleting the correct bac
         --show-rc                       \
         --compression lz4               \
         --exclude-caches                \
-        --exclude '/home/*/.cache/*'    \
+        --exclude 'home/*/.cache/*'     \
-        --exclude '/var/tmp/*'          \
+        --exclude 'var/tmp/*'           \
                                         \
         ::'{hostname}-{now}'            \
         /etc                            \
         /home                           \
         /root                           \
-        /var                            \
+        /var
 
     backup_exit=$?
 
     info "Pruning repository"
 
     # Use the `prune` subcommand to maintain 7 daily, 4 weekly and 6 monthly
-    # archives of THIS machine. The '{hostname}-' prefix is very important to
+    # archives of THIS machine. The '{hostname}-*' matching is very important to
     # limit prune's operation to this machine's archives and not apply to
     # other machines' archives also:
 
     borg prune                          \
         --list                          \
-        --prefix '{hostname}-'          \
+        --glob-archives '{hostname}-*'  \
         --show-rc                       \
         --keep-daily    7               \
         --keep-weekly   4               \
-        --keep-monthly  6               \
+        --keep-monthly  6
 
     prune_exit=$?
 
@@ -309,36 +311,30 @@ Backup compression
 ------------------
 
 The default is lz4 (very fast, but low compression ratio), but other methods are
-supported for different situations.
+supported for different situations. Compression not only helps you save disk space,
+but will especially speed up remote backups since less data needs to be transferred.
 
-You can use zstd for a wide range from high speed (and relatively low
+zstd is a modern compression algorithm which can be parametrized to anything between
-compression) using N=1 to high compression (and lower speed) using N=22.
+N=1 for highest speed (and relatively low compression) to N=22 for highest compression
-
+(and lower speed)::
-zstd is a modern compression algorithm and might be preferable over zlib and
-lzma, except if you need compatibility to older borg versions (< 1.1.4) that
-did not yet offer zstd.::
 
     $ borg create --compression zstd,N /path/to/repo::arch ~
 
-Other options are:
+If you have a fast repo storage and you want minimum CPU usage you can disable
-
+compression::
-If you have a fast repo storage and you want minimum CPU usage, no compression::
 
     $ borg create --compression none /path/to/repo::arch ~
 
-If you have a less fast repo storage and you want a bit more compression (N=0..9,
+You can also use zlib and lzma instead of zstd, although zstd usually provides the
-0 means no compression, 9 means high compression):
+the best compression for a given resource consumption. You may want to use these
+algorithms if you need compatibility to older borg versions (< 1.1.4) that
+did not yet offer zstd. Please see :ref:`borg_compression` for all options.
 
-::
+An interesting alternative is ``auto``, which first checks with lz4 whether a chunk is
+compressible (that check is very fast), and only if it is, compresses it with the
+specified algorithm::
 
-    $ borg create --compression zlib,N /path/to/repo::arch ~
+    $ borg create --compression auto,zstd,7 /path/to/repo::arch ~
-
-If you have a very slow repo storage and you want high compression (N=0..9, 0 means
-low compression, 9 means high compression):
-
-::
-
-    $ borg create --compression lzma,N /path/to/repo::arch ~
 
 You'll need to experiment a bit to find the best compression for your use case.
 Keep an eye on CPU load and throughput.
@@ -374,18 +370,8 @@ For automated backups the passphrase can be specified using the
 .. warning:: The repository data is totally inaccessible without the key
     and the key passphrase.
 
-    Make a backup copy of the key file (``keyfile`` mode) or repo config
+    In any case, make a backup of the borg key, see :ref:`borg_key_export` for
-    file (``repokey`` mode) and keep it at a safe place, so you still have
+    more details.
-    the key in case it gets corrupted or lost. Also keep your passphrase
-    at a safe place. You can make backups using :ref:`borg_key_export`
-    subcommand.
-
-    If you want to print a backup of your key to paper use the ``--paper``
-    option of this command and print the result, or print this `template`_
-    if you need a version with QR-Code.
-
-    A backup inside of the backup that is encrypted with that key/passphrase
-    won't help you with that, of course.
 
     In case you lose your repository and the security information, but have an
     older copy of it to restore from, don't use that later for creating new
@@ -393,8 +379,6 @@ For automated backups the passphrase can be specified using the
     values). It is better to initialize a new Borg repository. See also:
     :ref:`faq_corrupt_repo`
 
-.. _template: paperkey.html
-
 .. _remote_repos:
 
 Remote repositories
@@ -406,7 +390,8 @@ is installed on the remote host, in which case the following syntax is used::
 
   $ borg init user@hostname:/path/to/repo
 
-Note: please see the usage chapter for a full documentation of repo URLs.
+Note: Please see the usage chapter for a full documentation of repo URLs. Also
+see :ref:`ssh_configuration` for recommended settings to avoid disconnects and hangs.
 
 Remote operations over SSH can be automated with SSH keys. You can restrict the
 use of the SSH keypair by prepending a forced command to the SSH public key in

docs/support.rst

@@ -15,7 +15,7 @@ Security
 --------
 
 In case you discover a security issue, please use this contact for reporting it
-privately and please, if possible, use encrypted E-Mail:
+privately and please, if possible, use encrypted email:
 
 Thomas Waldmann <tw@waldmann-edv.de>
 
@@ -28,7 +28,7 @@ Verifying signed releases
 -------------------------
 
 `Releases <https://github.com/borgbackup/borg/releases>`_ are signed with the
-same GPG key and a .asc file is provided for each binary.
+same GPG key and an .asc file is provided for each binary.
 
 To verify a signature, the public key needs to be known to GPG. It can be
 imported into the local keystore from a keyserver with the fingerprint::
@@ -41,7 +41,7 @@ If GPG successfully imported the key, the output should include (among other thi
       gpg: Total number processed: 1
       ...
 
-To verify for example the signature of the borg-linux64 binary::
+To verify, for example, the signature of the borg-linux64 binary::
 
       gpg --verify borg-linux64.asc
 

docs/usage.rst

@@ -22,7 +22,7 @@ Usage
            window.location.pathname = replaced;
        }
    }
-   // Fixup anchored links from when usage.html contained all the commands
+   // Fix up anchored links from when usage.html contained all the commands
    else if(hash.startsWith("borg-key") || hash == "borg-change-passphrase") {
       window.location.hash = "";
       window.location.pathname = window.location.pathname.replace("usage.html", "usage/key.html");
@@ -47,6 +47,7 @@ Usage
    usage/prune
    usage/compact
    usage/info
+   usage/version
    usage/mount
    usage/key
    usage/upgrade

docs/usage/benchmark_crud.rst.inc

@@ -17,7 +17,7 @@ borg benchmark crud
     +-------------------------------------------------------+----------------+----------------------------------------------+
     |                                                       | ``REPOSITORY`` | repository to use for benchmark (must exist) |
     +-------------------------------------------------------+----------------+----------------------------------------------+
-    |                                                       | ``PATH``       | path were to create benchmark input data     |
+    |                                                       | ``PATH``       | path where to create benchmark input data    |
     +-------------------------------------------------------+----------------+----------------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                        |
     |                                                                                                                       |
@@ -37,7 +37,7 @@ borg benchmark crud
     REPOSITORY
         repository to use for benchmark (must exist)
     PATH
-        path were to create benchmark input data
+        path where to create benchmark input data
 
 
     :ref:`common_options`
@@ -48,7 +48,7 @@ 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.
 
@@ -64,17 +64,17 @@ thus the measurement results do not necessarily reflect performance with real da
 Also, due to the kind of content used, no compression is used in these benchmarks.
 
 C- == borg create (1st archive creation, no compression, do not use files cache)
-      C-Z- == all-zero files. full dedup, this is primarily measuring reader/chunker/hasher.
+      C-Z- == all-zero files. full deduplication; this primarily measures reader/chunker/hasher.
-      C-R- == random files. no dedup, measuring throughput through all processing stages.
+      C-R- == random files. no deduplication, measuring throughput through all processing stages.
 
 R- == borg extract (extract archive, dry-run, do everything, but do not write files to disk)
-      R-Z- == all zero files. Measuring heavily duplicated files.
+      R-Z- == all-zero files. Measuring heavily duplicated files.
       R-R- == random files. No duplication here, measuring throughput through all processing
       stages, except writing to disk.
 
 U- == borg create (2nd archive creation of unchanged input files, measure files cache speed)
       The throughput value is kind of virtual here, it does not actually read the file.
-      U-Z- == needs to check the 2 all-zero chunks' existence in the repo.
+      U-Z- == needs to check the two all-zero chunks' existence in the repo.
       U-R- == needs to check existence of a lot of different chunks in the repo.
 
 D- == borg delete archive (delete last remaining archive, measure deletion + compaction)
@@ -82,4 +82,4 @@ D- == borg delete archive (delete last remaining archive, measure deletion + com
       D-R- == many chunks to delete / many segments to compact/remove.
 
 Please note that there might be quite some variance in these measurements.
-Try multiple measurements and having a otherwise idle machine (and network, if you use it).
+Try multiple measurements and have an otherwise idle machine (and network, if you use it).

docs/usage/break-lock.rst.inc

@@ -43,5 +43,5 @@ Description
 ~~~~~~~~~~~
 
 This command breaks the repository and cache locks.
-Please use carefully and only while no borg process (on any machine) is
+Please use with care and only when no borg process (on any machine) is
-trying to access the Cache or the Repository.
+trying to access the cache or the repository.