diff --git a/NEWS b/NEWS index 9badeacc..500a2cb5 100644 --- a/NEWS +++ b/NEWS @@ -2,6 +2,9 @@ * #501: Optionally error if a source directory does not exist via "source_directories_must_exist" option in borgmatic's location configuration. * #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 in borgmatic's storage configuration. * #623: Fix confusing message when an error occurs running actions for a configuration file. diff --git a/borgmatic/commands/borgmatic.py b/borgmatic/commands/borgmatic.py index 73bde94b..61b83951 100644 --- a/borgmatic/commands/borgmatic.py +++ b/borgmatic/commands/borgmatic.py @@ -581,7 +581,7 @@ def collect_configuration_run_summary_logs(configs, arguments): if not configs: 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 diff --git a/borgmatic/config/load.py b/borgmatic/config/load.py index 9cc665ae..f3c45d52 100644 --- a/borgmatic/config/load.py +++ b/borgmatic/config/load.py @@ -103,12 +103,15 @@ def load_configuration(filename): with open(filename) as file: file_contents = file.read() config = yaml.load(file_contents) + if config and 'constants' in config: for key, value in config['constants'].items(): value = json.dumps(value) file_contents = file_contents.replace(f'{{{key}}}', value.strip('"')) + config = yaml.load(file_contents) del config['constants'] + return config diff --git a/docs/how-to/make-per-application-backups.md b/docs/how-to/make-per-application-backups.md index 2bf099e6..5641213e 100644 --- a/docs/how-to/make-per-application-backups.md +++ b/docs/how-to/make-per-application-backups.md @@ -255,3 +255,60 @@ Be sure to quote your overrides if they contain spaces or other characters 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/). + + +## Constants + +New in version 1.7.10 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- +```