Clarify constants/placeholders interaction and improve examples (#763).
This commit is contained in:
parent
20cf0f7089
commit
84823dfb91
2 changed files with 24 additions and 18 deletions
|
@ -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:
|
||||||
|
|
|
@ -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:
|
||||||
|
|
Loading…
Reference in a new issue