From 19e95628c3ed57451bfc2c9a1421688a641f5211 Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Fri, 24 Mar 2023 23:47:05 -0700 Subject: [PATCH] Add documentation and NEWS for custom constants feature (#612). --- NEWS | 3 ++ borgmatic/commands/borgmatic.py | 2 +- borgmatic/config/load.py | 3 ++ docs/how-to/make-per-application-backups.md | 57 +++++++++++++++++++++ 4 files changed, 64 insertions(+), 1 deletion(-) diff --git a/NEWS b/NEWS index 9badeac..500a2cb 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 73bde94..61b8395 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 9cc665a..f3c45d5 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 2bf099e..5641213 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- +```