From 19e95628c3ed57451bfc2c9a1421688a641f5211 Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
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
+
+<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-
+```