More documentation updates based on section removal (#721).

docs/_includes/components/suggestion-link.html

@@ -1,5 +1,5 @@
 <h2>Improve this documentation</h2>
 
 <p>Have an idea on how to make this documentation even better? Use our <a
-href="https://projects.torsion.org/borgmatic-collective/borgmatic/issues">issue tracker</a> to send your
+href="https://torsion.org/borgmatic/#support-and-contributing">issue
-feedback!</p>
+tracker</a> to send your feedback!</p>

docs/how-to/add-preparation-and-cleanup-steps-to-backups.md

@@ -21,7 +21,6 @@ running backups, and specify `after_backup` hooks to perform cleanup steps
 afterwards. Here's an example:
 
 ```yaml
-hooks:
 before_backup:
     - mount /some/filesystem
 after_backup:
@@ -33,11 +32,23 @@ need to quote the entire string (or use a [multiline
 string](https://yaml-multiline.info/)) to avoid an error:
 
 ```yaml
-hooks:
 before_backup:
     - "echo Backup: start"
 ```
 
+There are additional hooks that run before/after other actions as well. For
+instance, `before_prune` runs before a `prune` action for a repository, while
+`after_prune` runs after it.
+
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `hooks:` section of your configuration.
+
+<span class="minilink minilink-addedin">New in version 1.7.0</span> The
+`before_actions` and `after_actions` hooks run before/after all the actions
+(like `create`, `prune`, etc.) for each repository. These hooks are a good
+place to run per-repository steps like mounting/unmounting a remote
+filesystem.
+
 <span class="minilink minilink-addedin">New in version 1.6.0</span> The
 `before_backup` and `after_backup` hooks each run once per repository in a
 configuration file. `before_backup` hooks runs right before the `create`
@@ -46,16 +57,6 @@ but not if an error occurs in a previous hook or in the backups themselves.
 (Prior to borgmatic 1.6.0, these hooks instead ran once per configuration file
 rather than once per repository.)
 
-There are additional hooks that run before/after other actions as well. For
-instance, `before_prune` runs before a `prune` action for a repository, while
-`after_prune` runs after it.
-
-<span class="minilink minilink-addedin">New in version 1.7.0</span> The
-`before_actions` and `after_actions` hooks run before/after all the actions
-(like `create`, `prune`, etc.) for each repository. These hooks are a good
-place to run per-repository steps like mounting/unmounting a remote
-filesystem.
-
 
 ## Variable interpolation
 
@@ -64,11 +65,13 @@ variables into the hook command. Here's an example that assumes you provide a
 separate shell script:
 
 ```yaml
-hooks:
 after_prune:
     - record-prune.sh "{configuration_filename}" "{repository}"
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 In this example, when the hook is triggered, borgmatic interpolates runtime
 values into the hook command: the borgmatic configuration filename and the
 paths of the current Borg repository. Here's the full set of supported
@@ -92,13 +95,15 @@ You can also use `before_everything` and `after_everything` hooks to perform
 global setup or cleanup:
 
 ```yaml
-hooks:
 before_everything:
     - set-up-stuff-globally
 after_everything:
     - clean-up-stuff-globally
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `hooks:` section of your configuration.
+
 `before_everything` hooks collected from all borgmatic configuration files run
 once before all configuration files (prior to all actions), but only if there
 is a `create` action. An error encountered during a `before_everything` hook
@@ -109,6 +114,7 @@ but only if there is a `create` action. It runs even if an error occurs during
 a backup or a backup hook, but not if an error occurs during a
 `before_everything` hook.
 
+
 ## Error hooks
 
 borgmatic also runs `on_error` hooks if an error occurs, either when creating
@@ -116,6 +122,7 @@ a backup or running a backup hook. See the [monitoring and alerting
 documentation](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)
 for more information.
 
+
 ## Hook output
 
 Any output produced by your hooks shows up both at the console and in syslog
@@ -123,6 +130,7 @@ Any output produced by your hooks shows up both at the console and in syslog
 href="https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/">inspecting
 your backups</a>.
 
+
 ## Security
 
 An important security note about hooks: borgmatic executes all hook commands

docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md

@@ -62,11 +62,13 @@ the external `findmnt` utility to see whether the drive is mounted before
 proceeding.
 
 ```yaml
-hooks:
 before_backup:
     - findmnt /mnt/removable > /dev/null || exit 75
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put this
+option in the `hooks:` section of your configuration.
+
 What this does is check if the `findmnt` command errors when probing for a
 particular mount point. If it does error, then it returns exit code 75 to
 borgmatic. borgmatic logs the soft failure, skips all further actions in that
@@ -89,17 +91,9 @@ before_backup:
     - ping -q -c 1 buddys-server.org > /dev/null || exit 75
 ```
 
-<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put the
-first two options in the `location:` section of your configuration and the
-`before_backup` option within the `hooks:` section.
-
-<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
-the `path:` portion of the `repositories` list.
-
 Or to only run backups if the battery level is high enough:
 
 ```yaml
-hooks:
 before_backup:
     - is_battery_percent_at_least.sh 25
 ```

docs/how-to/backup-your-databases.md

@@ -18,7 +18,6 @@ prior to running backups. For example, here is everything you need to dump and
 backup a couple of local PostgreSQL databases and a MySQL/MariaDB database.
 
 ```yaml
-hooks:
 postgresql_databases:
     - name: users
     - name: orders
@@ -26,11 +25,14 @@ hooks:
     - name: posts
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these and other database options in the `hooks:` section of your
+configuration.
+
 <span class="minilink minilink-addedin">New in version 1.5.22</span> You can
 also dump MongoDB databases. For example:
 
 ```yaml
-hooks:
 mongodb_databases:
     - name: messages
 ```
@@ -39,7 +41,6 @@ hooks:
 Additionally, you can dump SQLite databases. For example:
 
 ```yaml
-hooks:
 sqlite_databases:
     - name: mydb
       path: /var/lib/sqlite3/mydb.sqlite
@@ -54,7 +55,7 @@ temporary disk space.)
 
 To support this, borgmatic creates temporary named pipes in `~/.borgmatic` by
 default. To customize this path, set the `borgmatic_source_directory` option
-in the `location` section of borgmatic's configuration.
+in borgmatic's configuration.
 
 Also note that using a database hook implicitly enables both the
 `read_special` and `one_file_system` configuration settings (even if they're
@@ -64,7 +65,6 @@ See Limitations below for more on this.
 Here's a more involved example that connects to remote databases:
 
 ```yaml
-hooks:
 postgresql_databases:
     - name: users
       hostname: database1.example.org
@@ -106,7 +106,6 @@ listing databases, restoring databases, etc.).
 If you want to dump all databases on a host, use `all` for the database name:
 
 ```yaml
-hooks:
 postgresql_databases:
     - name: all
 mysql_databases:
@@ -120,6 +119,9 @@ this to work with PostgreSQL.
 
 The SQLite hook in particular does not consider "all" a special database name.
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `hooks:` section of your configuration.
+
 <span class="minilink minilink-addedin">New in version 1.7.6</span> With
 PostgreSQL and MySQL, you can optionally dump "all" databases to separate
 files instead of one combined dump file, allowing more convenient restores of
@@ -127,7 +129,6 @@ individual databases. Enable this by specifying your desired database dump
 `format`:
 
 ```yaml
-hooks:
 postgresql_databases:
     - name: all
       format: custom
@@ -143,7 +144,6 @@ problem—configure borgmatic to connect to the container's name on its exposed
 port. For instance:
 
 ```yaml
-hooks:
 postgresql_databases:
     - name: users
       hostname: your-database-container-name
@@ -152,6 +152,9 @@ hooks:
       password: trustsome1
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `hooks:` section of your configuration.
+
 But what if borgmatic is running on the host? You can still connect to a
 database container if its ports are properly exposed to the host. For
 instance, when running the database container, you can specify `--publish
@@ -179,8 +182,7 @@ hooks:
           password: trustsome1
 ```
 
-You can alter the ports in these examples to suit your particular database
+Alter the ports in these examples to suit your particular database system.
-system.
 
 
 ### No source directories
@@ -428,7 +430,6 @@ You can add any additional flags to the `options:` in your database
 configuration. Here's an example:
 
 ```yaml
-hooks:
 mysql_databases:
     - name: posts
       options: "--single-transaction --quick"

docs/how-to/deal-with-very-large-backups.md

@@ -65,17 +65,18 @@ configure borgmatic to run repository checks only. Configure this in the
 `consistency` section of borgmatic configuration:
 
 ```yaml
-consistency:
 checks:
     - name: repository
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `consistency:` section of your configuration.
+
 <span class="minilink minilink-addedin">Prior to version 1.6.2</span> The
 `checks` option was a plain list of strings without the `name:` part, and
 borgmatic ran each configured check every time checks were run. For example:
 
 ```yaml
-consistency:
 checks:
     - repository
 ```
@@ -103,7 +104,6 @@ optionally configure checks to run on a periodic basis rather than every time
 borgmatic runs checks. For instance:
 
 ```yaml
-consistency:
 checks:
     - name: repository
       frequency: 2 weeks
@@ -111,6 +111,9 @@ consistency:
       frequency: 1 month
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `consistency:` section of your configuration.
+
 This tells borgmatic to run the `repository` consistency check at most once
 every two weeks for a given repository and the `archives` check at most once a
 month. The `frequency` value is a number followed by a unit of time, e.g. "3
@@ -173,7 +176,6 @@ this option in the `consistency:` section of your configuration.
 was a plain list of strings without the `name:` part. For instance:
 
 ```yaml
-consistency:
 checks:
     - disabled
 ```

docs/how-to/develop-on-borgmatic.md

@@ -7,7 +7,7 @@ eleventyNavigation:
 ---
 ## Source code
 
-To get set up to hack on borgmatic, first clone it via HTTPS or SSH:
+To get set up to develop on borgmatic, first clone it via HTTPS or SSH:
 
 ```bash
 git clone https://projects.torsion.org/borgmatic-collective/borgmatic.git
@@ -21,8 +21,8 @@ git clone ssh://git@projects.torsion.org:3022/borgmatic-collective/borgmatic.git
 
 Then, install borgmatic
 "[editable](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs)"
-so that you can run borgmatic commands while you're hacking on them to
+so that you can run borgmatic actions during development to make sure your
-make sure your changes work.
+changes work.
 
 ```bash
 cd borgmatic

docs/how-to/inspect-your-backups.md

@@ -60,7 +60,7 @@ with `--format`. Refer to the [borg list --format
 documentation](https://borgbackup.readthedocs.io/en/stable/usage/list.html#the-format-specifier-syntax)
 for available values.
 
-*(No borgmatic `list` or `info` actions? Upgrade borgmatic!)*
+(No borgmatic `list` or `info` actions? Upgrade borgmatic!)
 
 <span class="minilink minilink-addedin">New in borgmatic version 1.7.0</span>
 There are also `rlist` and `rinfo` actions for displaying repository

docs/how-to/make-per-application-backups.md

@@ -104,11 +104,12 @@ to filter archives when running supported actions.
 For instance, let's say that you have this in your configuration:
 
 ```yaml
-storage:
-    ...
 archive_name_format: {hostname}-user-data-{now}
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `storage:` section of your configuration.
+
 borgmatic considers `{now}` an emphemeral data placeholder that will probably
 change per archive, while `{hostname}` won't. So it turns the example value
 into `{hostname}-user-data-*` and applies it to filter down the set of
@@ -124,8 +125,6 @@ If this behavior isn't quite smart enough for your needs, you can use the
 filtering archives. For example:
 
 ```yaml
-storage:
-    ...
 archive_name_format: {hostname}-user-data-{now}
 match_archives: sh:myhost-user-data-*        
 ```
@@ -190,7 +189,7 @@ When a configuration include is a relative path, borgmatic loads it from either
 the current working directory or from the directory containing the file doing
 the including.
 
-Note that this form of include must be a YAML value rather than a key. For
+Note that this form of include must be a value rather than an option name. For
 example, this will not work:
 
 ```yaml
@@ -201,7 +200,7 @@ repositories:
 !include /etc/borgmatic/common_checks.yaml
 ```
 
-But if you do want to merge in a YAML key *and* its values, keep reading!
+But if you do want to merge in a option name *and* its values, keep reading!
 
 
 ## Include merging
@@ -238,11 +237,6 @@ Once this include gets merged in, the resulting configuration would have all
 of the options from the original configuration file *and* the options from the
 include.
 
-<span class="minilink minilink-addedin">Prior to version 1.6.0</span> When the
-same option appeared in both the local file and the merged include, the local
-file's value took precedence—meaning the included value was ignored in favor
-of the local one. But see below about deep merge in version 1.6.0+.
-
 Note that this `<<` include merging syntax is only for merging in mappings
 (configuration options and their values). But if you'd like to include a
 single value directly, please see the above about standard includes.
@@ -261,29 +255,30 @@ at all levels in the two configuration files. This allows you to include
 common configuration—up to full borgmatic configuration files—while overriding
 only the parts you want to customize.
 
-For instance, here's an example of a main configuration file that pulls in two
+For instance, here's an example of a main configuration file that pulls in
-retention options via an include and then overrides one of them locally:
+options via an include and then overrides one of them locally:
 
 ```yaml
 <<: !include /etc/borgmatic/common.yaml
 
-location:
+constants:
-   ...
+    hostname: myhostname
 
-retention:
+repositories:
-    keep_daily: 5
+    - path: repo.borg
 ```
 
 This is what `common.yaml` might look like:
 
 ```yaml
-retention:
+constants:
-    keep_hourly: 24
+    prefix: myprefix
-    keep_daily: 7
+    hostname: otherhost
 ```
 
 Once this include gets merged in, the resulting configuration would have a
-`keep_hourly` value of `24` and an overridden `keep_daily` value of `5`.
+`prefix` value of `myprefix` and an overridden `hostname` value of
+`myhostname`.
 
 When there's an option collision between the local file and the merged
 include, the local file's option takes precedence.
@@ -301,7 +296,6 @@ configuration file, you can omit it with an `!omit` tag. For instance:
 ```yaml
 <<: !include /etc/borgmatic/common.yaml
 
-location:
 source_directories:
     - !omit /home
     - /var
@@ -310,12 +304,14 @@ location:
 And `common.yaml` like this:
 
 ```yaml
-location:
 source_directories:
     - /home
     - /etc
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `location:` section of your configuration.
+
 Once this include gets merged in, the resulting configuration will have a
 `source_directories` value of `/etc` and `/var`—with `/home` omitted.
 
@@ -328,7 +324,6 @@ an example of some things not to do:
 ```yaml
 <<: !include /etc/borgmatic/common.yaml
 
-location:
 source_directories:
     # Do not do this! It will not work. "!omit" belongs before "/home".
     - /home !omit
@@ -451,9 +446,6 @@ What this does is load your configuration files, and for each one, disregard
 the configured value for the `remote_path` option, and use the value of
 `/usr/local/bin/borg1` instead.
 
-<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Don't
-forget to specify the section (like `location:`) that any option is in.
-
 You can even override nested values or multiple values at once. For instance:
 
 ```bash

docs/how-to/monitor-your-backups.md

@@ -89,17 +89,18 @@ notifications or take other actions, so you can get alerted as soon as
 something goes wrong. Here's a not-so-useful example:
 
 ```yaml
-hooks:
 on_error:
     - echo "Error while creating a backup or running a backup hook."
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 The `on_error` hook supports interpolating particular runtime variables into
 the hook command. Here's an example that assumes you provide a separate shell
 script to handle the alerting:
 
 ```yaml
-hooks:
 on_error:
     - send-text-message.sh "{configuration_filename}" "{repository}"
 ```
@@ -135,11 +136,13 @@ URL" for your project. Here's an example:
 
 
 ```yaml
-hooks:
 healthchecks:
     ping_url: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 With this hook in place, borgmatic pings your Healthchecks project when a
 backup begins, ends, or errors. Specifically, after the <a
 href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
@@ -179,11 +182,13 @@ API URL" for your monitor. Here's an example:
 
 
 ```yaml
-hooks:
 cronitor:
     ping_url: https://cronitor.link/d3x0c1
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 With this hook in place, borgmatic pings your Cronitor monitor when a backup
 begins, ends, or errors. Specifically, after the <a
 href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
@@ -208,11 +213,13 @@ URL" for your monitor. Here's an example:
 
 
 ```yaml
-hooks:
 cronhub:
     ping_url: https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d031
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 With this hook in place, borgmatic pings your Cronhub monitor when a backup
 begins, ends, or errors. Specifically, after the <a
 href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
@@ -251,11 +258,13 @@ Here's an example:
 
 
 ```yaml
-hooks:
 pagerduty:
     integration_key: a177cad45bd374409f78906a810a3074
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 With this hook in place, borgmatic creates a PagerDuty event for your service
 whenever backups fail. Specifically, if an error occurs during a `create`,
 `prune`, `compact`, or `check` action, borgmatic sends an event to PagerDuty
@@ -291,7 +300,6 @@ An example configuration is shown here, with all the available options, includin
 [tags](https://ntfy.sh/docs/publish/#tags-emojis):
 
 ```yaml
-hooks:
 ntfy:
     topic: my-unique-topic
     server: https://ntfy.my-domain.com
@@ -316,6 +324,10 @@ hooks:
         - fail
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+the `ntfy:` option in the `hooks:` section of your configuration.
+
+
 ## Scripting borgmatic
 
 To consume the output of borgmatic in other software, you can include an

docs/how-to/provide-your-passwords.md

@@ -20,10 +20,12 @@ pull your repository passphrase, your database passwords, or any other option
 values from environment variables. For instance:
 
 ```yaml
-storage:
 encryption_passphrase: ${MY_PASSPHRASE}
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `storage:` section of your configuration.
+
 This uses the `MY_PASSPHRASE` environment variable as your encryption
 passphrase. Note that the `{` `}` brackets are required. `$MY_PASSPHRASE` by
 itself will not work.
@@ -38,12 +40,14 @@ configuration](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/)
 the same approach applies. For example:
 
 ```yaml
-hooks:
 postgresql_databases:
     - name: users
       password: ${MY_DATABASE_PASSWORD}
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 This uses the `MY_DATABASE_PASSWORD` environment variable as your database
 password.
 
@@ -53,7 +57,6 @@ password.
 If you'd like to set a default for your environment variables, you can do so with the following syntax:
 
 ```yaml
-storage:
 encryption_passphrase: ${MY_PASSPHRASE:-defaultpass}
 ```
 
@@ -72,7 +75,6 @@ can escape it with a backslash. For instance, if your password is literally
 `${A}@!`:
 
 ```yaml
-storage:
 encryption_passphrase: \${A}@!
 ```
 

docs/how-to/upgrade.md

@@ -135,12 +135,6 @@ repositories:
     - path: original.borg
 ```
 
-<span class="minilink minilink-addedin">Prior to version 1.8.0</span> This
-option was found in the `location:` section of your configuration.
-
-<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
-the `path:` portion of the `repositories` list.
-
 Change it to a new (not yet created) repository path:
 
 ```yaml
@@ -148,6 +142,12 @@ repositories:
     - path: upgraded.borg
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> This
+option was found in the `location:` section of your configuration.
+
+<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
+the `path:` portion of the `repositories` list.
+
 Then, run the `rcreate` action (formerly `init`) to create that new Borg 2
 repository:
 

docs/reference/command-line.md

@@ -15,7 +15,7 @@ listed here do not have equivalents in borgmatic's [configuration
 file](https://torsion.org/borgmatic/docs/reference/configuration/).
 
 If you're using an older version of borgmatic, some of these flags may not be
-present in that version, and you should instead use `borgmatic --help` or
+present in that version and you should instead use `borgmatic --help` or
 `borgmatic [action name] --help` (where `[action name]` is the name of an
 action like `list`, `create`, etc.).