Clarify constants/placeholders interaction and improve examples (#763).

This commit is contained in:
Dan Helfman 2023-12-24 11:18:17 -08:00
parent 20cf0f7089
commit 84823dfb91
2 changed files with 24 additions and 18 deletions

View file

@ -6,14 +6,15 @@ properties:
constants: constants:
type: object type: object
description: | description: |
Constants to use in the configuration file. All occurrences of the Constants to use in the configuration file. Within option values,
constant name within curly braces will be replaced with the value. all occurrences of the constant name in curly braces will be
For example, if you have a constant named "hostname" with the value replaced with the constant value. For example, if you have a
"myhostname", then the string "{hostname}" will be replaced with constant named "app_name" with the value "myapp", then the string
"myhostname" in the configuration file. "{app_name}" will be replaced with "myapp" in the configuration
file.
example: example:
hostname: myhostname app_name: myapp
prefix: myprefix user: myuser
source_directories: source_directories:
type: array type: array
items: items:

View file

@ -301,7 +301,7 @@ options via an include and then overrides one of them locally:
<<: !include /etc/borgmatic/common.yaml <<: !include /etc/borgmatic/common.yaml
constants: constants:
hostname: myhostname base_directory: /opt
repositories: repositories:
- path: repo.borg - path: repo.borg
@ -311,13 +311,13 @@ This is what `common.yaml` might look like:
```yaml ```yaml
constants: constants:
prefix: myprefix app_name: myapp
hostname: otherhost base_directory: /var/lib
``` ```
Once this include gets merged in, the resulting configuration would have a Once this include gets merged in, the resulting configuration would have an
`prefix` value of `myprefix` and an overridden `hostname` value of `app_name` value of `myapp` and an overridden `base_directory` value of
`myhostname`. `/opt`.
When there's an option collision between the local file and the merged When there's an option collision between the local file and the merged
include, the local file's option takes precedence. include, the local file's option takes precedence.
@ -540,7 +540,7 @@ tool is borgmatic's support for defining custom constants. This is similar to
the [variable interpolation the [variable interpolation
feature](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/#variable-interpolation) feature](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/#variable-interpolation)
for command hooks, but the constants feature lets you substitute your own for command hooks, but the constants feature lets you substitute your own
custom values into anywhere in the entire configuration file. custom values into any option values in the entire configuration file.
Here's an example usage: Here's an example usage:
@ -563,10 +563,15 @@ forget to specify the section (like `location:` or `storage:`) that any option
is in. is in.
In this example, when borgmatic runs, all instances of `{user}` get replaced In this example, when borgmatic runs, all instances of `{user}` get replaced
with `foo` and all instances of `{archive_prefix}` get replaced with `bar-`. with `foo` and all instances of `{archive_prefix}` get replaced with `bar`.
(And in this particular example, `{now}` doesn't get replaced with anything, And `{now}` doesn't get replaced with anything, but gets passed directly to
but gets passed directly to Borg.) After substitution, the logical result Borg, which has its own
looks something like this: [placeholders](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-help-placeholders)
using the same syntax as borgmatic constants. So borgmatic options like
`archive_name_format` that get passed directly to Borg can use either Borg
placeholders or borgmatic constants or both!
After substitution, the logical result looks something like this:
```yaml ```yaml
source_directories: source_directories: