From b37dd1a79e5a992325080f232ebd039be5742792 Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
Date: Wed, 9 Jun 2021 10:03:35 -0700
Subject: [PATCH] Document use case of running backups conditionally based on
 laptop power level (#419).

---
 NEWS                                          |  4 ++++
 ...movable-drive-or-an-intermittent-server.md | 20 +++++++++++++++++--
 sample/systemd/borgmatic.service              |  2 ++
 setup.py                                      |  2 +-
 4 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/NEWS b/NEWS
index 1eb54b4..b211395 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,7 @@
+1.5.15.dev0
+ * #419: Document use case of running backups conditionally based on laptop power level:
+   https://torsion.org/borgmatic/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server/
+
 1.5.14
  * #390: Add link to Hetzner storage offering from the documentation.
  * #398: Clarify canonical home of borgmatic in documentation.
diff --git a/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md b/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md
index 90f096b..0c4f83f 100644
--- a/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md
+++ b/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md
@@ -16,9 +16,14 @@ But if you run borgmatic and your hard drive isn't plugged in, or your buddy's
 server is offline, then you'll get an annoying error message and the overall
 borgmatic run will fail (even if individual repositories still complete).
 
+Another variant is when the source machine is only sometimes available for
+backups, e.g. a laptop where you want to skip backups when the battery falls
+below a certain level.
+
 So what if you want borgmatic to swallow the error of a missing drive
-or an offline server, and continue trucking along? That's where the concept of
-"soft failure" come in.
+or an offline server or a low battery—and exit gracefully? That's where the
+concept of "soft failure" come in.
+
 
 ## Soft failure command hooks
 
@@ -78,6 +83,17 @@ hooks:
       - ping -q -c 1 buddys-server.org > /dev/null || exit 75
 ```
 
+Or to only run backups if the battery level is high enough:
+
+```yaml
+hooks:
+    before_backup:
+      - is_battery_percent_at_least.sh 25
+```
+
+(Writing the battery script is left as an exercise to the reader.)
+
+
 ## Caveats and details
 
 There are some caveats you should be aware of with this feature.
diff --git a/sample/systemd/borgmatic.service b/sample/systemd/borgmatic.service
index 12e75a8..c118d73 100644
--- a/sample/systemd/borgmatic.service
+++ b/sample/systemd/borgmatic.service
@@ -2,6 +2,8 @@
 Description=borgmatic backup
 Wants=network-online.target
 After=network-online.target
+# Prevent borgmatic from running unless the machine is plugged into power. Remove this line if you
+# want to allow borgmatic to run anytime.
 ConditionACPower=true
 
 [Service]
diff --git a/setup.py b/setup.py
index 722dfb9..cc04f56 100644
--- a/setup.py
+++ b/setup.py
@@ -1,6 +1,6 @@
 from setuptools import find_packages, setup
 
-VERSION = '1.5.14'
+VERSION = '1.5.15.dev0'
 
 
 setup(