build_man

include unistd.h in _chunker.c

.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 = *

.github/workflows/ci.yml

@@ -4,7 +4,7 @@ name: CI
 
 on:
   push:
-    branches: [ master ]
+    branches: [ 1.2-maint ]
     paths:
     - '**.py'
     - '**.pyx'
@@ -16,7 +16,7 @@ on:
     - 'requirements.d/*'
     - '!docs/**'
   pull_request:
-    branches: [ master ]
+    branches: [ 1.2-maint ]
     paths:
     - '**.py'
     - '**.pyx'
@@ -31,13 +31,13 @@ on:
 jobs:
   lint:
 
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
     timeout-minutes: 10
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v4
       with:
         python-version: 3.8
     - name: Lint with flake8
@@ -49,6 +49,7 @@ jobs:
 
     needs: lint
     strategy:
+      fail-fast: false
       matrix:
         include:
             - os: ubuntu-20.04
@@ -60,29 +61,35 @@ jobs:
             - os: ubuntu-20.04
               python-version: '3.10'
               toxenv: py310-fuse3
-            - os: macos-10.15  # macos-latest is macos 11.6.2 and hanging at test_fuse, #6099
+            - os: ubuntu-20.04
+              python-version: '3.11'
+              toxenv: py311-fuse2
+            - os: ubuntu-22.04
+              python-version: '3.12'
+              toxenv: py312-fuse3
+            - os: macos-12
               python-version: '3.8'
-              toxenv: py38-fuse2
+              toxenv: py38-none  # note: no fuse testing, due to #6099, see also #6196.
 
     env:
       # Configure pkg-config to use OpenSSL from Homebrew
-      PKG_CONFIG_PATH: /usr/local/opt/openssl@1.1/lib/pkgconfig
+      PKG_CONFIG_PATH: "/usr/local/opt/openssl@1.1/lib/pkgconfig:$PKG_CONFIG_PATH"
       TOXENV: ${{ matrix.toxenv }}
 
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 40
+    timeout-minutes: 90
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         # just fetching 1 commit is not enough for setuptools-scm, so we fetch all
         fetch-depth: 0
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
     - name: Cache pip
-      uses: actions/cache@v2
+      uses: actions/cache@v3
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip-${{ hashFiles('requirements.d/development.txt') }}
@@ -107,17 +114,24 @@ jobs:
         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
+      env:
+        # we already have that in the global env, but something is broken and overwrites that.
+        # so, set it here, again.
+        PKG_CONFIG_PATH: "/usr/local/opt/openssl@1.1/lib/pkgconfig:$PKG_CONFIG_PATH"
       run: |
         # pip install -e .
         python setup.py -v develop
     - name: run pytest via tox
+      env:
+        # we already have that in the global env, but something is broken and overwrites that.
+        # so, set it here, again.
+        PKG_CONFIG_PATH: "/usr/local/opt/openssl@1.1/lib/pkgconfig:$PKG_CONFIG_PATH"
       run: |
         # do not use fakeroot, but run as root. avoids the dreaded EISDIR sporadic failures. see #2482.
         #sudo -E bash -c "tox -e py"

.github/workflows/codeql-analysis.yml

@@ -4,17 +4,17 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ master ]
+    branches: [ 1.2-maint ]
   pull_request:
     # The branches below must be a subset of the branches above
-    branches: [ master ]
+    branches: [ 1.2-maint ]
   schedule:
     - cron: '39 2 * * 5'
 
 jobs:
   analyze:
     name: Analyze
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
     permissions:
       actions: read
       contents: read
@@ -29,38 +29,41 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       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@v4
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
       with:
-        languages: ${{ matrix.language }}
+        python-version: 3.8
-        # 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@v3
       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 -e .
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      uses: github/codeql-action/analyze@v2

.github/workflows/windows.yml

@@ -0,0 +1,27 @@
+name: Windows CI
+on: [push, pull_request]
+
+jobs:
+  msys2-ucrt64:
+    runs-on: windows-latest
+    defaults:
+      run:
+        shell: msys2 {0}
+    steps:
+      - uses: actions/checkout@v3
+        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

.pre-commit-config.yaml

@@ -0,0 +1,6 @@
+repos:
+-   repo: https://github.com/pycqa/flake8
+    rev: 6.0.0
+    hooks:
+    -   id: flake8
+        files: '(src|scripts|conftest.py)'

.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

LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) 2015-2022 The Borg Collective (see AUTHORS file)
+Copyright (C) 2015-2023 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
 # setuptools_scm - it includes all git-committed files.
 # 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

@@ -171,11 +171,7 @@ 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

SECURITY.md

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

Vagrantfile

@@ -3,8 +3,8 @@
 
 # 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)
@@ -42,9 +42,11 @@ def packages_freebsd
     pkg install -y fusefs-libs3 || true
     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 python38 py38-sqlite3
     # make sure there is a python3 command
     ln -sf /usr/local/bin/python3.8 /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 +54,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
@@ -68,9 +70,11 @@ def packages_openbsd
   return <<-EOF
     pkg_add bash
     chsh -s bash vagrant
+    pkg_add xxhash
     pkg_add lz4
     pkg_add zstd
     pkg_add git  # no fakeroot
+    pkg_add openssl%1.1
     pkg_add py3-pip
     pkg_add py3-virtualenv
   EOF
@@ -78,8 +82,7 @@ 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
@@ -91,15 +94,14 @@ def packages_netbsd
     # 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
-    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.
     pkg_add python39 py39-sqlite3 py39-pip py39-virtualenv py39-expat
+    pkg_add py310-sqlite3 py310-pip py310-virtualenv py310-expat
     ln -s /usr/pkg/bin/python3.9 /usr/pkg/bin/python
     ln -s /usr/pkg/bin/python3.9 /usr/pkg/bin/python3
     ln -s /usr/pkg/bin/pip3.9 /usr/pkg/bin/pip
     ln -s /usr/pkg/bin/pip3.9 /usr/pkg/bin/pip3
     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
 
@@ -113,7 +115,7 @@ def packages_darwin
     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 pkg-config readline openssl@1.1 zstd lz4 xz
     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
@@ -156,9 +158,10 @@ end
 def install_pythons(boxname)
   return <<-EOF
     . ~/.bash_profile
-    pyenv install 3.10.0  # tests, version supporting openssl 1.1
+    pyenv install 3.12.0  # tests, version supporting openssl 1.1
-    pyenv install 3.9.10  # tests, version supporting openssl 1.1, binary build
+    pyenv install 3.11.1  # tests, version supporting openssl 1.1
-    pyenv install 3.8.0  # tests, version supporting openssl 1.1
+    pyenv install 3.10.2  # tests, version supporting openssl 1.1
+    pyenv install 3.9.18  # tests, version supporting openssl 1.1, binary build
     pyenv rehash
   EOF
 end
@@ -176,8 +179,8 @@ def build_pyenv_venv(boxname)
     . ~/.bash_profile
     cd /vagrant/borg
     # use the latest 3.9 release
-    pyenv global 3.9.10
+    pyenv global 3.9.18
-    pyenv virtualenv 3.9.10 borg-env
+    pyenv virtualenv 3.9.18 borg-env
     ln -s ~/.pyenv/versions/borg-env .
   EOF
 end
@@ -201,10 +204,7 @@ def install_pyinstaller()
     . ~/.bash_profile
     cd /vagrant/borg
     . borg-env/bin/activate
-    git clone https://github.com/thomaswaldmann/pyinstaller.git
+    pip install 'pyinstaller==4.10'
-    cd pyinstaller
-    git checkout v4.7-maint
-    python setup.py install
   EOF
 end
 
@@ -227,10 +227,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.9.18 3.10.2 3.11.1 3.12.0
-      pyenv local 3.8.0 3.9.10 3.10.0
+      pyenv local 3.9.18 3.10.2 3.11.1 3.12.0
     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
@@ -281,6 +283,34 @@ Vagrant.configure(2) do |config|
     b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("focal64", ".*none.*")
   end
 
+  config.vm.define "jammy64" 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("jammy64")
+    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("jammy64", ".*none.*")
+  end
+
+  config.vm.define "bookworm64" 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("bookworm64")
+    b.vm.provision "install pythons", :type => :shell, :privileged => false, :inline => install_pythons("bookworm64")
+    b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_pyenv_venv("bookworm64")
+    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("bookworm64")
+    b.vm.provision "run tests", :type => :shell, :privileged => false, :inline => run_tests("bookworm64", ".*none.*")
+  end
+
   config.vm.define "bullseye64" do |b|
     b.vm.box = "debian/bullseye64"
     b.vm.provider :virtualbox do |v|
@@ -314,7 +344,7 @@ Vagrant.configure(2) do |config|
   end
 
   config.vm.define "stretch64" do |b|
-    b.vm.box = "debian/stretch64"
+    b.vm.box = "generic/debian9"
     b.vm.provider :virtualbox do |v|
       v.memory = 1024 + $wmem
     end
@@ -330,7 +360,7 @@ Vagrant.configure(2) do |config|
   end
 
   config.vm.define "freebsd64" do |b|
-    b.vm.box = "freebsd121-64"
+    b.vm.box = "generic/freebsd13"
     b.vm.provider :virtualbox do |v|
       v.memory = 1024 + $wmem
     end
@@ -347,7 +377,7 @@ Vagrant.configure(2) do |config|
   end
 
   config.vm.define "openbsd64" do |b|
-    b.vm.box = "generic/openbsd6"
+    b.vm.box = "openbsd71-64"
     b.vm.provider :virtualbox do |v|
       v.memory = 1024 + $wmem
     end

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/changes.rst

@@ -5,6 +5,83 @@ Important notes
 
 This section provides information about security and corruption issues.
 
+.. _archives_tam_vuln:
+
+Pre-1.2.5 archives spoofing vulnerability (CVE-2023-36811)
+----------------------------------------------------------
+
+A flaw in the cryptographic authentication scheme in Borg allowed an attacker to
+fake archives and potentially indirectly cause backup data loss in the repository.
+
+The attack requires an attacker to be able to
+
+1. insert files (with no additional headers) into backups
+2. gain write access to the repository
+
+This vulnerability does not disclose plaintext to the attacker, nor does it
+affect the authenticity of existing archives.
+
+Creating plausible fake archives may be feasible for empty or small archives,
+but is unlikely for large archives.
+
+The fix enforces checking the TAM authentication tag of archives at critical
+places. Borg now considers archives without TAM as garbage or an attack.
+
+We are not aware of others having discovered, disclosed or exploited this vulnerability.
+
+Below, if we speak of borg 1.2.6, we mean a borg version >= 1.2.6 **or** a
+borg version that has the relevant security patches for this vulnerability applied
+(could be also an older version in that case).
+
+Steps you must take to upgrade a repository (this applies to all kinds of repos
+no matter what encryption mode they use, including "none"):
+
+1. Upgrade all clients using this repository to borg 1.2.6.
+   Note: it is not required to upgrade a server, except if the server-side borg
+   is also used as a client (and not just for "borg serve").
+
+   Do **not** run ``borg check`` with borg 1.2.6 before completing the upgrade steps:
+
+   - ``borg check`` would complain about archives without a valid archive TAM.
+   - ``borg check --repair`` would remove such archives!
+2. Run: ``BORG_WORKAROUNDS=ignore_invalid_archive_tam borg info --debug <repo> 2>&1 | grep TAM | grep -i manifest``
+
+   a) If you get "TAM-verified manifest", continue with 3.
+   b) If you get "Manifest TAM not found and not required", run
+      ``borg upgrade --tam --force <repository>`` *on every client*.
+
+3. Run: ``BORG_WORKAROUNDS=ignore_invalid_archive_tam borg list --consider-checkpoints --format='{name} {time} tam:{tam}{NL}' <repo>``
+
+   "tam:verified" means that the archive has a valid TAM authentication.
+   "tam:none" is expected as output for archives created by borg <1.0.9.
+   "tam:none" is also expected for archives resulting from a borg rename
+   or borg recreate operation (see #7791).
+   "tam:none" could also come from archives created by an attacker.
+   You should verify that "tam:none" archives are authentic and not malicious
+   (== have good content, have correct timestamp, can be extracted successfully).
+   In case you find crappy/malicious archives, you must delete them before proceeding.
+   In low-risk, trusted environments, you may decide on your own risk to skip step 3
+   and just trust in everything being OK.
+
+4. If there are no tam:none archives left at this point, you can skip this step.
+   Run ``BORG_WORKAROUNDS=ignore_invalid_archive_tam borg upgrade --archives-tam <repo>``.
+   This will unconditionally add a correct archive TAM to all archives not having one.
+   ``borg check`` would consider TAM-less or invalid-TAM archives as garbage or a potential attack.
+   To see that all archives now are "tam:verified" run: ``borg list --consider-checkpoints --format='{name} {time} tam:{tam}{NL}' <repo>``
+
+5. Please note that you should never use BORG_WORKAROUNDS=ignore_invalid_archive_tam
+   for normal production operations - it is only needed once to get the archives in a
+   repository into a good state. All archives have a valid TAM now.
+
+Vulnerability time line:
+
+* 2023-06-13: Vulnerability discovered during code review by Thomas Waldmann
+* 2023-06-13...: Work on fixing the issue, upgrade procedure, docs.
+* 2023-06-30: CVE was assigned via Github CNA
+* 2023-06-30 .. 2023-08-29: Fixed issue, code review, docs, testing.
+* 2023-08-30: Released fixed version 1.2.5 (broken upgrade procedure for some repos)
+* 2023-08-31: Released fixed version 1.2.6 (fixes upgrade procedure)
+
 .. _hashindex_set_bug:
 
 Pre-1.1.11 potential index corruption / data loss issue
@@ -212,26 +289,17 @@ The best check that everything is ok is to run a dry-run extraction::
 
     borg extract -v --dry-run REPO::ARCHIVE
 
-.. _changelog:
+.. _upgradenotes:
 
-Change Log
+Upgrade Notes
-==========
+=============
 
+borg 1.1.x to 1.2.x
+-------------------
 
-Version 1.2.0 (2022-02-22 22:02:22 :-)
+Some things can be recommended for the upgrade process from borg 1.1.x
---------------------------------------
+(please also read the important compatibility notes below):
 
-Please note:
-
-This is the first borg 1.2 release, so be careful and read the notes below.
-
-Upgrade notes:
-
-Strictly taken, nothing special is required for upgrading to 1.2, but some
-things can be recommended:
-
-- do you already want to upgrade? 1.1.x also will get fixes for a while.
-- be careful, first upgrade your less critical / smaller repos.
 - first upgrade to a recent 1.1.x release - especially if you run some older
   1.1.* or even 1.0.* borg release.
 - using that, run at least one `borg create` (your normal backup), `prune`
@@ -239,10 +307,12 @@ things can be recommended:
 - check the output of `borg check` - if there is anything special, consider
   a `borg check --repair` followed by another `borg check`.
 - if everything is fine so far (borg check reports no issues), you can consider
-  upgrading to 1.2.0. if not, please first fix any already existing issue.
+  upgrading to 1.2.x. if not, please first fix any already existing issue.
 - if you want to play safer, first **create a backup of your borg repository**.
 - upgrade to latest borg 1.2.x release (you could use the fat binary from
   github releases page)
+- borg 1.2.6 has a security fix for the pre-1.2.5 archives spoofing vulnerability
+  (CVE-2023-36811), see details and necessary upgrade procedure described above.
 - run `borg compact --cleanup-commits` to clean up a ton of 17 bytes long files
   in your repo caused by a borg 1.1 bug
 - run `borg check` again (now with borg 1.2.x) and check if there is anything
@@ -260,6 +330,10 @@ and maybe just were not noticed.
 
 Compatibility notes:
 
+- matching of path patterns has been aligned with borg storing relative paths.
+  Borg archives file paths without leading slashes. Previously, include/exclude
+  patterns could contain leading slashes. You should check your patterns and
+  remove leading slashes.
 - dropped support / testing for older Pythons, minimum requirement is 3.8.
   In case your OS does not provide Python >= 3.8, consider using our binary,
   which does not need an external Python interpreter. Or continue using
@@ -268,6 +342,7 @@ Compatibility notes:
 - mount: the default for --numeric-ids is False now (same as borg extract)
 - borg create --noatime is deprecated. Not storing atime is the default behaviour
   now (use --atime if you want to store the atime).
+- --prefix is deprecated, use -a / --glob-archives, see #6806
 - list: corrected mix-up of "isomtime" and "mtime" formats.
   Previously, "isomtime" was the default but produced a verbose human format,
   while "mtime" produced a ISO-8601-like format.
@@ -297,6 +372,356 @@ Compatibility notes:
   if you have scripts expecting rc == 2 for a signal exit, you need to update
   them to check for >= 128.
 
+
+.. _changelog:
+
+Change Log
+==========
+
+Version 1.2.7 (2023-12-02)
+--------------------------
+
+For upgrade and compatibility hints, please also read the section "Upgrade Notes"
+above.
+
+Fixes:
+
+- docs: CVE-2023-36811 upgrade steps: consider checkpoint archives, #7802
+- check/compact: fix spurious reappearance of orphan chunks since borg 1.2, #6687 -
+  this consists of 2 fixes:
+
+  - for existing chunks: check --repair: recreate shadow index, #6687
+  - for newly created chunks: update shadow index when doing a double-put, #5661
+- LockRoster.modify: no KeyError if element was already gone, #7937
+- create --X-from-command: run subcommands with a clean environment, #7916
+- list --sort-by: support "archive" as alias of "name", #7873
+- fix rc and msg if arg parsing throws an exception, #7885
+
+Other changes:
+
+- support and test on Python 3.12
+- include unistd.h in _chunker.c (fix for Python 3.13)
+- allow msgpack 1.0.6 and 1.0.7
+- TAM issues: show tracebacks, improve borg check logging, #7797
+- replace "datetime.utcfromtimestamp" with custom helper to avoid
+  deprecation warnings when using Python 3.12
+- vagrant:
+
+  - use generic/debian9 box, fixes #7579
+  - add VM with debian bookworm / test on OpenSSL 3.0.x.
+- docs:
+
+  - not only attack/unsafe, can also be a fs issue, #7853
+  - point to CVE-2023-36811 upgrade steps from borg 1.1 to 1.2 upgrade steps, #7899
+  - upgrade steps needed for all kinds of repos (including "none" encryption mode), #7813
+  - upgrade steps: talk about consequences of borg check, #7816
+  - upgrade steps: remove period that could be interpreted as part of the command
+  - automated-local.rst: use GPT UUID for consistent udev rule
+  - create disk/partition sector backup by disk serial number, #7934
+  - update macOS hint about full disk access
+  - clarify borg prune -a option description, #7871
+  - readthedocs: also build offline docs (HTMLzip), #7835
+  - frontends: add "check.rebuild_refcounts" message
+
+
+Version 1.2.6 (2023-08-31)
+--------------------------
+
+Fixes:
+
+- The upgrade procedure docs as published with borg 1.2.5 did not work, if the
+  repository had archives resulting from a borg rename or borg recreate operation.
+
+  The updated docs now use BORG_WORKAROUNDS=ignore_invalid_archive_tam at some
+  places to avoid that issue, #7791.
+
+  See: fix pre-1.2.5 archives spoofing vulnerability (CVE-2023-36811),
+  details and necessary upgrade procedure described above.
+
+Other changes:
+
+- updated 1.2.5 changelog entry: 1.2.5 already has the fix for rename/recreate.
+- remove cython restrictions. recommended is to build with cython 0.29.latest,
+  because borg 1.2.x uses this since years and it is very stable.
+  you can also try to build with cython 3.0.x, there is a good chance that it works.
+  as a 3rd option, we also bundle the `*.c` files cython outputs in the release
+  pypi package, so you can also just use these and not need cython at all.
+
+
+Version 1.2.5 (2023-08-30)
+--------------------------
+
+Fixes:
+
+- Security: fix pre-1.2.5 archives spoofing vulnerability (CVE-2023-36811),
+  see details and necessary upgrade procedure described above.
+- rename/recreate: correctly update resulting archive's TAM, see #7791
+- create: do not try to read parent dir of recursion root, #7746
+- extract: fix false warning about pattern never matching, #4110
+- diff: remove surrogates before output, #7535
+- compact: clear empty directories at end of compact process, #6823
+- create --files-cache=size: fix crash, #7658
+- keyfiles: improve key sanity check, #7561
+- only warn about "invalid" chunker params, #7590
+- ProgressIndicatorPercent: fix space computation for wide chars, #3027
+- improve argparse validator error messages
+
+New features:
+
+- mount: make up volname if not given (macOS), #7690.
+  macFUSE supports a volname mount option to give what finder displays on the
+  desktop / in the directory view. if the user did not specify it, we make
+  something up, because otherwise it would be "macFUSE Volume 0 (Python)" and
+  hide the mountpoint directory name.
+- BORG_WORKAROUNDS=authenticated_no_key to extract from authenticated repos
+  without key, #7700
+
+Other changes:
+
+- add `utcnow()` helper function to avoid deprecated `datetime.utcnow()`
+- stay on latest Cython 0.29 (0.29.36) for borg 1.2.x (do not use Cython 3.0 yet)
+- docs:
+
+  - move upgrade notes to own section, see #7546
+  - mount -olocal: how to show mount in finder's sidebar, #5321
+  - list: fix --pattern examples, #7611
+  - improve patterns help
+  - incl./excl. options, path-from-stdin exclusiveness
+  - obfuscation docs: markup fix, note about MAX_DATA_SIZE
+  - --one-file-system: add macOS apfs notes, #4876
+  - improve --one-file-system help string, #5618
+  - rewrite borg check docs
+  - improve the docs for --keep-within, #7687
+  - fix borg init command in environment.rst.inc
+  - 1.1.x upgrade notes: more precise borg upgrade instructions, #3396
+
+- tests:
+
+  - fix repo reopen
+  - avoid long ids in pytest output
+  - check buzhash chunksize distribution, see #7586
+
+
+Version 1.2.4 (2023-03-24)
+--------------------------
+
+New features:
+
+- import-tar: add --ignore-zeros to process concatenated tars, #7432.
+- debug id-hash: computes file/chunk content id-hash, #7406
+- diff: --content-only does not show mode/ctime/mtime changes, #7248
+- diff: JSON strings in diff output are now sorted alphabetically
+
+Bug fixes:
+
+- xattrs: fix namespace processing on FreeBSD, #6997
+- diff: fix path related bug seen when addressing deferred items.
+- debug get-obj/put-obj: always give chunkid as cli param, see #7290
+  (this is an incompatible change, see also borg debug id-hash)
+- extract: fix mtime when ResourceFork xattr is set (macOS specific), #7234
+- recreate: without --chunker-params, do not re-chunk, #7337
+- recreate: when --target is given, do not detect "nothing to do".
+  use case: borg recreate -a src --target dst can be used to make a copy
+  of an archive inside the same repository, #7254.
+- set .hardlink_master for ALL hardlinkable items, #7175
+- locking: fix host, pid, tid order.
+  tid (thread id) must be parsed as hex from lock file name.
+- update development.lock.txt, including a setuptools security fix, #7227
+
+Other changes:
+
+- requirements: allow msgpack 1.0.5 also
+- upgrade Cython to 0.29.33
+- hashindex minor fixes, refactor, tweaks, tests
+- use os.replace not os.rename
+- remove BORG_LIBB2_PREFIX (not used any more)
+- docs:
+
+  - BORG_KEY_FILE: clarify docs, #7444
+  - update FAQ about locale/unicode issues, #6999
+  - improve mount options rendering, #7359
+  - make timestamps in manual pages reproducible
+  - installation: update Fedora in distribution list, #7357
+- tests:
+
+  - fix test_size_on_disk_accurate for large st_blksize, #7250
+  - add same_ts_ns function and use it for relaxed timestamp comparisons
+  - "auto" compressor tests: don't assume a specific size,
+    do not assume zlib is better than lz4, #7363
+  - add test for extracted directory mtime
+- vagrant:
+
+  - upgrade local freebsd 12.1 box -> generic/freebsd13 box (13.1)
+  - use pythons > 3.8 which work on freebsd 13.1
+  - pyenv: also install python 3.11.1 for testing
+  - pyenv: use python 3.10.1, 3.10.0 build is broken on freebsd
+
+
+Version 1.2.3 (2022-12-24)
+--------------------------
+
+Fixes:
+
+- create: fix --list --dry-run output for directories, #7209
+- diff/recreate: normalize chunker params before comparing them, #7079
+- check: fix uninitialised variable if repo is completely empty, #7034
+- xattrs: improve error handling, #6988
+- fix args.paths related argparsing, #6994
+- archive.save(): always use metadata from stats (e.g. nfiles, size, ...), #7072
+- tar_filter: recognize .tar.zst as zstd, #7093
+- get_chunker: fix missing sparse=False argument, #7056
+- file_integrity.py: make sure file_fd is always closed on exit
+- repository: cleanup(): close segment before unlinking
+- repository: use os.replace instead of os.rename
+
+Other changes:
+
+- remove python < 3.7 compatibility code
+- do not use version_tuple placeholder in setuptools_scm template
+- CI: fix tox4 passenv issue, #7199
+- vagrant: update to python 3.9.16, use the openbsd 7.1 box
+- misc. test suite and docs fixes / improvements
+- remove deprecated --prefix from docs, #7109
+- Windows: use MSYS2 for Github CI, remove Appveyor CI
+
+
+Version 1.2.2 (2022-08-20)
+--------------------------
+
+New features:
+
+- prune/delete --checkpoint-interval=1800 and ctrl-c/SIGINT support, #6284
+
+Fixes:
+
+- SaveFile: use a custom mkstemp with mode support, #6933, #6400, #6786.
+  This fixes umask/mode/ACL issues (and also "chmod not supported" exceptions
+  seen in 1.2.1) of files updated using SaveFile, e.g. the repo config.
+- hashindex_compact: fix eval order (check idx before use), #5899
+- create --paths-from-(stdin|command): normalize paths, #6778
+- secure_erase: avoid collateral damage, #6768.
+  If a hardlink copy of a repo was made and a new repo config shall be saved,
+  do NOT fill in random garbage before deleting the previous repo config,
+  because that would damage the hardlink copy.
+- list: fix {flags:<WIDTH>} formatting, #6081
+- check: try harder to create the key, #5719
+- misc commands: ctrl-c must not kill other subprocesses, #6912
+
+  - borg create with a remote repo via ssh
+  - borg create --content-from-command
+  - borg create --paths-from-command
+  - (de)compression filter process of import-tar / export-tar
+
+Other changes:
+
+- deprecate --prefix, use -a / --glob-archives, see #6806
+- make setuptools happy ("package would be ignored"), #6874
+- fix pyproject.toml to create a fixed _version.py file, compatible with both
+  old and new setuptools_scm version, #6875
+- automate asciinema screencasts
+- CI: test on macOS 12 without fuse / fuse tests
+  (too troublesome on github CI due to kernel extensions needed by macFUSE)
+- tests: fix test_obfuscate byte accounting
+- repository: add debug logging for issue #6687
+- _chunker.c: fix warnings on macOS
+- requirements.lock.txt: use the latest cython 0.29.32
+- docs:
+
+  - add info on man page installation, #6894
+  - update archive_progress json description about "finished", #6570
+  - json progress_percent: some values are optional, #4074
+  - FAQ: full quota / full disk, #5960
+  - correct shell syntax for installation using git
+
+
+Version 1.2.1 (2022-06-06)
+--------------------------
+
+Fixes:
+
+- create: skip with warning if opening the parent dir of recursion root fails, #6374
+- create: fix crash. metadata stream can produce all-zero chunks, #6587
+- fix crash when computing stats, escape % chars in archive name, #6500
+- fix transaction rollback: use files cache filename as found in txn.active/, #6353
+- import-tar: kill filter process in case of borg exceptions, #6401 #6681
+- import-tar: fix mtime type bug
+- ensure_dir: respect umask for created directory modes, #6400
+- SaveFile: respect umask for final file mode, #6400
+- check archive: improve error handling for corrupt archive metadata block, make
+  robust_iterator more robust, #4777
+- pre12-meta cache: do not use the cache if want_unique is True, #6612
+- fix scp-style repo url parsing for ip v6 address, #6526
+- mount -o versions: give clear error msg instead of crashing.
+  it does not make sense to request versions view if you only look at 1 archive,
+  but the code shall not crash in that case as it did, but give a clear error msg.
+- show_progress: add finished=true/false to archive_progress json, #6570
+- delete/prune: fix --iec mode output (decimal vs. binary units), #6606
+- info: fix authenticated mode repo to show "Encrypted: No", #6462
+- diff: support presence change for blkdev, chrdev and fifo items, #6615
+
+New features:
+
+- delete: add repository id and location to prompt, #6453
+- borg debug dump-repo-objs --ghost: new --segment=S --offset=O options
+
+Other changes:
+
+- support python 3.11
+- allow msgpack 1.0.4, #6716
+- load_key: no key is same as empty key, #6441
+- give a more helpful error msg for unsupported key formats, #6561
+- better error msg for defect or unsupported repo configs, #6566
+- docs:
+
+  - document borg 1.2 pattern matching behavior change, #6407
+    Make clear that absolute paths always go into the matcher as if they are
+    relative (without leading slash). Adapt all examples accordingly.
+  - authentication primitives: improved security and performance infos
+  - mention BORG_FILES_CACHE_SUFFIX as alternative to BORG_FILES_CACHE_TTL, #5602
+  - FAQ: add a hint about --debug-topic=files_cache
+  - improve borg check --max-duration description
+  - fix values of TAG bytes, #6515
+  - borg compact --cleanup-commits also runs a normal compaction, #6324
+  - virtualization speed tips
+  - recommend umask for passphrase file perms
+  - borg 1.2 is security supported
+  - update link to ubuntu packages, #6485
+  - use --numeric-ids in pull mode docs
+  - remove blake2 docs, blake2 code not bundled any more, #6371
+  - clarify on-disk order and size of segment file log entry fields, #6357
+  - docs building: do not transform --/--- to unicode dashes
+- tests:
+
+  - check that borg does not require pytest for normal usage, fixes #6563
+  - fix OpenBSD symlink mode test failure, #2055
+- vagrant:
+
+  - darwin64: remove fakeroot, #6314
+  - update development.lock.txt
+  - use pyinstaller 4.10 and python 3.9.13 for binary build
+  - upgrade VMCPUS and xdistn from 4 to 16, maybe this speeds up the tests
+- crypto:
+
+  - use hmac.compare_digest instead of ==, #6470
+  - hmac_sha256: replace own cython wrapper code by hmac.digest python stdlib (since py38)
+  - hmac and blake2b minor optimizations and cleanups
+  - removed some unused crypto related code, #6472
+  - avoid losing the key (potential use-after-free). this never could happen in
+    1.2 due to the way we use the code. The issue was discovered in master after
+    other changes, so we also "fixed" it here before it bites us.
+- setup / build:
+
+  - add pyproject.toml, fix sys.path, #6466
+  - setuptools_scm: also require it via pyproject.toml
+  - allow extra compiler flags for every extension build
+  - fix misc. C / Cython compiler warnings, deprecation warnings
+  - fix zstd.h include for bundled zstd, #6369
+- source using python 3.8 features: ``pyupgrade --py38-plus ./**/*.py``
+
+
+Version 1.2.0 (2022-02-22 22:02:22 :-)
+--------------------------------------
+
 Fixes:
 
 - diff: reduce memory consumption, fix is_hardlink_master, #6295
@@ -543,7 +968,7 @@ Other changes:
   - add examples for --paths-from-stdin, --paths-from-command, --paths-separator, #5644
   - fix typos/grammar
   - update docs for dev environment installation instructions
-  - recomend running tests only on installed versions for setup
+  - recommend running tests only on installed versions for setup
   - add badge with current status of package
 - vagrant:
 
@@ -1036,6 +1461,156 @@ Other changes:
 
 
 
+Version 1.1.18 (2022-06-05)
+---------------------------
+
+Compatibility notes:
+
+- When upgrading from borg 1.0.x to 1.1.x, please note:
+
+  - read all the compatibility notes for 1.1.0*, starting from 1.1.0b1.
+  - borg upgrade: you do not need to and you also should not run it.
+    There is one exception though:
+    If you upgrade from an unpatched borg < 1.0.9, please read that section
+    above: "Pre-1.0.9 manifest spoofing vulnerability (CVE-2016-10099)"
+  - borg might ask some security-related questions once after upgrading.
+    You can answer them either manually or via environment variable.
+    One known case is if you use unencrypted repositories, then it will ask
+    about a unknown unencrypted repository one time.
+  - your first backup with 1.1.x might be significantly slower (it might
+    completely read, chunk, hash a lot files) - this is due to the
+    --files-cache mode change (and happens every time you change mode).
+    You can avoid the one-time slowdown by using the pre-1.1.0rc4-compatible
+    mode (but that is less safe for detecting changed files than the default).
+    See the --files-cache docs for details.
+- 1.1.11 removes WSL autodetection (Windows 10 Subsystem for Linux).
+  If WSL still has a problem with sync_file_range, you need to set
+  BORG_WORKAROUNDS=basesyncfile in the borg process environment to
+  work around the WSL issue.
+- 1.1.14 changes return codes due to a bug fix:
+  In case you have scripts expecting rc == 2 for a signal exit, you need to
+  update them to check for >= 128 (as documented since long).
+- 1.1.15 drops python 3.4 support, minimum requirement is 3.5 now.
+- 1.1.17 install_requires the "packaging" pypi package now.
+
+New features:
+
+- check --repair: significantly speed up search for next valid object in segment, #6022
+- create: add retry_erofs workaround for O_NOATIME issue on volume shadow copies in WSL1, #6024
+- key export: display key if path is '-' or not given, #6092
+- list --format: add command_line to format keys, #6108
+
+Fixes:
+
+- check: improve error handling for corrupt archive metadata block,
+  make robust_iterator more robust, #4777
+- diff: support presence change for blkdev, chrdev and fifo items, #6483
+- diff: reduce memory consumption, fix is_hardlink_master
+- init: disallow overwriting of existing keyfiles
+- info: fix authenticated mode repo to show "Encrypted: No", #6462
+- info: emit repo info even if repo has 0 archives, #6120
+- list: remove placeholders for shake_* hashes, #6082
+- mount -o versions: give clear error msg instead of crashing
+- show_progress: add finished=true/false to archive_progress json, #6570
+- fix hardlinkable file type check, #6037
+- do not show archive name in error msgs referring to the repository, #6023
+- prettier error msg (no stacktrace) if exclude file is missing, #5734
+- do not require BORG_CONFIG_DIR if BORG_{SECURITY,KEYS}_DIR are set, #5979
+- atomically create the CACHE_TAG file, #6028
+- deal with the SaveFile/SyncFile race, docs, see #6176 5c5b59bc9
+- avoid expanding path into LHS of formatting operation + tests, #6064 #6063
+- repository: quota / compactable computation fixes, #6119.
+  This is mainly to keep the repo code in sync with borg 1.2. As borg 1.1
+  compacts immediately, there was not really an issue with this in 1.1.
+- fix transaction rollback: use files cache filename as found in txn.active, #6353
+- do not load files cache for commands not using it, fixes #5673
+- fix scp repo url parsing for ip v6 addrs, #6526
+- repo::archive location placeholder expansion fixes, #5826, #5998
+
+  - use expanded location for log output
+  - support placeholder expansion for BORG_REPO env var
+- respect umask for created directory and file modes, #6400
+- safer truncate_and_unlink implementation
+
+Other changes:
+
+- upgrade bundled xxhash code to 0.8.1
+- fix xxh64 related build (setup.py and post-0.8.1 patch for static_assert).
+  The patch was required to build the bundled xxhash code on FreeBSD, see
+  https://github.com/Cyan4973/xxHash/pull/670
+- msgpack build: remove endianness macro, #6105
+- update and fix shell completions
+- fuse: remove unneeded version check and compat code
+- delete --force: do not ask when deleting a repo, #5941
+- delete: don't commit if nothing was deleted, avoid cache sync, #6060
+- delete: add repository id and location to prompt
+- compact segments: improve freeable / freed space log output, #5679
+- if ensure_dir() fails, give more informative error message, #5952
+- load_key: no key is same as empty key, #6441
+- better error msg for defect or unsupported repo configs, #6566
+- use hmac.compare_digest instead of ==, #6470
+- implement more standard hashindex.setdefault behaviour
+- remove stray punctuation from secure-erase message
+- add development.lock.txt, use a real python 3.5 to generate frozen reqs
+- setuptools 60.7.0 breaks pyinstaller, #6246
+- setup.py clean2 was added to work around some setuptools customizability limitation.
+- allow extra compiler flags for every extension build
+- C code: make switch fallthrough explicit
+- Cython code: fix "useless trailing comma" cython warnings
+- requirements.lock.txt: use the latest cython 0.29.30
+- fix compilation warnings: ‘PyUnicode_AsUnicode’ is deprecated
+- docs:
+
+  - ~/.config/borg/keys is not used for repokey keys, #6107
+  - excluded parent dir's metadata can't restore, #6062
+  - permissions note rewritten to make it less confusing, #5490
+  - add note about grandfather-father-son backup retention policy / rotation scheme
+  - clarify who starts the remote agent (borg serve)
+  - test/improve pull backup docs, #5903
+  - document the socat pull mode described in #900 #515ß
+  - borg serve: improve ssh forced commands docs, #6083
+  - improve docs for borg list --format, #6080
+  - fix the broken link to .nix file
+  - clarify pattern usage with commands, #5176
+  - clarify user_id vs uid for fuse, #5723
+  - fix binary build freebsd/macOS version, #5942
+  - FAQ: fix manifest-timestamp path, #6016
+  - remove duplicate faq entries, #5926
+  - fix sphinx warnings, #5919
+  - virtualisation speed tips
+  - fix values of TAG bytes, #6515
+  - recommend umask for passphrase file perms
+  - update link to ubuntu packages, #6485
+  - clarify on-disk order and size of log entry fields, #6357
+  - do not transform --/--- to unicode dashes
+  - improve linking inside docs, link to borg_placeholders, link to borg_patterns
+  - use same phrasing in misc. help texts
+  - borg init: explain the encryption modes better
+  - explain the difference between a path that ends with or without a slash, #6297
+  - clarify usage of patternfile roots, #6242
+  - borg key export: add examples
+  - updates about features not experimental any more: FUSE "versions" view, --pattern*, #6134
+  - fix/update cygwin package requirements
+  - impact of deleting path/to/repo/nonce, #5858
+  - warn about tampered server nonce
+  - mention BORG_FILES_CACHE_SUFFIX as alternative to BORG_FILES_CACHE_TTL, #5602
+  - add a troubleshooting note about "is not a valid repository" to the FAQ
+- vagrant / CI / testing:
+
+  - misc. fixes and updates, new python versions
+  - macOS on github: re-enable fuse2 testing by downgrading to older macOS, #6099
+  - fix OpenBSD symlink mode test failure, #2055
+  - use the generic/openbsd6 box
+  - strengthen the test: we can read data w/o nonces
+  - add tests for path/to/repo/nonce deletion
+  - darwin64: backport some tunings from master
+  - darwin64: remove fakeroot, #6314
+  - darwin64: fix vagrant scp, #5921
+  - darwin64: use macfuse instead of osxfuse
+  - add ubuntu "jammy" 22.04 LTS VM
+  - adapt memory for openindiana64 and darwin64
+
+
 Version 1.1.17 (2021-07-12)
 ---------------------------
 
@@ -1045,6 +1620,9 @@ Compatibility notes:
 
   - read all the compatibility notes for 1.1.0*, starting from 1.1.0b1.
   - borg upgrade: you do not need to and you also should not run it.
+    There is one exception though:
+    If you upgrade from an unpatched borg < 1.0.9, please read that section
+    above: "Pre-1.0.9 manifest spoofing vulnerability (CVE-2016-10099)"
   - borg might ask some security-related questions once after upgrading.
     You can answer them either manually or via environment variable.
     One known case is if you use unencrypted repositories, then it will ask
@@ -1172,7 +1750,7 @@ Other changes:
   - use macFUSE (not osxfuse) for Apple M1 compatibility
   - update docs for dev environment installation instructions, #5643
   - fix grammar in faq
-  - recomend running tests only on installed versions for setup
+  - recommend running tests only on installed versions for setup
   - add link back to git-installation
   - remove /var/cache exclusion in example commands, #5625.
     This is generally a poor idea and shouldn't be promoted through examples.
@@ -1315,6 +1893,9 @@ Compatibility notes:
 
   - read all the compatibility notes for 1.1.0*, starting from 1.1.0b1.
   - borg upgrade: you do not need to and you also should not run it.
+    There is one exception though:
+    If you upgrade from an unpatched borg < 1.0.9, please read that section
+    above: "Pre-1.0.9 manifest spoofing vulnerability (CVE-2016-10099)"
   - borg might ask some security-related questions once after upgrading.
     You can answer them either manually or via environment variable.
     One known case is if you use unencrypted repositories, then it will ask
@@ -1387,6 +1968,9 @@ Compatibility notes:
 
   - read all the compatibility notes for 1.1.0*, starting from 1.1.0b1.
   - borg upgrade: you do not need to and you also should not run it.
+    There is one exception though:
+    If you upgrade from an unpatched borg < 1.0.9, please read that section
+    above: "Pre-1.0.9 manifest spoofing vulnerability (CVE-2016-10099)"
   - borg might ask some security-related questions once after upgrading.
     You can answer them either manually or via environment variable.
     One known case is if you use unencrypted repositories, then it will ask
@@ -1570,6 +2154,9 @@ Compatibility notes:
 
   - read all the compatibility notes for 1.1.0*, starting from 1.1.0b1.
   - borg upgrade: you do not need to and you also should not run it.
+    There is one exception though:
+    If you upgrade from an unpatched borg < 1.0.9, please read that section
+    above: "Pre-1.0.9 manifest spoofing vulnerability (CVE-2016-10099)"
   - borg might ask some security-related questions once after upgrading.
     You can answer them either manually or via environment variable.
     One known case is if you use unencrypted repositories, then it will ask
@@ -1863,6 +2450,9 @@ Compatibility notes:
 
   - read all the compatibility notes for 1.1.0*, starting from 1.1.0b1.
   - borg upgrade: you do not need to and you also should not run it.
+    There is one exception though:
+    If you upgrade from an unpatched borg < 1.0.9, please read that section
+    above: "Pre-1.0.9 manifest spoofing vulnerability (CVE-2016-10099)"
   - borg might ask some security-related questions once after upgrading.
     You can answer them either manually or via environment variable.
     One known case is if you use unencrypted repositories, then it will ask
@@ -3185,7 +3775,7 @@ Other changes:
     cryptohash for dedupe, so people don't worry, #2390
   - add hint about chunker params to borg upgrade docs, #2421
   - clarify borg upgrade docs, #2436
-  - quickstart: delete problematic BORG_PASSPRHASE use, #2623
+  - quickstart: delete problematic BORG_PASSPHRASE use, #2623
   - faq: specify "using inline shell scripts"
   - document pattern denial of service, #2624
 - tests:
@@ -3925,7 +4515,7 @@ Bug fixes:
   Makes --cache-only idempotent: it won't fail if the cache is already deleted.
 - fixed borg create --one-file-system erroneously traversing into other
   filesystems (if starting fs device number was 0), #873
-- workround a bug in Linux fadvise FADV_DONTNEED, #907
+- workaround a bug in Linux fadvise FADV_DONTNEED, #907
 
 Other changes:
 

docs/conf.py

@@ -40,7 +40,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-2023 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
@@ -154,6 +154,7 @@ 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 = {
@@ -258,6 +259,6 @@ extensions = [
 ]
 
 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/automated-local.rst

@@ -29,26 +29,12 @@ Configuring the system
 First, create the ``/etc/backups`` directory (as root).
 All configuration goes into this directory.
 
+Find out the ID of the partition table of your backup disk (here assumed to be /dev/sdz):
+    lsblk --fs -o +PTUUID /dev/sdz
+
 Then, create ``/etc/backups/40-backup.rules`` with the following content (all on one line)::
 
-    ACTION=="add", SUBSYSTEM=="bdi", DEVPATH=="/devices/virtual/bdi/*",
+    ACTION=="add", SUBSYSTEM=="block", ENV{ID_PART_TABLE_UUID}=="<the PTUUID you just noted>", TAG+="systemd", ENV{SYSTEMD_WANTS}="automatic-backup.service"
-    TAG+="systemd", ENV{SYSTEMD_WANTS}="automatic-backup.service"
-
-.. topic:: Finding a more precise udev rule
-
-    If you always connect the drive(s) to the same physical hardware path, e.g. the same
-    eSATA port, then you can make a more precise udev rule.
-
-    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
@@ -110,7 +96,7 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
     # Mount 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/
 

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 importancy to pin down the disk you want to backup.
+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
 ------------------------------------
 
@@ -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/pull-backup.rst

@@ -58,7 +58,7 @@ 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
@@ -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

@@ -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,13 @@ 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
 -----------------
 
@@ -195,26 +199,6 @@ Important notes:
 - When using ``--`` to give options to py.test, you MUST also give ``borg.testsuite[.module]``.
 
 
-Running more checks using coala
--------------------------------
-
-First install coala and some checkers ("bears"):
-
-::
-
-  pip install -r requirements.d/coala.txt
-
-You can now run coala from the toplevel directory; it will read its settings
-from ``.coafile`` there:
-
-::
-
-  coala
-
-Some bears have additional requirements and they usually tell you about
-them in case they are missing.
-
-
 Adding a compression algorithm
 ------------------------------
 
@@ -349,6 +333,9 @@ Checklist:
     scripts/sdist-sign X.Y.Z
     scripts/upload-pypi X.Y.Z test
     scripts/upload-pypi X.Y.Z
+
+  Note: the signature is not uploaded to PyPi any more, but we upload it to
+  github releases.
 - Put binaries into dist/borg-OSNAME and sign them:
 
   ::
@@ -366,9 +353,10 @@ Checklist:
 
 - Create a GitHub release, include:
 
+  * 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, document the macFUSE version in the README of the binaries.
-      OS X FUSE uses a kernel extension that needs to be compatible with the
+      macFUSE uses a kernel extension that needs to be compatible with the
       code contained in the binary.
   * 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:
 
@@ -429,18 +438,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?
 ----------------------------------------------
@@ -564,8 +574,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::
 
@@ -727,7 +736,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,6 +748,15 @@ the nonce is deleted or if you suspect it may have been tampered with. See :ref:
 Common issues
 #############
 
+/path/to/repo is not a valid repository. Check repo config.
+-----------------------------------------------------------
+
+There can be many causes of this error. E.g. you have incorrectly specified the repository path.
+
+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.
+We recommend upgrading to the latest stable version and trying again. We are sorry. We should have thought abount forward
+compatibility and implemented a more helpful error message.
+
 Why does Borg extract hang after some time?
 -------------------------------------------
 
@@ -863,6 +881,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 +957,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 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 expose the host CPU's 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 +1049,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
@@ -1178,10 +1224,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/osxfuse/osxfuse/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?
 -----------------------------------------------------------
 

docs/installation.rst

@@ -65,7 +65,7 @@ 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
 .. _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 /
@@ -266,7 +266,7 @@ 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.
+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::
@@ -326,6 +326,8 @@ Use the Cygwin installer to install the dependencies::
 Using pip
 ~~~~~~~~~
 
+Ensure to install the dependencies as described within :ref:`source-install`.
+
 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.
@@ -358,11 +360,26 @@ 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
 ~~~~~~~~~
 
+Ensure to install the dependencies as described within :ref:`source-install`.
+
 This uses latest, unreleased development code from git.
 While we try not to break master, there are no guarantees on anything.
 
@@ -372,7 +389,7 @@ While we try not to break master, there are no guarantees on anything.
     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

docs/internals/data-structures.rst

@@ -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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -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

docs/internals/frontends.rst

@@ -10,7 +10,7 @@ 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
 as needed and parse JSON output from borg.
 
@@ -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``::
 
@@ -632,6 +637,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

@@ -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/man/borg-benchmark-crud.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-BENCHMARK-CRUD" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CRUD" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .SH SYNOPSIS

docs/man/borg-benchmark.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-BENCHMARK" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-BENCHMARK" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-benchmark \- benchmark command
 .SH SYNOPSIS

docs/man/borg-break-lock.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-BREAK-LOCK" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-BREAK-LOCK" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .SH SYNOPSIS

docs/man/borg-check.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-CHECK" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-CHECK" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .SH SYNOPSIS
@@ -35,91 +35,123 @@ borg-check \- Check repository consistency
 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 excepts
+archive checks for the same reason. Therefore partial checks may be useful with
+very large repositories only where a full check would take too long.
+.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 can
+not use \fB\-\-verify\-data\fP with \fB\-\-repository\-only\fP\&.
+.SS About repair mode
+.sp
+The check command is a readonly task by default. If any corruption is found,
+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 +161,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 +186,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

docs/man/borg-common.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-COMMON" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-COMMON" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .SH SYNOPSIS
@@ -79,7 +79,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 +97,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)

docs/man/borg-compact.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-COMPACT" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-COMPACT" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-compact \- compact segment files in the repository
 .SH SYNOPSIS
@@ -53,7 +53,8 @@ When using \fB\-\-verbose\fP, borg will output an estimate of the freed space.
 .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
-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,7 +66,7 @@ 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  \-\-cleanup\-commits

docs/man/borg-compression.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-COMPRESSION" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-COMPRESSION" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .SH DESCRIPTION
@@ -53,20 +53,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,35 +76,76 @@ 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.
 .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
+.nf
+.ft C
+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
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Example probabilities for SPEC \fB1\fP:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+90   %  0.01 ..   0.1
+ 9   %  0.1  ..   1
+ 0.9 %  1    ..  10
+ 0.09% 10    .. 100
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fIRandomly sized padding up to the given size\fP (additive)
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+110: 1kiB (2 ^ (SPEC \- 100))
 \&...
 120: 1MiB
 \&...
 123: 8MiB (max.)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .UNINDENT
 .sp
 Examples:
@@ -120,7 +161,7 @@ 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

docs/man/borg-config.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-CONFIG" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-CONFIG" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-config \- get, set, and delete values in a repository or cache config file
 .SH SYNOPSIS
@@ -41,8 +41,8 @@ For security reasons, this command only works on local repositories.
 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
 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 +62,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

docs/man/borg-create.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-CREATE" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-CREATE" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .SH SYNOPSIS
@@ -112,8 +112,8 @@ The \fB\-\-progress\fP option shows (from left to right) Original, Compressed an
 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 +132,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 +169,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
@@ -208,7 +208,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
@@ -265,7 +265,7 @@ 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
@@ -273,7 +273,7 @@ select compression algorithm, see the output of the "borg help compression" comm
 .sp
 .nf
 .ft C
-# Backup ~/Documents into an archive named "my\-documents"
+# Backup ~/Documents into an archive named \(dqmy\-documents\(dq
 $ borg create /path/to/repo::my\-documents ~/Documents
 
 # same, but list all files as we process them
@@ -288,17 +288,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 +341,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,7 +352,7 @@ $ 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
 .fi
@@ -376,13 +376,13 @@ through using the \fB\-\-keep\-exclude\-tags\fP option.
 The \fB\-x\fP or \fB\-\-one\-file\-system\fP option excludes directories, that are mountpoints (and everything in them).
 It detects mountpoints 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 number 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 a mountpoint and also the other way around.
-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 mountpoint) 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 (different device number from parent but not necessarily a mountpoint).
-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 +395,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

docs/man/borg-delete.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-DELETE" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-DELETE" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .SH SYNOPSIS
@@ -48,15 +48,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 +71,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 +94,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
@@ -126,10 +127,10 @@ $ 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

docs/man/borg-diff.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-DIFF" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-DIFF" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .SH SYNOPSIS
@@ -66,7 +66,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
@@ -81,10 +81,13 @@ Override check of chunker parameters.
 .B  \-\-sort
 Sort the output lines by file path.
 .TP
+.B  \-\-content\-only
+Only compare differences in content (exclude metadata differences)
+.TP
 .B  \-\-json\-lines
 Format output as JSON Lines.
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
@@ -114,10 +117,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,10 +142,10 @@ 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
 .UNINDENT

docs/man/borg-export-tar.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-EXPORT-TAR" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-EXPORT-TAR" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .SH SYNOPSIS
@@ -50,7 +50,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
@@ -86,12 +86,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 +100,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
@@ -131,14 +131,14 @@ $ borg export\-tar /path/to/repo::Monday Monday.tar
 $ borg export\-tar /path/to/repo::Monday Monday.tar.gz \-\-exclude \(aq*.so\(aq
 
 # use 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,
 # 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
 .fi
 .UNINDENT

docs/man/borg-extract.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-EXTRACT" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-EXTRACT" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .SH SYNOPSIS
@@ -52,7 +52,7 @@ pass over the archive metadata.
 \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
@@ -72,7 +72,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 +105,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
@@ -138,10 +138,10 @@ $ 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
 
 # Restore a raw device (must not be active/in use/mounted at that time)

docs/man/borg-import-tar.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-IMPORT-TAR" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-IMPORT-TAR" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-import-tar \- Create a backup archive from a tarball
 .SH SYNOPSIS
@@ -49,7 +49,7 @@ 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
@@ -70,6 +70,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 +84,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 +103,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,7 +123,7 @@ 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

docs/man/borg-info.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-INFO" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-INFO" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .SH SYNOPSIS
@@ -38,7 +38,7 @@ 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:
 .sp
 This archive / deduplicated size = amount of data stored ONLY for this archive
@@ -59,7 +59,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 +69,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

docs/man/borg-init.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-INIT" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-INIT" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .SH SYNOPSIS
@@ -82,7 +82,7 @@ This is why it is essential to use a secure passphrase.
 Encrypt and sign your backups to prevent anyone from reading or forging them unless they
 have the key and know the passphrase. Make sure to keep a backup of
 your key \fBoutside\fP the repository \- do not lock yourself out by
-"leaving your keys inside your car" (see \fIborg_key_export\fP).
+\(dqleaving your keys inside your car\(dq (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
@@ -119,11 +119,13 @@ Only use \fB\-\-encryption none\fP if you are OK with anyone who has access to
 your repository being able to read your backups and tamper with their
 contents without you noticing.
 .sp
-If you want "passphrase and having\-the\-key" security, use \fB\-\-encryption keyfile\fP\&.
+If you want \(dqpassphrase and having\-the\-key\(dq security, use \fB\-\-encryption keyfile\fP\&.
 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\&.
+To normally work with \fBauthenticated\fP repos, you will need the passphrase, but
+there is an emergency workaround, see \fBBORG_WORKAROUNDS=authenticated_no_key\fP docs.
 .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
@@ -223,7 +225,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

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

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-key-change-passphrase \- Change repository key file passphrase
 .SH SYNOPSIS
@@ -56,11 +56,11 @@ REPOSITORY
 .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.
@@ -90,9 +90,9 @@ Fully automated using environment variables:
 .nf
 .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
 .fi
 .UNINDENT

docs/man/borg-key-export.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY-EXPORT" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-KEY-EXPORT" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .SH SYNOPSIS
@@ -85,7 +85,7 @@ REPOSITORY
 .B PATH
 where to store the backup
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-paper

docs/man/borg-key-import.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY-IMPORT" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-KEY-IMPORT" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .SH SYNOPSIS
@@ -60,7 +60,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

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

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
 .SH SYNOPSIS

docs/man/borg-key.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-KEY" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-key \- Manage a keyfile or repokey of a repository
 .SH SYNOPSIS

docs/man/borg-list.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-LIST" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-LIST" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .SH SYNOPSIS
@@ -50,7 +50,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 +60,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 +86,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
@@ -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,11 +137,11 @@ 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
 \&...
@@ -207,7 +207,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 +217,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,9 +311,9 @@ 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

docs/man/borg-mount.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-MOUNT" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-MOUNT" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
@@ -69,16 +69,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.
 .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
@@ -107,7 +107,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 +129,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 +143,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

docs/man/borg-patterns.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-PATTERNS" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-PATTERNS" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .SH DESCRIPTION
@@ -36,36 +36,20 @@ The path/filenames used as input for the pattern matching start from 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
+Starting with Borg 1.2, paths that are matched against patterns always
-will look like \fIrelative/.../file.ext\fP\&. When you give \fI/absolute/\fP as
+appear relative. If you give \fB/absolute/\fP as root, the paths going
-root, they will look like \fI/absolute/.../file.ext\fP\&.
+into the matcher will start with \fBabsolute/\fP\&.
-.sp
+If you give \fB\&../../relative\fP as root, the paths will be normalized
-File paths in Borg archives are always stored normalized and relative.
+as \fBrelative/\fP\&.
-This means that e.g. \fBborg create /path/to/repo ../some/path\fP will
-store all files as \fIsome/path/.../file.ext\fP and \fBborg create
-/path/to/repo /home/user\fP will store all files as
-\fIhome/user/.../file.ext\fP\&.
 .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
-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
@@ -159,26 +143,26 @@ $ 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
+$ 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
@@ -188,12 +172,37 @@ $ borg create \-\-exclude\-from exclude.txt backup /
 .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
+To change the default pattern style, use the \fBP\fP prefix, followed by
+the pattern style abbreviation (\fBfm\fP, \fBpf\fP, \fBpp\fP, \fBre\fP, \fBsh\fP).
+All patterns following this line will use this style until another style
+is specified.
+.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
 .INDENT 0.0
@@ -204,11 +213,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
+Example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# 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.
+\- **
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .sp
 \fBNOTE:\fP
 .INDENT 0.0
@@ -250,22 +285,22 @@ The patterns.lst file could look like that:
 .sp
 .nf
 .ft C
-# "sh:" pattern style is the default, so the following line is not needed:
+# \(dqsh:\(dq 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
 .fi
 .UNINDENT
@@ -278,7 +313,7 @@ You can specify recursion roots either on the command line or in a patternfile:
 .nf
 .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
 .fi
@@ -297,7 +332,7 @@ P fm
 R /home/bobby
 R /home/susan
 
-\- /home/bobby/junk
+\- home/bobby/junk
 .ft P
 .fi
 .UNINDENT

docs/man/borg-placeholders.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-PLACEHOLDERS" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-PLACEHOLDERS" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-placeholders \- Details regarding placeholders
 .SH DESCRIPTION
@@ -92,7 +92,7 @@ Examples:
 .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
 .fi
 .UNINDENT

docs/man/borg-prune.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-PRUNE" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-PRUNE" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .SH SYNOPSIS
@@ -61,10 +61,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.
@@ -85,9 +85,9 @@ keep the last N archives under the assumption that you do not create more than o
 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 +97,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
@@ -138,15 +138,18 @@ 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
@@ -154,9 +157,9 @@ Be careful, prune is a potentially dangerous command, it will remove backup
 archives.
 .sp
 The default of prune is to apply to \fBall archives in the repository\fP unless
-you restrict its operation to a subset of the archives using \fB\-\-prefix\fP\&.
+you 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".
+e.g. 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.
@@ -170,8 +173,8 @@ first so you will see what it would do without it actually doing 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:
 $ borg compact /path/to/repo
 

docs/man/borg-recreate.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-RECREATE" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-RECREATE" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .SH SYNOPSIS
@@ -43,7 +43,7 @@ recreate is a potentially dangerous function and might lead to data loss
 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
@@ -67,7 +67,7 @@ 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.
 .sp
@@ -97,7 +97,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 +112,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
@@ -152,13 +152,13 @@ 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
@@ -182,13 +182,13 @@ $ borg recreate /mnt/backup::archive \-\-recompress \-\-compression zlib,9
 $ borg recreate /mnt/backup \-\-exclude home/icke/Pictures/drunk_photos
 
 # Change 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: ...

docs/man/borg-rename.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-RENAME" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-RENAME" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-rename \- Rename an existing archive
 .SH SYNOPSIS

docs/man/borg-serve.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-SERVE" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-SERVE" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .SH SYNOPSIS
@@ -39,7 +39,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
@@ -83,11 +83,11 @@ locations like \fB/etc/environment\fP or in the forced command itself (example b
 # Use key options to disable unneeded and potentially dangerous SSH functionality.
 # This will help to 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 \(dqborg serve\(dq side
 $ cat ~/.ssh/authorized_keys
-command="export BORG_XXX=value; borg serve [...]",restrict ssh\-rsa [...]
+command=\(dqexport BORG_XXX=value; borg serve [...]\(dq,restrict ssh\-rsa [...]
 .ft P
 .fi
 .UNINDENT

docs/man/borg-umount.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-UMOUNT" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-UMOUNT" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .SH SYNOPSIS
@@ -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
 

docs/man/borg-upgrade.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-UPGRADE" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-UPGRADE" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-upgrade \- upgrade a repository from a previous version
 .SH SYNOPSIS
@@ -53,6 +53,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 version 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
@@ -131,7 +148,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
@@ -148,6 +165,9 @@ Enable manifest authentication (in key and cache) (Borg 1.0.9 and later).
 .TP
 .B  \-\-disable\-tam
 Disable manifest authentication (in key and cache).
+.TP
+.B  \-\-archives\-tam
+add TAM authentication for all archives.
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0
@@ -170,11 +190,11 @@ no key file found for repository
 .UNINDENT
 .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).
 .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, 2 steps
 are needed, in this order:
 .INDENT 0.0
 .IP \(bu 2

docs/man/borg-with-lock.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-WITH-LOCK" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG-WITH-LOCK" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .SH SYNOPSIS
@@ -47,7 +47,7 @@ code as borg\(aqs return code.
 .INDENT 3.5
 If you copy a repository with the lock held, the lock will be present in
 the copy. Thus, before using borg on the copy from a different host,
-you need to use "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

docs/man/borg.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORG" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borg \- deduplicating and encrypting backup tool
 .SH SYNOPSIS
@@ -162,7 +162,7 @@ $ borg extract /path/to/repo::Monday
 .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
@@ -173,6 +173,18 @@ $ borg delete /path/to/repo::Monday
 .fi
 .UNINDENT
 .UNINDENT
+.IP 8. 3
+Recover disk space by compacting the segment files in the repo:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg compact /path/to/repo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .UNINDENT
 .sp
 \fBNOTE:\fP
@@ -413,7 +425,7 @@ 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_HOST_ID
 Borg usually computes a host id from the FQDN plus the results of \fBuuid.getnode()\fP (which usually returns
@@ -433,7 +445,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,7 +454,7 @@ 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
@@ -495,23 +507,63 @@ 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
+.nf
+.ft C
+BORG_WORKAROUNDS=authenticated_no_key borg extract repo::archive
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+After you have extracted all data you need, you MUST delete the repository:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+BORG_WORKAROUNDS=authenticated_no_key borg delete repo
+.ft P
+.fi
+.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
@@ -544,15 +596,32 @@ 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
@@ -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
@@ -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.
@@ -809,7 +874,7 @@ Yes [1]
 T}
 _
 T{
-Mac OS X
+macOS
 T}	T{
 Yes
 T}	T{
@@ -875,7 +940,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

docs/man/borgfs.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORGFS" 1 "2022-02-19" "" "borg backup tool"
+.TH "BORGFS" 1 "2023-12-02" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
@@ -69,16 +69,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.
 .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
@@ -107,7 +107,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 +132,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 +146,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

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/quickstart.rst

@@ -26,6 +26,8 @@ repositories contain data blocks and a manifest tracking which blocks are in eac
 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
 -------------------------------
 
@@ -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=$?
 

docs/usage/check.rst.inc

@@ -12,41 +12,41 @@ borg check
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                     |
+    | **positional arguments**                                                                                                                                                                                                                                |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to check consistency of                                                                                                          |
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to check consistency of                                                                                     |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                       |
+    | **options**                                                                                                                                                                                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--repository-only``                 | only perform repository checks                                                                                                                         |
+    |                                                                             | ``--repository-only``                 | only perform repository checks                                                                                                    |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--archives-only``                   | only perform archives checks                                                                                                                           |
+    |                                                                             | ``--archives-only``                   | only perform archives checks                                                                                                      |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--verify-data``                     | perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)                                                       |
+    |                                                                             | ``--verify-data``                     | perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)                                  |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--repair``                          | attempt to repair any inconsistencies found                                                                                                            |
+    |                                                                             | ``--repair``                          | attempt to repair any inconsistencies found                                                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--save-space``                      | work slower, but using less space                                                                                                                      |
+    |                                                                             | ``--save-space``                      | work slower, but using less space                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--max-duration SECONDS``            | do only a partial repo check for max. SECONDS seconds (Default: unlimited)                                                                             |
+    |                                                                             | ``--max-duration SECONDS``            | do only a partial repo check for max. SECONDS seconds (Default: unlimited)                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                               |
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                          |
-    |                                                                                                                                                                                                                                                                              |
+    |                                                                                                                                                                                                                                                         |
-    | :ref:`common_options`                                                                                                                                                                                                                                                        |
+    | :ref:`common_options`                                                                                                                                                                                                                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                  |
+    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix.                                                                                                 |
+    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix. (deprecated)                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see "borg help patterns". |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp                                                       |
+    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                                                                             |
+    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                                                              |
+    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -62,7 +62,7 @@ borg check
         repository or archive to check consistency of
 
 
-    optional arguments
+    options
         --repository-only    only perform repository checks
         --archives-only    only perform archives checks
         --verify-data     perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)
@@ -75,9 +75,9 @@ borg check
         |
 
     Archive filters
-        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix.
+        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix. (deprecated)
-        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see "borg help patterns".
-        --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+        --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp
         --first N                         consider first N archives after other filters were applied
         --last N                          consider last N archives after other filters were applied
 
@@ -85,72 +85,115 @@ borg check
 Description
 ~~~~~~~~~~~
 
-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:
 
-check --repair is a potentially dangerous function and might lead to data loss
+1. Checking the consistency of the repository itself. This includes checking
-(for kinds of corruption it is not capable of dealing with). BE VERY CAREFUL!
+   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 ``--max-duration``.
+   When checking a remote repository, please note that the checks run on the
+   server and do not cause significant network traffic.
+
+2. Checking consistency and correctness of the archive metadata and optionally
+   archive data (requires ``--verify-data``). 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 ``--verify-data``, 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.
+
+Both steps can also be run independently. Pass ``--repository-only`` to run the
+repository checks only, or pass ``--archives-only`` to run the archive checks
+only.
+
+The ``--max-duration`` option can be used to split a long-running repository
+check into multiple partial checks. After the given number of seconds the check
+is interrupted. The next partial check will continue where the previous one
+stopped, until the full repository has been checked. Assuming a complete check
+would take 7 hours, then running a daily check with ``--max-duration=3600``
+(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
+``--max-duration`` you must also pass ``--repository-only``, and must not pass
+``--archives-only``, nor ``--repair``.
+
+**Warning:** Please note that partial repository checks (i.e. running it with
+``--max-duration``) can only perform non-cryptographic checksum checks on the
+segment files. A full repository check (i.e. without ``--max-duration``) can
+also do a repository index check. Enabling partial repository checks excepts
+archive checks for the same reason. Therefore partial checks may be useful with
+very large repositories only where a full check would take too long.
+
+The ``--verify-data`` 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 can
+not use ``--verify-data`` with ``--repository-only``.
+
+About repair mode
++++++++++++++++++
+
+The check command is a readonly task by default. If any corruption is found,
+Borg will report the issue and proceed with checking. To actually repair the
+issues found, pass ``--repair``.
+
+.. note::
+
+    ``--repair`` is a **POTENTIALLY DANGEROUS FEATURE** 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. **BE VERY CAREFUL!**
 
 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.
 
-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 ``--repair``).
 
-- For all segments, the segment magic header is checked.
+Repair mode will attempt to fix any corruptions found. Fixing corruptions does
-- For all objects stored in the segments, all metadata (e.g. CRC and size) and
+not mean recovering lost data: Borg can not magically restore data lost due to
-  all data is read. The read data is checked by size and CRC. Bit rot and other
+e.g. a hardware failure. Repairing a repository means sacrificing some data
-  types of accidental damage can be detected this way.
+for the sake of the repository as a whole and the remaining data. Hence it is,
-- In repair mode, if an integrity error is detected in a segment, try to recover
+by definition, a potentially lossy task.
-  as many objects from the segment as possible.
-- In repair mode, make sure that the index is consistent with the data stored in
-  the segments.
-- If checking a remote repo via ``ssh:``, the repo check is executed on the server
-  without causing significant network traffic.
-- The repository check can be skipped using the ``--archives-only`` option.
-- A repository check can be time consuming. Partial checks are possible with the
-  ``--max-duration`` option.
 
-Second, the consistency and correctness of the archive metadata is verified:
+In practice, repair mode hooks into both the repository and archive checks:
 
-- Is the repo manifest present? If not, it is rebuilt from archive metadata
+1. When checking the repository's consistency, repair mode will try to recover
-  chunks (this requires reading and decrypting of all metadata and data).
+   as many objects from segments with integrity errors as possible, and ensure
-- Check if archive metadata chunk is present; if not, remove archive from manifest.
+   that the index is consistent with the data stored in the segments.
-- 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.
-- 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.
-- In verify-data mode, a complete cryptographic verification of the archive data
-  integrity is performed. This conflicts with ``--repository-only`` as this mode
-  only makes sense if the archive checks are enabled. The full details of this mode
-  are documented below.
-- If checking a remote repo via ``ssh:``, 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.
-- The archive checks can be time consuming; they can be skipped using the
-  ``--repository-only`` option.
 
-The ``--max-duration`` option can be used to split a long-running repository check
+2. When checking the consistency and correctness of archives, repair mode might
-into multiple partial checks. After the given number of seconds the check is
+   remove whole archives from the manifest if their archive metadata chunk is
-interrupted. The next partial check will continue where the previous one stopped,
+   corrupt or lost. On a chunk level (i.e. the contents of files), repair mode
-until the complete repository has been checked. Example: Assuming a full check took 7
+   will replace corrupt or lost chunks with a same-size replacement chunk of
-hours, then running a daily check with --max-duration=3600 (1 hour) resulted in one
+   zeroes. If a previously zeroed chunk reappears, repair mode will restore
-full check per week.
+   this lost chunk using the new chunk. Lastly, repair mode will also delete
+   orphaned chunks (e.g. caused by read errors while creating the archive).
 
-Attention: Partial checks can only do way less checking than a full check (only the
+Most steps taken by repair mode have a one-time effect on the repository, like
-CRC32 checks on segment file entries are done), and cannot be combined with the
+removing a lost archive from the repository. However, replacing a corrupt or
-``--repair`` option. Partial checks may therefore be useful only with very large
+lost chunk with an all-zero replacement will have an ongoing effect on the
-repositories where a full check took too long. Doing a full repository check aborts a
+repository: When attempting to extract a file referencing an all-zero chunk,
-partial check; the next partial check will restart from the beginning.
+the ``extract`` command will distinctly warn about it. The FUSE filesystem
+created by the ``mount`` command will reject reading such a "zero-patched"
+file unless a special mount option is given.
 
-The ``--verify-data`` option will perform a full integrity verification (as opposed to
+As mentioned earlier, Borg might be able to "heal" a "zero-patched" file in
-checking the CRC32 of the segment) of data, which means reading the data from the
+repair mode, if all its previously lost chunks reappear (e.g. via a later
-repository, decrypting and decompressing it. This is a cryptographic verification,
+backup). This is achieved by Borg not only keeping track of the all-zero
-which will detect (accidental) corruption. For encrypted repositories it is
+replacement chunks, but also by keeping metadata about the lost chunks. In
-tamper-resistant as well, unless the attacker has access to the keys. It is also very
+repair mode Borg will check whether a previously lost chunk reappeared and will
-slow.
+replace the all-zero replacement chunk by the reappeared chunk. If all lost
+chunks of a "zero-patched" file reappear, this effectively "heals" the file.
+Consequently, if lost chunks were repaired earlier, it is advised to run
+``--repair`` a second time after creating some new backups.

docs/usage/compact.rst.inc

@@ -17,7 +17,7 @@ borg compact
     +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
     |                                                       | ``REPOSITORY``          | repository to compact                                          |
     +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
-    | **optional arguments**                                                                                                                           |
+    | **options**                                                                                                                                      |
     +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
     |                                                       | ``--cleanup-commits``   | cleanup commit-only 17-byte segment files                      |
     +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
@@ -42,7 +42,7 @@ borg compact
         repository to compact
 
 
-    optional arguments
+    options
         --cleanup-commits       cleanup commit-only 17-byte segment files
         --threshold PERCENT     set minimum threshold for saved space in PERCENT (Default: 10)
 
@@ -71,6 +71,7 @@ When using ``--verbose``, borg will output an estimate of the freed space.
 
 After upgrading borg (server) to 1.2+, you can use ``borg compact --cleanup-commits``
 to clean up the numerous 17byte 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.
 
 See :ref:`separate_compaction` in Additional Notes for more details.

docs/usage/config.rst.inc

@@ -21,7 +21,7 @@ borg config
     +-------------------------------------------------------+----------------------+----------------------------------------+
     |                                                       | ``VALUE``            | new value for key                      |
     +-------------------------------------------------------+----------------------+----------------------------------------+
-    | **optional arguments**                                                                                                |
+    | **options**                                                                                                           |
     +-------------------------------------------------------+----------------------+----------------------------------------+
     |                                                       | ``-c``, ``--cache``  | get and set values from the repo cache |
     +-------------------------------------------------------+----------------------+----------------------------------------+
@@ -52,7 +52,7 @@ borg config
         new value for key
 
 
-    optional arguments
+    options
         -c, --cache    get and set values from the repo cache
         -d, --delete    delete the key from the config file
         -l, --list     list the configuration of the repo

docs/usage/create.rst

@@ -19,7 +19,7 @@ Examples
     # 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 \
-        --exclude 'sh:/home/*/.thumbnails'
+        --exclude 'sh:home/*/.thumbnails'
 
     # Backup the root filesystem into an archive named "root-YYYY-MM-DD"
     # use zlib compression (good, but slow) - default is lz4 (fast, low compression ratio)

docs/usage/create.rst.inc

@@ -12,107 +12,107 @@ borg create
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                         |
+    | **positional arguments**                                                                                                                                                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``ARCHIVE``                                       | name of archive to create (must be also a valid directory name)                                                                                      |
+    |                                                       | ``ARCHIVE``                                       | name of archive to create (must be also a valid directory name)                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``PATH``                                          | paths to archive                                                                                                                                     |
+    |                                                       | ``PATH``                                          | paths to archive                                                                                                                                                  |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                           |
+    | **options**                                                                                                                                                                                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-n``, ``--dry-run``                             | do not create a backup archive                                                                                                                       |
+    |                                                       | ``-n``, ``--dry-run``                             | do not create a backup archive                                                                                                                                    |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-s``, ``--stats``                               | print statistics for the created archive                                                                                                             |
+    |                                                       | ``-s``, ``--stats``                               | print statistics for the created archive                                                                                                                          |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--list``                                        | output verbose list of items (files, dirs, ...)                                                                                                      |
+    |                                                       | ``--list``                                        | output verbose list of items (files, dirs, ...)                                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--filter STATUSCHARS``                          | only display items with the given status characters (see description)                                                                                |
+    |                                                       | ``--filter STATUSCHARS``                          | only display items with the given status characters (see description)                                                                                             |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--json``                                        | output stats as JSON. Implies ``--stats``.                                                                                                           |
+    |                                                       | ``--json``                                        | output stats as JSON. Implies ``--stats``.                                                                                                                        |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--no-cache-sync``                               | experimental: do not synchronize the cache. Implies not using the files cache.                                                                       |
+    |                                                       | ``--no-cache-sync``                               | experimental: do not synchronize the cache. Implies not using the files cache.                                                                                    |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdin-name NAME``                             | use NAME in archive for stdin data (default: 'stdin')                                                                                                |
+    |                                                       | ``--stdin-name NAME``                             | use NAME in archive for stdin data (default: 'stdin')                                                                                                             |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdin-user USER``                             | set user USER in archive for stdin data (default: 'root')                                                                                            |
+    |                                                       | ``--stdin-user USER``                             | set user USER in archive for stdin data (default: 'root')                                                                                                         |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdin-group GROUP``                           | set group GROUP in archive for stdin data (default: 'wheel')                                                                                         |
+    |                                                       | ``--stdin-group GROUP``                           | set group GROUP in archive for stdin data (default: 'wheel')                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdin-mode M``                                | set mode to M in archive for stdin data (default: 0660)                                                                                              |
+    |                                                       | ``--stdin-mode M``                                | set mode to M in archive for stdin data (default: 0660)                                                                                                           |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--content-from-command``                        | interpret PATH as command and store its stdout. See also section Reading from stdin below.                                                           |
+    |                                                       | ``--content-from-command``                        | interpret PATH as command and store its stdout. See also section Reading from stdin below.                                                                        |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--paths-from-stdin``                            | read DELIM-separated list of paths to backup from stdin. Will not recurse into directories.                                                          |
+    |                                                       | ``--paths-from-stdin``                            | 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.                             |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--paths-from-command``                          | interpret PATH as command and treat its output as ``--paths-from-stdin``                                                                             |
+    |                                                       | ``--paths-from-command``                          | interpret PATH as command and treat its output as ``--paths-from-stdin``                                                                                          |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--paths-delimiter DELIM``                       | set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: \n)                                                             |
+    |                                                       | ``--paths-delimiter DELIM``                       | set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``)                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                   |
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                |
-    |                                                                                                                                                                                                                                                                  |
+    |                                                                                                                                                                                                                                                                               |
-    | :ref:`common_options`                                                                                                                                                                                                                                            |
+    | :ref:`common_options`                                                                                                                                                                                                                                                         |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                                                                            |
+    | **Include/Exclude options**                                                                                                                                                                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-e PATTERN``, ``--exclude PATTERN``             | exclude paths matching PATTERN                                                                                                                       |
+    |                                                       | ``-e PATTERN``, ``--exclude PATTERN``             | exclude paths matching PATTERN                                                                                                                                    |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-from EXCLUDEFILE``                    | read exclude patterns from EXCLUDEFILE, one per line                                                                                                 |
+    |                                                       | ``--exclude-from EXCLUDEFILE``                    | read exclude patterns from EXCLUDEFILE, one per line                                                                                                              |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                             | include/exclude paths matching PATTERN                                                                                                               |
+    |                                                       | ``--pattern PATTERN``                             | include/exclude paths matching PATTERN                                                                                                                            |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``                   | read include/exclude patterns from PATTERNFILE, one per line                                                                                         |
+    |                                                       | ``--patterns-from PATTERNFILE``                   | read include/exclude patterns from PATTERNFILE, one per line                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                      |
+    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-if-present NAME``                     | exclude directories that are tagged by containing a filesystem object with the given NAME                                                            |
+    |                                                       | ``--exclude-if-present NAME``                     | exclude directories that are tagged by containing a filesystem object with the given NAME                                                                         |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--keep-exclude-tags``                           | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                            |
+    |                                                       | ``--keep-exclude-tags``                           | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                                         |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-nodump``                              | exclude files flagged NODUMP                                                                                                                         |
+    |                                                       | ``--exclude-nodump``                              | exclude files flagged NODUMP                                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Filesystem options**                                                                                                                                                                                                                                           |
+    | **Filesystem options**                                                                                                                                                                                                                                                        |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-x``, ``--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. |
+    |                                                       | ``-x``, ``--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 description below. |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--numeric-owner``                               | deprecated, use ``--numeric-ids`` instead                                                                                                            |
+    |                                                       | ``--numeric-owner``                               | deprecated, use ``--numeric-ids`` instead                                                                                                                         |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--numeric-ids``                                 | only store numeric user and group identifiers                                                                                                        |
+    |                                                       | ``--numeric-ids``                                 | only store numeric user and group identifiers                                                                                                                     |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--noatime``                                     | do not store atime into archive                                                                                                                      |
+    |                                                       | ``--noatime``                                     | do not store atime into archive                                                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--atime``                                       | do store atime into archive                                                                                                                          |
+    |                                                       | ``--atime``                                       | do store atime into archive                                                                                                                                       |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--noctime``                                     | do not store ctime into archive                                                                                                                      |
+    |                                                       | ``--noctime``                                     | do not store ctime into archive                                                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--nobirthtime``                                 | do not store birthtime (creation date) into archive                                                                                                  |
+    |                                                       | ``--nobirthtime``                                 | do not store birthtime (creation date) into archive                                                                                                               |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--nobsdflags``                                  | deprecated, use ``--noflags`` instead                                                                                                                |
+    |                                                       | ``--nobsdflags``                                  | deprecated, use ``--noflags`` instead                                                                                                                             |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--noflags``                                     | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive                                                                                    |
+    |                                                       | ``--noflags``                                     | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive                                                                                                 |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--noacls``                                      | do not read and store ACLs into archive                                                                                                              |
+    |                                                       | ``--noacls``                                      | do not read and store ACLs into archive                                                                                                                           |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--noxattrs``                                    | do not read and store xattrs into archive                                                                                                            |
+    |                                                       | ``--noxattrs``                                    | do not read and store xattrs into archive                                                                                                                         |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--sparse``                                      | detect sparse holes in input (supported only by fixed chunker)                                                                                       |
+    |                                                       | ``--sparse``                                      | detect sparse holes in input (supported only by fixed chunker)                                                                                                    |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--files-cache MODE``                            | operate files cache in MODE. default: ctime,size,inode                                                                                               |
+    |                                                       | ``--files-cache MODE``                            | operate files cache in MODE. default: ctime,size,inode                                                                                                            |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--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.    |
+    |                                                       | ``--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.                 |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Archive options**                                                                                                                                                                                                                                              |
+    | **Archive options**                                                                                                                                                                                                                                                           |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--comment COMMENT``                             | add a comment text to the archive                                                                                                                    |
+    |                                                       | ``--comment COMMENT``                             | add a comment text to the archive                                                                                                                                 |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--timestamp TIMESTAMP``                         | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory.                   |
+    |                                                       | ``--timestamp TIMESTAMP``                         | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory.                                |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                               |
+    |                                                       | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                                            |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095                |
+    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095                             |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details.                                                     |
+    |                                                       | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details.                                                                  |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -130,7 +130,7 @@ borg create
         paths to archive
 
 
-    optional arguments
+    options
         -n, --dry-run    do not create a backup archive
         -s, --stats     print statistics for the created archive
         --list          output verbose list of items (files, dirs, ...)
@@ -142,15 +142,15 @@ borg create
         --stdin-group GROUP    set group GROUP in archive for stdin data (default: 'wheel')
         --stdin-mode M    set mode to M in archive for stdin data (default: 0660)
         --content-from-command    interpret PATH as command and store its stdout. See also section Reading from stdin below.
-        --paths-from-stdin    read DELIM-separated list of paths to backup from stdin. Will not recurse into directories.
+        --paths-from-stdin    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.
         --paths-from-command    interpret PATH as command and treat its output as ``--paths-from-stdin``
-        --paths-delimiter DELIM    set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: \n) 
+        --paths-delimiter DELIM    set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``)
 
 
     :ref:`common_options`
         |
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN
@@ -162,7 +162,7 @@ borg create
 
 
     Filesystem options
-        -x, --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.
+        -x, --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 description below.
         --numeric-owner           deprecated, use ``--numeric-ids`` instead
         --numeric-ids             only store numeric user and group identifiers
         --noatime                 do not store atime into archive
@@ -282,13 +282,13 @@ through using the ``--keep-exclude-tags`` option.
 The ``-x`` or ``--one-file-system`` option excludes directories, that are mountpoints (and everything in them).
 It detects mountpoints by comparing the device number from the output of ``stat()`` of the directory and its
 parent directory. Specifically, it excludes directories for which ``stat()`` 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 number 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 a mountpoint and also the other way around.
-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 mountpoint) and ALL
-using ``--one-file-system``, one should make doubly sure that the backup works as intended especially when using
+subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint).
-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 ``--one-file-system``, you should double-check that the backup works as intended.
 
 
 .. _list_item_flags:

docs/usage/delete.rst

@@ -10,7 +10,7 @@ Examples
     $ borg compact /path/to/repo
 
     # delete all archives whose names begin with the machine's hostname followed by "-"
-    $ borg delete --prefix '{hostname}-' /path/to/repo
+    $ borg delete --glob-archives '{hostname}-*' /path/to/repo
 
     # delete all archives whose names contain "-2012-"
     $ borg delete --glob-archives '*-2012-*' /path/to/repo

docs/usage/delete.rst.inc

@@ -12,45 +12,47 @@ borg delete
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                     |
+    | **positional arguments**                                                                                                                                                                                                                                            |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to delete                                                                                                                        |
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``                         | repository or archive to delete                                                                                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``ARCHIVE``                           | archives to delete                                                                                                                                     |
+    |                                                                             | ``ARCHIVE``                                       | archives to delete                                                                                                                |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                       |
+    | **options**                                                                                                                                                                                                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-n``, ``--dry-run``                 | do not change repository                                                                                                                               |
+    |                                                                             | ``-n``, ``--dry-run``                             | do not change repository                                                                                                          |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--list``                            | output verbose list of archives                                                                                                                        |
+    |                                                                             | ``--list``                                        | output verbose list of archives                                                                                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-s``, ``--stats``                   | print statistics for the deleted archive                                                                                                               |
+    |                                                                             | ``-s``, ``--stats``                               | print statistics for the deleted archive                                                                                          |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--cache-only``                      | delete only the local cache for the given repository                                                                                                   |
+    |                                                                             | ``--cache-only``                                  | delete only the local cache for the given repository                                                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--force``                           | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.                                                       |
+    |                                                                             | ``--force``                                       | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.                                  |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--keep-security-info``              | keep the local security info when deleting a repository                                                                                                |
+    |                                                                             | ``--keep-security-info``                          | keep the local security info when deleting a repository                                                                           |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--save-space``                      | work slower, but using less space                                                                                                                      |
+    |                                                                             | ``--save-space``                                  | work slower, but using less space                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                               |
+    |                                                                             | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                            |
-    |                                                                                                                                                                                                                                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | :ref:`common_options`                                                                                                                                                                                                                                                        |
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                      |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                                                                                                                                                                                                                     |
-    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                  |
+    | :ref:`common_options`                                                                                                                                                                                                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix.                                                                                                 |
+    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
+    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``                | only consider archive names starting with this prefix. (deprecated)                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp                                                       |
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB``             | only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see "borg help patterns". |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                                                                             |
+    |                                                                             | ``--sort-by KEYS``                                | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                                                              |
+    |                                                                             | ``--first N``                                     | consider first N archives after other filters were applied                                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--last N``                                      | consider last N archives after other filters were applied                                                                         |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -68,7 +70,7 @@ borg delete
         archives to delete
 
 
-    optional arguments
+    options
         -n, --dry-run    do not change repository
         --list          output verbose list of archives
         -s, --stats     print statistics for the deleted archive
@@ -76,15 +78,16 @@ borg delete
         --force         force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
         --keep-security-info    keep the local security info when deleting a repository
         --save-space    work slower, but using less space
+        -c SECONDS, --checkpoint-interval SECONDS    write checkpoint every SECONDS seconds (Default: 1800)
 
 
     :ref:`common_options`
         |
 
     Archive filters
-        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix.
+        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix. (deprecated)
-        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see "borg help patterns".
-        --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+        --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp
         --first N                         consider first N archives after other filters were applied
         --last N                          consider last N archives after other filters were applied
 
@@ -109,11 +112,9 @@ deleted - the "Deleted data" 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.
 
-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 ``--prefix PREFIX`` option. You can also specify a shell
+multiple archives using the ``--glob-archives GLOB`` option (for more info on
-pattern to match multiple archives using the ``--glob-archives GLOB`` option
+these patterns, see :ref:`borg_patterns`).
-(for more info on these patterns, see :ref:`borg_patterns`). Note that these
-two options are mutually exclusive.
 
 To avoid accidentally deleting archives, especially when using glob patterns,
 it might be helpful to use the ``--dry-run`` to test out the command without

docs/usage/diff.rst.inc

@@ -21,7 +21,7 @@ borg diff
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
     |                                                       | ``PATH``                              | paths of items inside the archives to compare; patterns are supported |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                |
+    | **options**                                                                                                                                                           |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
     |                                                       | ``--numeric-owner``                   | deprecated, use ``--numeric-ids`` instead                             |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
@@ -31,13 +31,15 @@ borg diff
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
     |                                                       | ``--sort``                            | Sort the output lines by file path.                                   |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    |                                                       | ``--content-only``                    | Only compare differences in content (exclude metadata differences)    |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
     |                                                       | ``--json-lines``                      | Format output as JSON Lines.                                          |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                                                                        |
     |                                                                                                                                                                       |
     | :ref:`common_options`                                                                                                                                                 |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                 |
+    | **Include/Exclude options**                                                                                                                                           |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
     |                                                       | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                        |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
@@ -66,18 +68,19 @@ borg diff
         paths of items inside the archives to compare; patterns are supported
 
 
-    optional arguments
+    options
         --numeric-owner    deprecated, use ``--numeric-ids`` instead
         --numeric-ids    only consider numeric user and group identifiers
         --same-chunker-params    Override check of chunker parameters.
         --sort     Sort the output lines by file path.
+        --content-only    Only compare differences in content (exclude metadata differences)
         --json-lines    Format output as JSON Lines. 
 
 
     :ref:`common_options`
         |
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN

docs/usage/export-tar.rst.inc

@@ -21,7 +21,7 @@ borg export-tar
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                              | paths to extract; patterns are supported                                                                  |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                    |
+    | **options**                                                                                                                                                                                               |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``--tar-filter``                      | filter program to pipe data through                                                                       |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -31,7 +31,7 @@ borg export-tar
     |                                                                                                                                                                                                           |
     | :ref:`common_options`                                                                                                                                                                                     |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                     |
+    | **Include/Exclude options**                                                                                                                                                                               |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                            |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -62,7 +62,7 @@ borg export-tar
         paths to extract; patterns are supported
 
 
-    optional arguments
+    options
         --tar-filter     filter program to pipe data through
         --list           output verbose list of items (files, dirs, ...)
 
@@ -70,7 +70,7 @@ borg export-tar
     :ref:`common_options`
         |
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN
@@ -92,7 +92,7 @@ before writing it to FILE:
 - .tar.gz or .tgz: gzip
 - .tar.bz2 or .tbz: bzip2
 - .tar.xz or .txz: xz
-- .tar.zstd: zstd
+- .tar.zstd or .tar.zst: zstd
 - .tar.lz4: lz4
 
 Alternatively, a ``--tar-filter`` program may be explicitly specified. It should

docs/usage/extract.rst.inc

@@ -19,7 +19,7 @@ borg extract
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                              | paths to extract; patterns are supported                                                                  |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                    |
+    | **options**                                                                                                                                                                                               |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``--list``                            | output verbose list of items (files, dirs, ...)                                                           |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -45,7 +45,7 @@ borg extract
     |                                                                                                                                                                                                           |
     | :ref:`common_options`                                                                                                                                                                                     |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                     |
+    | **Include/Exclude options**                                                                                                                                                                               |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                            |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -74,7 +74,7 @@ borg extract
         paths to extract; patterns are supported
 
 
-    optional arguments
+    options
         --list            output verbose list of items (files, dirs, ...)
         -n, --dry-run     do not actually change any files
         --numeric-owner    deprecated, use ``--numeric-ids`` instead
@@ -90,7 +90,7 @@ borg extract
     :ref:`common_options`
         |
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN

docs/usage/general/environment.rst.inc

@@ -100,6 +100,30 @@ General:
             caused EROFS. You will need this to make archives from volume shadow copies
             in WSL1 (Windows Subsystem for Linux 1).
 
+        authenticated_no_key
+            Work around a lost passphrase or key for an ``authenticated`` mode repository
+            (these are only authenticated, but not encrypted).
+            If the key is missing in the repository config, add ``key = anything`` there.
+
+            This workaround is **only** for emergencies and **only** to extract data
+            from an affected repository (read-only access)::
+
+                BORG_WORKAROUNDS=authenticated_no_key borg extract repo::archive
+
+            After you have extracted all data you need, you MUST delete the repository::
+
+                BORG_WORKAROUNDS=authenticated_no_key borg delete repo
+
+            Now you can init a fresh repo. Make sure you do not use the workaround any more.
+
+        ignore_invalid_archive_tam
+            Work around invalid archive TAMs created by borg < 1.2.5, see :issue:`7791`.
+
+            This workaround likely needs to get used only once when following the upgrade
+            instructions for CVE-2023-36811, see :ref:`archives_tam_vuln`.
+
+            In normal production operations, this workaround should never be used.
+
 Some automatic "answerers" (if set, they automatically answer confirmation questions):
     BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no (or =yes)
         For "Warning: Attempting to access a previously unknown unencrypted repository"
@@ -141,7 +165,16 @@ Directories and files:
         Defaults to ``$BORG_CONFIG_DIR/keys``.
         This directory contains keys for encrypted repositories.
     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:
+
+        - this setting only applies to the keyfile modes (not to the repokey modes).
+        - using a full, absolute path to the key file is recommended.
+        - all directories in the given path must exist.
+        - this setting forces borg to use the key file at the given location.
+        - the key file must either exist (for most commands) or will be created (``borg init``).
+        - you need to give a different path for different repositories.
+        - you need to point to the correct key file matching the repository the command will operate on.
     TMPDIR
         This is where temporary files are stored (might need a lot of temporary space for some
         operations), see tempfile_ for details.
@@ -152,9 +185,6 @@ Building:
     BORG_LIBLZ4_PREFIX
         Adds given prefix directory to the default locations. If a 'include/lz4.h' is found Borg
         will be linked against the system liblz4 instead of a bundled implementation. (setup.py)
-    BORG_LIBB2_PREFIX
-        Adds given prefix directory to the default locations. If a 'include/blake2.h' is found Borg
-        will be linked against the system libb2 instead of a bundled implementation. (setup.py)
     BORG_LIBZSTD_PREFIX
         Adds given prefix directory to the default locations. If a 'include/zstd.h' is found Borg
         will be linked against the system libzstd instead of a bundled implementation. (setup.py)

docs/usage/general/file-metadata.rst.inc

@@ -29,7 +29,7 @@ On some platforms additional features are supported:
 +=========================+==========+===========+============+
 | Linux                   | Yes      | Yes       | Yes [1]_   |
 +-------------------------+----------+-----------+------------+
-| Mac OS X                | Yes      | Yes       | Yes (all)  |
+| macOS                   | Yes      | Yes       | Yes (all)  |
 +-------------------------+----------+-----------+------------+
 | FreeBSD                 | Yes      | Yes       | Yes (all)  |
 +-------------------------+----------+-----------+------------+

docs/usage/general/file-systems.rst.inc

@@ -21,7 +21,7 @@ and readable after one of the failures mentioned above occurred, run
 - 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).
-- Up to 1000 files per directory (10000 for repositories initialized with Borg 1.0)
+- Up to 1000 files per directory.
 - 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
   it should fail if the destination exists and is not an empty directory,

docs/usage/help.rst.inc

@@ -10,36 +10,20 @@ The path/filenames used as input for the pattern matching start from the
 currently active recursion root. You usually give the recursion root(s)
 when invoking borg and these can be either relative or absolute paths.
 
-So, when you give `relative/` as root, the paths going into the matcher
+Starting with Borg 1.2, paths that are matched against patterns always
-will look like `relative/.../file.ext`. When you give `/absolute/` as
+appear relative. If you give ``/absolute/`` as root, the paths going
-root, they will look like `/absolute/.../file.ext`.
+into the matcher will start with ``absolute/``.
-
+If you give ``../../relative`` as root, the paths will be normalized
-File paths in Borg archives are always stored normalized and relative.
+as ``relative/``.
-This means that e.g. ``borg create /path/to/repo ../some/path`` will
-store all files as `some/path/.../file.ext` and ``borg create
-/path/to/repo /home/user`` will store all files as
-`home/user/.../file.ext`.
 
 A directory exclusion pattern can end either with or without a slash ('/').
 If it ends with a slash, such as `some/path/`, the directory will be
 included but not its content. If it does not end with a slash, such as
 `some/path`, both the directory and content will be excluded.
 
-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
-``--exclude`` patterns and shell-style is used for the ``--pattern``
+by a colon ':' (i.e. ``fm:path/*``, ``sh:path/**``).
-option. For commands that support patterns in their ``PATH`` argument
-like (``borg list``), the default pattern is path prefix.
-
-Starting with Borg 1.2, for all but regular expression pattern matching
-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.
-
-If followed by a colon (':') 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. `aa:something/*`).
 
 `Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector `fm:`
     This is the default style for ``--exclude`` and ``--exclude-from``.
@@ -124,37 +108,60 @@ Examples::
 
     # Exclude '/home/user/junk' and '/home/user/subdir/junk' but
     # not '/home/user/importantjunk' or '/etc/junk':
-    $ borg create -e '/home/*/junk' backup /
+    $ borg create -e 'home/*/junk' backup /
 
     # Exclude the contents of '/home/user/cache' but not the directory itself:
     $ borg create -e home/user/cache/ backup /
 
     # The file '/home/user/cache/important' is *not* backed up:
-    $ borg create -e /home/user/cache/ backup / /home/user/cache/important
+    $ borg create -e home/user/cache/ backup / /home/user/cache/important
 
     # The contents of directories in '/home' are not backed up when their name
     # ends in '.tmp'
-    $ borg create --exclude 're:^/home/[^/]+\.tmp/' backup /
+    $ borg create --exclude 're:^home/[^/]+\.tmp/' backup /
 
     # Load exclusions from file
     $ cat >exclude.txt <<EOF
     # Comment line
-    /home/*/junk
+    home/*/junk
     *.tmp
     fm:aa:something/*
-    re:^/home/[^/]+\.tmp/
+    re:^home/[^/]+\.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 /
 
-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 ``--pattern`` and ``--patterns-from`` options. Using these, you may
+exists with the ``--pattern`` and ``--patterns-from`` 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 `R`, 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
+
-with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern.
+Root path prefix ``R``
+    A recursion root path starts with the prefix ``R``, 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.
+
+Pattern style prefix ``P``
+    To change the default pattern style, use the ``P`` prefix, followed by
+    the pattern style abbreviation (``fm``, ``pf``, ``pp``, ``re``, ``sh``).
+    All patterns following this line will use this style until another style
+    is specified.
+
+Exclude pattern prefix ``-``
+    Use the prefix ``-``, followed by a pattern, to define an exclusion.
+    This has the same effect as the ``--exclude`` option.
+
+Exclude no-recurse pattern prefix ``!``
+    Use the prefix ``!``, 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.
+
+Include pattern prefix ``+``
+    Use the prefix ``+``, 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.
 
 .. note::
 
@@ -162,11 +169,29 @@ with the prefix -, an exclude-norecurse rule starts with !, all followed by a pa
     of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and
     ``--exclude-from`` ONLY excludes are defined.
 
-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't recurse into it and won't discover any potential matches for
+will not match - use normal excludes for such use cases.
-include rules below that directory.
+
+Example::
+
+    # 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's 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.
+    - **
 
 .. note::
 
@@ -197,23 +222,23 @@ The patterns.lst file could look like that::
     P sh
     R /
     # can be rebuild
-    - /home/*/.cache
+    - home/*/.cache
     # they're 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't backup the other home directories
-    - /home/*
+    - home/*
     # don't even look in /proc
-    ! /proc
+    ! proc
 
 You can specify recursion roots either on the command line or in a patternfile::
 
     # 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
 
 The patternfile::
@@ -224,7 +249,7 @@ The patternfile::
     R /home/bobby
     R /home/susan
 
-    - /home/bobby/junk
+    - home/bobby/junk
 
 This allows you to share the same patterns between multiple repositories
 without needing to specify them on the command line.
@@ -281,7 +306,7 @@ Examples::
 
     borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
     borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
-    borg prune --prefix '{hostname}-' ...
+    borg prune --glob-archives '{hostname}-*' ...
 
 .. note::
     systemd uses a difficult, non-standard syntax for command lines in unit files (refer to
@@ -348,29 +373,44 @@ auto,C[,L]
 
 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:
-    - you must combine this with encryption or it won't make any sense.
-    - your repo size will be bigger, of course.
 
-    The SPEC value will determine how the size obfuscation will work:
+    - You must combine this with encryption, or it won't make any sense.
+    - Your repo size will be bigger, of course.
+    - A chunk is limited by the constant ``MAX_DATA_SIZE`` (cur. ~20MiB).
+
+    The SPEC value determines how the size obfuscation works:
+
+    *Relative random reciprocal size variation* (multiplicative)
 
-    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
 
-    Add a randomly sized padding up to the given size:
+    Available factors::
-    110: 1kiB
+
-    ...
+      1:     0.01 ..        100
-    120: 1MiB
+      2:     0.1  ..      1,000
-    ...
+      3:     1    ..     10,000
-    123: 8MiB (max.)
+      4:    10    ..    100,000
+      5:   100    ..  1,000,000
+      6: 1,000    .. 10,000,000
+
+    Example probabilities for SPEC ``1``::
+
+      90   %  0.01 ..   0.1
+       9   %  0.1  ..   1
+       0.9 %  1    ..  10
+       0.09% 10    .. 100
+
+    *Randomly sized padding up to the given size* (additive)
+
+    ::
+
+      110: 1kiB (2 ^ (SPEC - 100))
+      ...
+      120: 1MiB
+      ...
+      123: 8MiB (max.)
 
 Examples::
 
@@ -381,7 +421,7 @@ Examples::
     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 ...
 

docs/usage/import-tar.rst.inc

@@ -19,7 +19,7 @@ borg import-tar
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``TARFILE``                                       | input tar file. "-" to read from stdin instead.                                                                                       |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                            |
+    | **options**                                                                                                                                                                                                                                       |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--tar-filter``                                  | filter program to pipe data through                                                                                                   |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -31,6 +31,8 @@ borg import-tar
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--json``                                        | output stats as JSON (implies --stats)                                                                                                |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--ignore-zeros``                                | ignore zero-filled blocks in the input tarball                                                                                        |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                                                                                                                                                    |
     |                                                                                                                                                                                                                                                   |
     | :ref:`common_options`                                                                                                                                                                                                                             |
@@ -64,12 +66,13 @@ borg import-tar
         input tar file. "-" to read from stdin instead.
 
 
-    optional arguments
+    options
         --tar-filter    filter program to pipe data through
         -s, --stats     print statistics for the created archive
         --list          output verbose list of items (files, dirs, ...)
         --filter STATUSCHARS    only display items with the given status characters
         --json          output stats as JSON (implies --stats)
+        --ignore-zeros    ignore zero-filled blocks in the input tarball
 
 
     :ref:`common_options`
@@ -96,7 +99,7 @@ based on its file extension and pipe the file through an appropriate filter:
 - .tar.gz or .tgz: gzip -d
 - .tar.bz2 or .tbz: bzip2 -d
 - .tar.xz or .txz: xz -d
-- .tar.zstd: zstd -d
+- .tar.zstd or .tar.zst: zstd -d
 - .tar.lz4: lz4 -d
 
 Alternatively, a --tar-filter program may be explicitly specified. It should
@@ -114,4 +117,8 @@ otherwise supported by Borg.
 A ``--sparse`` option (as found in borg create) is not supported.
 
 import-tar reads POSIX.1-1988 (ustar), POSIX.1-2001 (pax), GNU tar, UNIX V7 tar
-and SunOS tar with extended attributes.
+and SunOS tar with extended attributes.
+
+To import multiple tarballs into a single archive, they can be simply
+concatenated (e.g. using "cat") into a single file, and imported with an
+``--ignore-zeros`` option to skip through the stop markers between them.

docs/usage/info.rst.inc

@@ -12,31 +12,31 @@ borg info
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                     |
+    | **positional arguments**                                                                                                                                                                                                                                |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to display information about                                                                                                     |
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to display information about                                                                                |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                       |
+    | **options**                                                                                                                                                                                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--json``                            | format output as JSON                                                                                                                                  |
+    |                                                                             | ``--json``                            | format output as JSON                                                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                               |
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                          |
-    |                                                                                                                                                                                                                                                                              |
+    |                                                                                                                                                                                                                                                         |
-    | :ref:`common_options`                                                                                                                                                                                                                                                        |
+    | :ref:`common_options`                                                                                                                                                                                                                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                  |
+    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix.                                                                                                 |
+    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix. (deprecated)                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see "borg help patterns". |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp                                                       |
+    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                                                                             |
+    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                                                              |
+    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -52,7 +52,7 @@ borg info
         repository or archive to display information about
 
 
-    optional arguments
+    options
         --json     format output as JSON
 
 
@@ -60,9 +60,9 @@ borg info
         |
 
     Archive filters
-        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix.
+        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix. (deprecated)
-        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see "borg help patterns".
-        --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+        --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp
         --first N                         consider first N archives after other filters were applied
         --last N                          consider last N archives after other filters were applied
 

docs/usage/init.rst.inc

@@ -17,7 +17,7 @@ borg init
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``REPOSITORY``                     | repository to create                                                                                                                                                                                                                   |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                              |
+    | **options**                                                                                                                                                                                                                                                                                                                         |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-e MODE``, ``--encryption MODE`` | select encryption key mode **(required)**                                                                                                                                                                                              |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -46,7 +46,7 @@ borg init
         repository to create
 
 
-    optional arguments
+    options
         -e MODE, --encryption MODE     select encryption key mode **(required)**
         --append-only                  create an append-only mode repository. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.
         --storage-quota QUOTA          Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
@@ -128,6 +128,8 @@ The key will be stored in your home directory (in ``~/.config/borg/keys``).
 
 If you do **not** want to encrypt the contents of your backups, but still
 want to detect malicious tampering use ``--encryption authenticated``.
+To normally work with ``authenticated`` repos, you will need the passphrase, but
+there is an emergency workaround, see ``BORG_WORKAROUNDS=authenticated_no_key`` docs.
 
 If ``BLAKE2b`` is faster than ``SHA-256`` on your hardware, use ``--encryption authenticated-blake2``,
 ``--encryption repokey-blake2`` or ``--encryption keyfile-blake2``. Note: for remote backups

docs/usage/key_export.rst.inc

@@ -19,7 +19,7 @@ borg key export
     +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
     |                                                       | ``PATH``       | where to store the backup                                              |
     +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                          |
+    | **options**                                                                                                                                     |
     +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
     |                                                       | ``--paper``    | Create an export suitable for printing and later type-in               |
     +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
@@ -46,7 +46,7 @@ borg key export
         where to store the backup
 
 
-    optional arguments
+    options
         --paper       Create an export suitable for printing and later type-in
         --qr-html     Create an html file suitable for printing and later type-in or qr scan
 

docs/usage/key_import.rst.inc

@@ -19,7 +19,7 @@ borg key import
     +-------------------------------------------------------+----------------+----------------------------------------------------------+
     |                                                       | ``PATH``       | path to the backup ('-' to read from stdin)              |
     +-------------------------------------------------------+----------------+----------------------------------------------------------+
-    | **optional arguments**                                                                                                            |
+    | **options**                                                                                                                       |
     +-------------------------------------------------------+----------------+----------------------------------------------------------+
     |                                                       | ``--paper``    | interactively import from a backup done with ``--paper`` |
     +-------------------------------------------------------+----------------+----------------------------------------------------------+
@@ -44,7 +44,7 @@ borg key import
         path to the backup ('-' to read from stdin)
 
 
-    optional arguments
+    options
         --paper     interactively import from a backup done with ``--paper``
 
 

docs/usage/list.rst

@@ -34,11 +34,11 @@ Examples
     -rw-rw-r-- user   user    1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.text
     ...
 
-    $ borg list /path/to/repo/::archiveA --pattern 're:\.ext$'
+    $ borg list /path/to/repo/::archiveA --pattern '+ re:\.ext$' --pattern '- re:^.*$'
     -rw-rw-r-- user   user    1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.ext
     ...
 
-    $ borg list /path/to/repo/::archiveA --pattern 're:.ext$'
+    $ borg list /path/to/repo/::archiveA --pattern '+ re:.ext$' --pattern '- re:^.*$'
     -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
     ...

docs/usage/list.rst.inc

@@ -19,7 +19,7 @@ borg list
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``PATH``                              | paths to list; patterns are supported                                                                                                                                                                                                                                    |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                         |
+    | **options**                                                                                                                                                                                                                                                                                                                                                                                    |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--consider-checkpoints``            | Show checkpoint archives in the repository contents list (default: hidden).                                                                                                                                                                                              |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -37,17 +37,17 @@ borg list
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                                                                                                                                    |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix.                                                                                                                                                                                                                   |
+    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix. (deprecated)                                                                                                                                                                                                      |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.                                                                                                                   |
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see "borg help patterns".                                                                                                                                        |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp                                                                                                                                                                         |
+    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp                                                                                                                                                                |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                                                                                                                                                                                               |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                                                                                                                                                                                |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                                                                                                                                                                                                          |
+    | **Include/Exclude options**                                                                                                                                                                                                                                                                                                                                                                    |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                                                                                                                                                                                           |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -74,7 +74,7 @@ borg list
         paths to list; patterns are supported
 
 
-    optional arguments
+    options
         --consider-checkpoints    Show checkpoint archives in the repository contents list (default: hidden).
         --short     only print file/directory names, nothing else
         --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}")
@@ -86,14 +86,14 @@ borg list
         |
 
     Archive filters
-        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix.
+        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix. (deprecated)
-        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see "borg help patterns".
-        --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+        --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp
         --first N                         consider first N archives after other filters were applied
         --last N                          consider last N archives after other filters were applied
 
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN
@@ -156,6 +156,7 @@ Keys available only when listing archives in a repository:
 - comment: archive comment interpreted as text (might be missing non-text characters, see bcomment)
 - bcomment: verbatim archive comment, can contain any character except NUL
 - id: internal ID of the archive
+- tam: TAM authentication state of this archive
 
 - start: time (start) of creation of the archive
 - time: alias of "start"

docs/usage/mount.rst.inc

@@ -12,55 +12,55 @@ borg mount
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                     |
+    | **positional arguments**                                                                                                                                                                                                                                |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to mount                                                                                                                         |
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to mount                                                                                                    |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``MOUNTPOINT``                        | where to mount filesystem                                                                                                                              |
+    |                                                                             | ``MOUNTPOINT``                        | where to mount filesystem                                                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``PATH``                              | paths to extract; patterns are supported                                                                                                               |
+    |                                                                             | ``PATH``                              | paths to extract; patterns are supported                                                                                          |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                       |
+    | **options**                                                                                                                                                                                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--consider-checkpoints``            | Show checkpoint archives in the repository contents list (default: hidden).                                                                            |
+    |                                                                             | ``--consider-checkpoints``            | Show checkpoint archives in the repository contents list (default: hidden).                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-f``, ``--foreground``              | stay in foreground, do not daemonize                                                                                                                   |
+    |                                                                             | ``-f``, ``--foreground``              | stay in foreground, do not daemonize                                                                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-o``                                | Extra mount options                                                                                                                                    |
+    |                                                                             | ``-o``                                | Extra mount options                                                                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--numeric-owner``                   | deprecated, use ``--numeric-ids`` instead                                                                                                              |
+    |                                                                             | ``--numeric-owner``                   | deprecated, use ``--numeric-ids`` instead                                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--numeric-ids``                     | use numeric user and group identifiers from archive(s)                                                                                                 |
+    |                                                                             | ``--numeric-ids``                     | use numeric user and group identifiers from archive(s)                                                                            |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                               |
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                          |
-    |                                                                                                                                                                                                                                                                              |
+    |                                                                                                                                                                                                                                                         |
-    | :ref:`common_options`                                                                                                                                                                                                                                                        |
+    | :ref:`common_options`                                                                                                                                                                                                                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                  |
+    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix.                                                                                                 |
+    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix. (deprecated)                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see "borg help patterns". |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp                                                       |
+    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                                                                             |
+    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                                                              |
+    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                                                                                        |
+    | **Include/Exclude options**                                                                                                                                                                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                                                                         |
+    |                                                                             | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                                                    |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                                                                                                   |
+    |                                                                             | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                                                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--pattern PATTERN``                 | include/exclude paths matching PATTERN                                                                                                                 |
+    |                                                                             | ``--pattern PATTERN``                 | include/exclude paths matching PATTERN                                                                                            |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--patterns-from PATTERNFILE``       | read include/exclude patterns from PATTERNFILE, one per line                                                                                           |
+    |                                                                             | ``--patterns-from PATTERNFILE``       | read include/exclude patterns from PATTERNFILE, one per line                                                                      |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--strip-components NUMBER``         | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.                                              |
+    |                                                                             | ``--strip-components NUMBER``         | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -80,7 +80,7 @@ borg mount
         paths to extract; patterns are supported
 
 
-    optional arguments
+    options
         --consider-checkpoints    Show checkpoint archives in the repository contents list (default: hidden).
         -f, --foreground    stay in foreground, do not daemonize
         -o     Extra mount options
@@ -92,14 +92,14 @@ borg mount
         |
 
     Archive filters
-        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix.
+        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix. (deprecated)
-        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see "borg help patterns".
-        --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+        --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp
         --first N                         consider first N archives after other filters were applied
         --last N                          consider last N archives after other filters were applied
 
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN
@@ -143,14 +143,14 @@ manually. Unlike the ``uid`` and ``gid`` mount options which affect all files,
 
 Additional mount options supported by borg:
 
-- versions: when used with a repository mount, this gives a merged, versioned
+- ``versions``: when used with a repository mount, this gives a merged, versioned
   view of the files in the archives. EXPERIMENTAL, layout may change in future.
-- allow_damaged_files: by default damaged files (where missing chunks were
+- ``allow_damaged_files``: by default damaged files (where missing chunks were
-  replaced with runs of zeros by borg check ``--repair``) are not readable and
+  replaced with runs of zeros by ``borg check --repair``) are not readable and
   return EIO (I/O error). Set this option to read such files.
-- ignore_permissions: for security reasons the "default_permissions" mount
+- ``ignore_permissions``: for security reasons the ``default_permissions`` mount
-  option is internally enforced by borg. "ignore_permissions" can be given to
+  option is internally enforced by borg. ``ignore_permissions`` can be given to
-  not enforce "default_permissions".
+  not enforce ``default_permissions``.
 
 The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users
 to tweak the performance. It sets the number of cached data chunks; additional

docs/usage/notes.rst

@@ -276,7 +276,7 @@ with file 6::
 
 That's all to do in the repository.
 
-If you want to access this rollbacked repository from a client that already has
+If you want to access this rolled back repository from a client that already has
 a cache for this repository, the cache will reflect a newer repository state
 than what you actually have in the repository now, after the rollback.
 

docs/usage/prune.rst

@@ -7,9 +7,9 @@ Be careful, prune is a potentially dangerous command, it will remove backup
 archives.
 
 The default of prune is to apply to **all archives in the repository** unless
-you restrict its operation to a subset of the archives using ``--prefix``.
+you restrict its operation to a subset of the archives using ``--glob-archives``.
-When using ``--prefix``, be careful to choose a good prefix - e.g. do not use a
+When using ``--glob-archives``, be careful to choose a good matching pattern -
-prefix "foo" if you do not also want to match "foobar".
+e.g. do not use "foo*" if you do not also want to match "foobar".
 
 It is strongly recommended to always run ``prune -v --list --dry-run ...``
 first so you will see what it would do without it actually doing anything.
@@ -22,7 +22,7 @@ first so you will see what it would do without it actually doing anything.
 
     # Same as above but only apply to archive names starting with the hostname
     # of the machine followed by a "-" character:
-    $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --prefix='{hostname}-' /path/to/repo
+    $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --glob-archives='{hostname}-*' /path/to/repo
     # actually free disk space:
     $ borg compact /path/to/repo
 

docs/usage/prune.rst.inc

@@ -12,49 +12,51 @@ borg prune
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                     |
+    | **positional arguments**                                                                                                                                                                                                                                            |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY``                        | repository to prune                                                                                                                                    |
+    |                                                                             | ``REPOSITORY``                                    | repository to prune                                                                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                       |
+    | **options**                                                                                                                                                                                                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-n``, ``--dry-run``                 | do not change repository                                                                                                                               |
+    |                                                                             | ``-n``, ``--dry-run``                             | do not change repository                                                                                                          |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--force``                           | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work.                                                        |
+    |                                                                             | ``--force``                                       | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work.                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-s``, ``--stats``                   | print statistics for the deleted archive                                                                                                               |
+    |                                                                             | ``-s``, ``--stats``                               | print statistics for the deleted archive                                                                                          |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--list``                            | output verbose list of archives it keeps/prunes                                                                                                        |
+    |                                                                             | ``--list``                                        | output verbose list of archives it keeps/prunes                                                                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--keep-within INTERVAL``            | keep all archives within this time interval                                                                                                            |
+    |                                                                             | ``--keep-within INTERVAL``                        | keep all archives within this time interval                                                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--keep-last``, ``--keep-secondly``  | number of secondly archives to keep                                                                                                                    |
+    |                                                                             | ``--keep-last``, ``--keep-secondly``              | number of secondly archives to keep                                                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--keep-minutely``                   | number of minutely archives to keep                                                                                                                    |
+    |                                                                             | ``--keep-minutely``                               | number of minutely archives to keep                                                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-H``, ``--keep-hourly``             | number of hourly archives to keep                                                                                                                      |
+    |                                                                             | ``-H``, ``--keep-hourly``                         | number of hourly archives to keep                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-d``, ``--keep-daily``              | number of daily archives to keep                                                                                                                       |
+    |                                                                             | ``-d``, ``--keep-daily``                          | number of daily archives to keep                                                                                                  |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-w``, ``--keep-weekly``             | number of weekly archives to keep                                                                                                                      |
+    |                                                                             | ``-w``, ``--keep-weekly``                         | number of weekly archives to keep                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-m``, ``--keep-monthly``            | number of monthly archives to keep                                                                                                                     |
+    |                                                                             | ``-m``, ``--keep-monthly``                        | number of monthly archives to keep                                                                                                |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-y``, ``--keep-yearly``             | number of yearly archives to keep                                                                                                                      |
+    |                                                                             | ``-y``, ``--keep-yearly``                         | number of yearly archives to keep                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--save-space``                      | work slower, but using less space                                                                                                                      |
+    |                                                                             | ``--save-space``                                  | work slower, but using less space                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                               |
+    |                                                                             | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                            |
-    |                                                                                                                                                                                                                                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    | :ref:`common_options`                                                                                                                                                                                                                                                        |
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                      |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                                                                                                                                                                                                                     |
-    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                  |
+    | :ref:`common_options`                                                                                                                                                                                                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix.                                                                                                 |
+    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
+    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``                | only consider archive names starting with this prefix. (deprecated)                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB``             | only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see "borg help patterns". |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -70,7 +72,7 @@ borg prune
         repository to prune
 
 
-    optional arguments
+    options
         -n, --dry-run         do not change repository
         --force               force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
         -s, --stats           print statistics for the deleted archive
@@ -84,14 +86,15 @@ borg prune
         -m, --keep-monthly    number of monthly archives to keep
         -y, --keep-yearly     number of yearly archives to keep
         --save-space          work slower, but using less space
+        -c SECONDS, --checkpoint-interval SECONDS    write checkpoint every SECONDS seconds (Default: 1800)
 
 
     :ref:`common_options`
         |
 
     Archive filters
-        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix.
+        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix. (deprecated)
-        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see "borg help patterns".
 
 
 Description

docs/usage/recreate.rst.inc

@@ -19,7 +19,7 @@ borg recreate
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                                          | paths to recreate; patterns are supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+    | **options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--list``                                        | output verbose list of items (files, dirs, ...)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -33,7 +33,7 @@ borg recreate
     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
     | :ref:`common_options`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+    | **Include/Exclude options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-e PATTERN``, ``--exclude PATTERN``             | exclude paths matching PATTERN                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -63,7 +63,7 @@ borg recreate
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--recompress MODE``                             | recompress data chunks according to `MODE` and ``--compression``. Possible modes are `if-different`: recompress if current compression is with a different compression algorithm (the level is not considered); `always`: recompress even if current compression is with the same compression algorithm (use this to change the compression level); and `never`: do not recompress (use this option to explicitly prevent recompression). If no MODE is given, `if-different` will be used. Not passing --recompress is equivalent to "--recompress never". |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: buzhash,19,23,21,4095                                                                                                                                                                                                                                                                                                                                                                              |
+    |                                                       | ``--chunker-params PARAMS``                       | rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the chunker defaults. default: do not rechunk                                                                                                                                                                                                                                                                                                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
@@ -82,7 +82,7 @@ borg recreate
         paths to recreate; patterns are supported
 
 
-    optional arguments
+    options
         --list          output verbose list of items (files, dirs, ...)
         --filter STATUSCHARS    only display items with the given status characters (listed in borg create --help)
         -n, --dry-run    do not change anything
@@ -92,7 +92,7 @@ borg recreate
     :ref:`common_options`
         |
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN
@@ -109,7 +109,7 @@ borg recreate
         --timestamp TIMESTAMP                         manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
         -C COMPRESSION, --compression COMPRESSION     select compression algorithm, see the output of the "borg help compression" command for details.
         --recompress MODE                             recompress data chunks according to `MODE` and ``--compression``. Possible modes are `if-different`: recompress if current compression is with a different compression algorithm (the level is not considered); `always`: recompress even if current compression is with the same compression algorithm (use this to change the compression level); and `never`: do not recompress (use this option to explicitly prevent recompression). If no MODE is given, `if-different` will be used. Not passing --recompress is equivalent to "--recompress never".
-        --chunker-params PARAMS                       specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: buzhash,19,23,21,4095
+        --chunker-params PARAMS                       rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the chunker defaults. default: do not rechunk
 
 
 Description

docs/usage/serve.rst.inc

@@ -13,7 +13,7 @@ borg serve
     .. class:: borg-options-table
 
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+    | **options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--restrict-to-path PATH``       | restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository.                                                                                                                                                                                                                                      |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -40,7 +40,7 @@ borg serve
 
 
 
-    optional arguments
+    options
         --restrict-to-path PATH    restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository.
         --restrict-to-repository PATH    restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to 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.
         --append-only             only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.

docs/usage/upgrade.rst.inc

@@ -17,7 +17,7 @@ borg upgrade
     +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
     |                                                       | ``REPOSITORY``        | path to the repository to be upgraded                                                          |
     +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                         |
+    | **options**                                                                                                                                                                    |
     +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
     |                                                       | ``-n``, ``--dry-run`` | do not change repository                                                                       |
     +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
@@ -29,6 +29,8 @@ borg upgrade
     +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
     |                                                       | ``--disable-tam``     | Disable manifest authentication (in key and cache).                                            |
     +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
+    |                                                       | ``--archives-tam``    | add TAM authentication for all archives.                                                       |
+    +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                                                                                 |
     |                                                                                                                                                                                |
     | :ref:`common_options`                                                                                                                                                          |
@@ -48,12 +50,13 @@ borg upgrade
         path to the repository to be upgraded
 
 
-    optional arguments
+    options
         -n, --dry-run     do not change repository
         --inplace         rewrite repository in place, with no chance of going back to older versions of the repository.
         --force           Force upgrade
         --tam             Enable manifest authentication (in key and cache) (Borg 1.0.9 and later).
         --disable-tam     Disable manifest authentication (in key and cache).
+        --archives-tam    add TAM authentication for all archives.
 
 
     :ref:`common_options`
@@ -80,6 +83,23 @@ You do **not** need to run it when:
 Borg 1.x.y upgrades
 +++++++++++++++++++
 
+Archive TAM authentication:
+
+Use ``borg upgrade --archives-tam REPO`` 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 version 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.
+
+This upgrade needs to be done once per repository.
+
+Manifest TAM authentication:
+
 Use ``borg upgrade --tam REPO`` 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

pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools", "wheel", "pkgconfig", "Cython", "setuptools_scm>=1.7"]
+build-backend = "setuptools.build_meta"

requirements.d/coala.txt

@@ -1,5 +0,0 @@
-# style and other checks for many languages.
-# some bears (checkers) have additional requirements.
-coala
-coala-bears
-

requirements.d/development.lock.txt

@@ -1,13 +1,12 @@
-setuptools==60.7.1
+setuptools==68.2.2
-setuptools-scm==6.4.2
+setuptools-scm==8.0.4
-pip==22.0.3
+pip==23.3.1
-virtualenv==20.13.0
+virtualenv==20.24.6
 pkgconfig==1.5.5
-tox==3.24.5
+tox==4.11.3
-pytest==7.0.0
+pytest==7.4.3
-pytest-xdist==2.5.0
+pytest-xdist==3.3.1
-pytest-cov==3.0.0
+pytest-cov==4.1.0
-pytest-benchmark==3.4.1
+pytest-benchmark==4.0.0
-Cython==0.29.27
+Cython==0.29.36
-twine==3.8.0
 python-dateutil==2.8.2