From e9bd5f4e1d79fac6f49612004f1608c149545ee2 Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
Date: Tue, 1 Aug 2023 21:12:49 -0700
Subject: [PATCH] Add documentation and NEWS link (#732).

---
 NEWS                                        |  4 +-
 docs/how-to/make-per-application-backups.md | 55 ++++++++++++++++++---
 2 files changed, 50 insertions(+), 9 deletions(-)

diff --git a/NEWS b/NEWS
index 676f0c38..88b9cc9d 100644
--- a/NEWS
+++ b/NEWS
@@ -8,7 +8,9 @@
  * #728: Fix for "prune" action error when using the "keep_exclude_tags" option.
  * #730: Fix for Borg's interactive prompt on the "check --repair" action automatically getting
    answered "NO" even when the "check_i_know_what_i_am_doing" option isn't set.
- * #732: Include multiple configuration files with a single "!include".
+ * #732: Include multiple configuration files with a single "!include". See the documentation for
+   more information:
+   https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#multiple-merge-includes
 
 1.8.0
  * #575: BREAKING: For the "borgmatic borg" action, instead of implicitly injecting
diff --git a/docs/how-to/make-per-application-backups.md b/docs/how-to/make-per-application-backups.md
index 6a28759b..697517bf 100644
--- a/docs/how-to/make-per-application-backups.md
+++ b/docs/how-to/make-per-application-backups.md
@@ -233,18 +233,57 @@ checks:
 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> These
 options were organized into sections like `retention:` and `consistency:`.
 
-Once this include gets merged in, the resulting configuration would have all
-of the options from the original configuration file *and* the options from the
+Once this include gets merged in, the resulting configuration has all of the
+options from the original configuration file *and* the options from the
 include.
 
 Note that this `<<` include merging syntax is only for merging in mappings
-(configuration options and their values). But if you'd like to include a
-single value directly, please see the above about standard includes.
+(configuration options and their values). If you'd like to include a single
+value directly, please see above about standard includes.
 
-Additionally, there is a limitation preventing multiple `<<` include merges
-per file or option value. So for instance, that means you can do one `<<`
-merge at the global level, another `<<` within each nested option value, etc.
-(This is a YAML limitation.)
+
+### Multiple merge includes
+
+borgmatic has a limitation preventing multiple `<<` include merges per file or
+option value. This means you can do a single `<<` merge at the global level,
+another `<<` within each nested option value, etc. (This is a YAML
+limitation.) For instance:
+
+```yaml
+repositories:
+   - path: repo.borg
+
+# This won't work! You can't do multiple merges like this at the same level.
+<<: !include common1.yaml
+<<: !include common2.yaml
+```
+
+But read on for a way around this.
+
+<span class="minilink minilink-addedin">New in version 1.8.1</span> You can
+include and merge multiple configuration files all at once. For instance:
+
+```yaml
+repositories:
+   - path: repo.borg
+
+<<: !include [common1.yaml, common2.yaml, common3.yaml]
+```
+
+This merges in each included configuration file in turn, such that later files
+replace the options in earlier ones.
+
+Here's another way to do the same thing:
+
+```yaml
+repositories:
+   - path: repo.borg
+
+<<: !include
+    - common1.yaml
+    - common2.yaml
+    - common3.yaml
+```
 
 
 ### Deep merge