From e9bd5f4e1d79fac6f49612004f1608c149545ee2 Mon Sep 17 00:00:00 2001 From: Dan Helfman 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 676f0c3..88b9cc9 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 6a28759..697517b 100644 --- a/docs/how-to/make-per-application-backups.md +++ b/docs/how-to/make-per-application-backups.md @@ -233,18 +233,57 @@ checks: Prior to version 1.8.0 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. + +New in version 1.8.1 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