From 99590cb6b6abfc355fcca411d1036e926f75b94a Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
Date: Thu, 23 Jul 2020 21:33:42 -0700
Subject: [PATCH] Clarify documentation on configuration overrides,
 specifically the portion about list syntax.

---
 NEWS                                        |  4 ++++
 docs/how-to/make-per-application-backups.md | 17 +++++++++++++++--
 setup.py                                    |  2 +-
 3 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/NEWS b/NEWS
index 3d473c75b..ba42cac28 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,7 @@
+1.5.10.dev0
+ * Clarify documentation on configuration overrides, specifically the portion about list syntax:
+   http://localhost:8080/docs/how-to/make-per-application-backups/#configuration-overrides
+
 1.5.9
  * #300: Add "borgmatic export-tar" action to export an archive to a tar-formatted file or stream.
  * #339: Fix for intermittent timing-related test failure of logging function.
diff --git a/docs/how-to/make-per-application-backups.md b/docs/how-to/make-per-application-backups.md
index a893308e8..b0c257b03 100644
--- a/docs/how-to/make-per-application-backups.md
+++ b/docs/how-to/make-per-application-backups.md
@@ -129,12 +129,12 @@ Whatever the reason, you can override borgmatic configuration options at the
 command-line via the `--override` flag. Here's an example:
 
 ```bash
-borgmatic create --override location.remote_path=borg1
+borgmatic create --override location.remote_path=/usr/local/bin/borg1
 ```
 
 What this does is load your configuration files, and for each one, disregard
 the configured value for the `remote_path` option in the `location` section,
-and use the value of `borg1` instead.
+and use the value of `/usr/local/bin/borg1` instead.
 
 Note that the value is parsed as an actual YAML string, so you can even set
 list values by using brackets. For instance:
@@ -143,9 +143,22 @@ list values by using brackets. For instance:
 borgmatic create --override location.repositories=[test1.borg,test2.borg]
 ```
 
+Or even a single list element:
+
+```bash
+borgmatic create --override location.repositories=[/root/test1.borg]
+```
+
 There is not currently a way to override a single element of a list without
 replacing the whole list.
 
+Note that if you override an option of the list type (like
+`location.repositories`), you do need to use the `[ ]` list syntax. See the
+[configuration
+reference](https://torsion.org/borgmatic/docs/reference/configuration/) for
+which options are list types. (YAML list values look like `- this` with an
+indentation and a leading dash.)
+
 Be sure to quote your overrides if they contain spaces or other characters
 that your shell may interpret.
 
diff --git a/setup.py b/setup.py
index 46073c561..3ce06788c 100644
--- a/setup.py
+++ b/setup.py
@@ -1,6 +1,6 @@
 from setuptools import find_packages, setup
 
-VERSION = '1.5.9'
+VERSION = '1.5.10.dev0'
 
 
 setup(