From 384d7635a412462a807d050deda408c780acbad7 Mon Sep 17 00:00:00 2001
From: Marian Beermann <public@enkore.de>
Date: Sun, 21 May 2017 17:07:58 +0200
Subject: [PATCH] docs: add systemd warning regarding placeholders

---
 docs/usage/help.rst.inc | 10 ++++++++++
 src/borg/archiver.py    | 12 +++++++++++-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc
index 8b3f8ded2..9082e5073 100644
--- a/docs/usage/help.rst.inc
+++ b/docs/usage/help.rst.inc
@@ -206,6 +206,16 @@ Examples::
     borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
     borg prune --prefix '{hostname}-' ...
 
+.. note::
+    systemd uses a difficult, non-standard syntax for command lines in unit files (refer to
+    the `systemd.unit(5)` manual page).
+
+    When invoking borg from unit files, pay particular attention to escaping,
+    especially when using the now/utcnow placeholders, since systemd performs its own
+    %-based variable replacement even in quoted text. To avoid interference from systemd,
+    double all percent signs (``{hostname}-{now:%Y-%m-%d_%H:%M:%S}``
+    becomes ``{hostname}-{now:%%Y-%%m-%%d_%%H:%%M:%%S}``).
+
 .. _borg_compression:
 
 borg help compression
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
index 79f89e972..7a3642011 100644
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -2009,7 +2009,17 @@ class Archiver:
 
             borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
             borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
-            borg prune --prefix '{hostname}-' ...\n\n''')
+            borg prune --prefix '{hostname}-' ...
+
+        .. note::
+            systemd uses a difficult, non-standard syntax for command lines in unit files (refer to
+            the `systemd.unit(5)` manual page).
+
+            When invoking borg from unit files, pay particular attention to escaping,
+            especially when using the now/utcnow placeholders, since systemd performs its own
+            %-based variable replacement even in quoted text. To avoid interference from systemd,
+            double all percent signs (``{hostname}-{now:%Y-%m-%d_%H:%M:%S}``
+            becomes ``{hostname}-{now:%%Y-%%m-%%d_%%H:%%M:%%S}``).\n\n''')
     helptext['compression'] = textwrap.dedent('''
         Compression is lz4 by default. If you want something else, you have to specify what you want.