From 151becbaea96cd84bb07b41cb48e547ad6180305 Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
Date: Tue, 11 Nov 2025 10:21:01 -0800
Subject: [PATCH] Move shell autocompletion documentation out to reference
 docs.

---
 docs/how-to/set-up-backups.md                 | 46 ++++---------------
 .../command-line/autocompletion/bash.md       | 36 +++++++++++++++
 .../command-line/autocompletion/fish.md       | 17 +++++++
 .../command-line/autocompletion/index.md      | 13 ++++++
 4 files changed, 74 insertions(+), 38 deletions(-)
 create mode 100644 docs/reference/command-line/autocompletion/bash.md
 create mode 100644 docs/reference/command-line/autocompletion/fish.md
 create mode 100644 docs/reference/command-line/autocompletion/index.md

diff --git a/docs/how-to/set-up-backups.md b/docs/how-to/set-up-backups.md
index d983ac9a..fc26c3e4 100644
--- a/docs/how-to/set-up-backups.md
+++ b/docs/how-to/set-up-backups.md
@@ -355,48 +355,18 @@ Access](https://projects.torsion.org/borgmatic-collective/borgmatic/issues/293).
 
 ## Niceties
 
+<a id="shell-completion"></a>
+<a id="bash"></a>
+<a id="fish"></a>
 
-### Shell completion
 
-borgmatic includes a shell completion script (currently only for Bash and Fish) to
-support tab-completing borgmatic command-line actions and flags. Depending on
-how you installed borgmatic, this may be enabled by default.
+### Command-line autocompletion
 
-#### Bash
+borgmatic includes autocompletion scripts for various command-line shells to
+support tab-completing command-line actions and flags. See the [autocompletion
+documentation](https://torsion.org/borgmatic/reference/command-line/autocompletion/)
+for details.
 
-If completions aren't enabled, start by installing the `bash-completion` Linux package or the
-[`bash-completion@2`](https://formulae.brew.sh/formula/bash-completion@2)
-macOS Homebrew formula. Then, install the shell completion script globally:
-
-```bash
-sudo su -c "borgmatic --bash-completion > $(pkg-config --variable=completionsdir bash-completion)/borgmatic"
-```
-
-If you don't have `pkg-config` installed, you can try the following path
-instead:
-
-```bash
-sudo su -c "borgmatic --bash-completion > /usr/share/bash-completion/completions/borgmatic"
-```
-
-Or, if you'd like to install the script for only the current user:
-
-```bash
-mkdir --parents ~/.local/share/bash-completion/completions
-borgmatic --bash-completion > ~/.local/share/bash-completion/completions/borgmatic
-```
-
-Finally, restart your shell (`exit` and open a new shell) so the completions
-take effect.
-
-#### fish
-
-To add completions for fish, install the completions file globally:
-
-```fish
-borgmatic --fish-completion | sudo tee /usr/share/fish/vendor_completions.d/borgmatic.fish
-source /usr/share/fish/vendor_completions.d/borgmatic.fish
-```
 
 ### Colored output
 
diff --git a/docs/reference/command-line/autocompletion/bash.md b/docs/reference/command-line/autocompletion/bash.md
new file mode 100644
index 00000000..24030ffc
--- /dev/null
+++ b/docs/reference/command-line/autocompletion/bash.md
@@ -0,0 +1,36 @@
+---
+title: bash
+eleventyNavigation:
+  key: bash
+  parent: ➡️  Autocompletion
+---
+borgmatic includes an autocompletion script for
+[Bash](https://www.gnu.org/software/bash/) to support tab-completing
+command-line actions and flags. Depending on how you installed borgmatic, this
+may be enabled by default.
+
+If completions aren't enabled, start by installing the `bash-completion` Linux
+package or the
+[`bash-completion@2`](https://formulae.brew.sh/formula/bash-completion@2) macOS
+Homebrew formula. Then, install the shell completion script globally:
+
+```bash
+sudo su -c "borgmatic --bash-completion > $(pkg-config --variable=completionsdir bash-completion)/borgmatic"
+```
+
+If you don't have `pkg-config` installed, you can try the following path
+instead:
+
+```bash
+sudo su -c "borgmatic --bash-completion > /usr/share/bash-completion/completions/borgmatic"
+```
+
+Or, if you'd like to install the script for only the current user:
+
+```bash
+mkdir --parents ~/.local/share/bash-completion/completions
+borgmatic --bash-completion > ~/.local/share/bash-completion/completions/borgmatic
+```
+
+Finally, restart your shell (`exit` and open a new shell) so the completions
+take effect.
diff --git a/docs/reference/command-line/autocompletion/fish.md b/docs/reference/command-line/autocompletion/fish.md
new file mode 100644
index 00000000..327e3c9a
--- /dev/null
+++ b/docs/reference/command-line/autocompletion/fish.md
@@ -0,0 +1,17 @@
+---
+title: fish
+eleventyNavigation:
+  key: fish
+  parent: ➡️  Autocompletion
+---
+borgmatic includes an autocompletion script for [fish
+shell](https://fishshell.com/) to support tab-completing command-line actions
+and flags. Depending on how you installed borgmatic, this may be enabled by
+default.
+
+If completions aren't enabled, install the completions file globally:
+
+```shell
+borgmatic --fish-completion | sudo tee /usr/share/fish/vendor_completions.d/borgmatic.fish
+source /usr/share/fish/vendor_completions.d/borgmatic.fish
+```
diff --git a/docs/reference/command-line/autocompletion/index.md b/docs/reference/command-line/autocompletion/index.md
new file mode 100644
index 00000000..e8446b9e
--- /dev/null
+++ b/docs/reference/command-line/autocompletion/index.md
@@ -0,0 +1,13 @@
+---
+title: ➡️  Autocompletion
+eleventyNavigation:
+  key: ➡️  Autocompletion
+  parent: 💻 Command-line
+---
+
+borgmatic includes autocompletion scripts for various command-line shells to
+support tab-completing command-line actions and flags. Depending on how you
+installed borgmatic, this may be enabled by default. Here are the supported
+shells and how to configure borgmatic autocompletion for each:
+
+{{ collections.all | eleventyNavigation: "➡️  Autocompletion" | eleventyNavigationToHtml | replace: 'href="/reference/', 'href="/borgmatic/reference/' }}