psw/borgmatic
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source
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
Show stats Download patch file Download diff file Expand all files Collapse all files

15
borgmatic/config/schema.yaml
View file

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

27
docs/how-to/make-per-application-backups.md
View file

@ -301,7 +301,7 @@ options via an include and then overrides one of them locally:
<<: !include /etc/borgmatic/common.yaml
constants:
hostname: myhostname
base_directory: /opt
repositories:
- path: repo.borg
@ -311,13 +311,13 @@ This is what `common.yaml` might look like:
```yaml
constants:
prefix: myprefix
hostname: otherhost
app_name: myapp
base_directory: /var/lib
```
Once this include gets merged in, the resulting configuration would have a
`prefix` value of `myprefix` and an overridden `hostname` value of
`myhostname`.
Once this include gets merged in, the resulting configuration would have an
`app_name` value of `myapp` and an overridden `base_directory` value of
`/opt`.
When there's an option collision between the local file and the merged
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
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
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:
@ -563,10 +563,15 @@ forget to specify the section (like `location:` or `storage:`) that any option
is in.
In this example, when borgmatic runs, all instances of `{user}` get replaced
with `foo` and all instances of `{archive_prefix}` get replaced with `bar-`.
(And in this particular example, `{now}` doesn't get replaced with anything,
but gets passed directly to Borg.) After substitution, the logical result
looks something like this:
with `foo` and all instances of `{archive_prefix}` get replaced with `bar`.
And `{now}` doesn't get replaced with anything, but gets passed directly to
Borg, which has its own
[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
source_directories: