Add documentation and NEWS for custom constants feature (#612).

This commit is contained in:
Dan Helfman 2023-03-24 23:47:05 -07:00
parent 4d01e53414
commit 19e95628c3
4 changed files with 64 additions and 1 deletions

3
NEWS
View file

@ -2,6 +2,9 @@
* #501: Optionally error if a source directory does not exist via "source_directories_must_exist" * #501: Optionally error if a source directory does not exist via "source_directories_must_exist"
option in borgmatic's location configuration. option in borgmatic's location configuration.
* #576: Add support for "file://" paths within "repositories" option. * #576: Add support for "file://" paths within "repositories" option.
* #612: Define and use custom constants in borgmatic configuration files. See the documentation for
more information:
https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#constants
* #618: Add support for BORG_FILES_CACHE_TTL environment variable via "borg_files_cache_ttl" option * #618: Add support for BORG_FILES_CACHE_TTL environment variable via "borg_files_cache_ttl" option
in borgmatic's storage configuration. in borgmatic's storage configuration.
* #623: Fix confusing message when an error occurs running actions for a configuration file. * #623: Fix confusing message when an error occurs running actions for a configuration file.

View file

@ -581,7 +581,7 @@ def collect_configuration_run_summary_logs(configs, arguments):
if not configs: if not configs:
yield from log_error_records( yield from log_error_records(
r"{' '.join(arguments['global'].config_paths)}: No valid configuration files found", f"{' '.join(arguments['global'].config_paths)}: No valid configuration files found",
) )
return return

View file

@ -103,12 +103,15 @@ def load_configuration(filename):
with open(filename) as file: with open(filename) as file:
file_contents = file.read() file_contents = file.read()
config = yaml.load(file_contents) config = yaml.load(file_contents)
if config and 'constants' in config: if config and 'constants' in config:
for key, value in config['constants'].items(): for key, value in config['constants'].items():
value = json.dumps(value) value = json.dumps(value)
file_contents = file_contents.replace(f'{{{key}}}', value.strip('"')) file_contents = file_contents.replace(f'{{{key}}}', value.strip('"'))
config = yaml.load(file_contents) config = yaml.load(file_contents)
del config['constants'] del config['constants']
return config return config

View file

@ -255,3 +255,60 @@ Be sure to quote your overrides if they contain spaces or other characters
that your shell may interpret. that your shell may interpret.
An alternate to command-line overrides is passing in your values via [environment variables](https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/). An alternate to command-line overrides is passing in your values via [environment variables](https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/).
## Constants
<span class="minilink minilink-addedin">New in version 1.7.10</span> Another
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. (Constants don't
work across includes or separate configuration files though.)
Here's an example usage:
```yaml
constants:
user: foo
my_prefix: bar-
location:
source_directories:
- /home/{user}/.config
- /home/{user}/.ssh
...
storage:
archive_name_format: '{my_prefix}{now}'
retention:
prefix: {my_prefix}
consistency:
prefix: {my_prefix}
```
In this example, when borgmatic runs, all instances of `{user}` get replaced
with `foo` and all instances of `{my_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:
```yaml
location:
source_directories:
- /home/foo/.config
- /home/foo/.ssh
...
storage:
archive_name_format: 'bar-{now}'
retention:
prefix: bar-
consistency:
prefix: bar-
```