Deprecate the "borgmatic_source_directory" option in favor of "user_runtime_directory" and "user_state_directory" (#562). Move the default borgmatic streaming database dump and bootstrap metadata location on disk (#562). With Borg 1.4+, store database dumps and bootstrap metadata in a "/borgmatic" directory within a backup archive (#838). Add "--local-path", "--remote-path", and "--user-runtime-directory" flags to the "config bootstrap" action.

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

@@ -63,14 +63,23 @@ dump formats, which can't stream and therefore do consume temporary disk
 space. Additionally, prior to borgmatic 1.5.3, all database dumps consumed
 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 borgmatic's configuration.
+<span class="minilink minilink-addedin">New in version 1.9.0</span> To support
+this, borgmatic creates temporary streaming database dumps within
+`/run/user/$UID/borgmatic` by default (where `$UID` is the current user's ID).
+To customize the `/run/user/$UID` portion of this path, set the
+`user_runtime_directory` option in borgmatic's configuration. Alternatively,
+set the `XDG_RUNTIME_DIR` environment variable (often already set to
+`/run/user/$UID`).
 
-Also note that using a database hook implicitly enables both the
-`read_special` and `one_file_system` configuration settings (even if they're
-disabled in your configuration) to support this dump and restore streaming.
-See Limitations below for more on this.
+<span class="minilink minilink-addedin">Prior to version 1.9.0</span>
+borgmatic created temporary streaming database dumps within the `~/.borgmatic`
+directory by default. At that time, the path was configurable by the
+`borgmatic_source_directory` configuration option (now deprecated).
+
+Also note that using a database hook implicitly enables the
+`read_special` configuration option (even if it's disabled in your
+configuration) to support this dump and restore streaming. See Limitations
+below for more on this.
 
 Here's a more involved example that connects to remote databases:
 

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

@@ -225,15 +225,26 @@ repository, at most once a month.
 
 Unlike a real scheduler like cron, borgmatic only makes a best effort to run
 checks on the configured frequency. It compares that frequency with how long
-it's been since the last check for a given repository (as recorded in a file
-within `~/.borgmatic/checks`). If it hasn't been long enough, the check is
-skipped. And you still have to run `borgmatic check` (or `borgmatic` without
-actions) in order for checks to run, even when a `frequency` is configured!
+it's been since the last check for a given repository If it hasn't been long
+enough, the check is skipped. And you still have to run `borgmatic check` (or
+`borgmatic` without actions) in order for checks to run, even when a
+`frequency` is configured!
 
 This also applies *across* configuration files that have the same repository
 configured. Make sure you have the same check frequency configured in each
 though—or the most frequently configured check will apply.
 
+<span class="minilink minilink-addedin">New in version 1.9.0</span>To support
+this frequency logic, borgmatic records check timestamps within the
+`~/.local/state/borgmatic/checks` directory. To override the `~/.local/state`
+portion of this path, set the `user_state_directory` configuration option.
+Alternatively, set the `XDG_STATE_HOME` environment variable.
+
+<span class="minilink minilink-addedin">Prior to version 1.9.0</span>
+borgmatic recorded check timestamps within the `~/.borgmatic` directory. At
+that time, the path was configurable by the `borgmatic_source_directory`
+configuration option (now deprecated).
+
 If you want to temporarily ignore your configured frequencies, you can invoke
 `borgmatic check --force` to run checks unconditionally.
 

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

@@ -62,9 +62,9 @@ for available values.
 
 (No borgmatic `list` or `info` actions? Upgrade borgmatic!)
 
-<span class="minilink minilink-addedin">New in borgmatic version 1.9.0</span>
-There are also `repo-list` and `repo-info` actions for displaying repository
-information with Borg 2.x:
+<span class="minilink minilink-addedin">New in version 1.9.0</span> There are
+also `repo-list` and `repo-info` actions for displaying repository information
+with Borg 2.x:
 
 ```bash
 borgmatic repo-list
@@ -107,12 +107,28 @@ hooks](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/), you
 can list backed up database dumps via borgmatic. For example:
 
 ```bash 
-borgmatic list --archive latest --find .borgmatic/*_databases
+borgmatic list --archive latest --find *borgmatic/*_databases
 ```
 
 This gives you a listing of all database dump files contained in the latest
 archive, complete with file sizes.
 
+<span class="minilink minilink-addedin">New in borgmatic version
+1.9.0</span>Database dump files are stored at `/borgmatic` within a backup
+archive, regardless of the user who performs the backup. (Note that Borg
+doesn't store the leading `/`.)
+
+<span class="minilink minilink-addedin">With Borg version 1.2 and
+earlier</span>Database dump files are stored at `/var/run/$UID/borgmatic`
+(where `$UID` is the current user's ID) unless overridden by the
+`user_runtime_directory` configuration option or the `XDG_STATE_HOME`
+environment variable.
+
+<span class="minilink minilink-addedin">Prior to borgmatic version
+1.9.0</span>Database dump files were instead stored at `~/.borgmatic` within
+the backup archive (where `~` was expanded to the home directory of the user
+who performed the backup). This applied with all versions of Borg.
+
 
 ## Logging
 

docs/how-to/run-arbitrary-borg-commands.md

@@ -22,7 +22,7 @@ following, all based on your borgmatic configuration files or command-line
 arguments:
 
  * configured repositories, running your Borg command once for each one
- * local and remote Borg binary paths
+ * local and remote Borg executable paths
  * SSH settings and Borg environment variables
  * lock wait settings
  * verbosity