diff --git a/docs/faq.rst b/docs/faq.rst
index ae2104229..4029cff70 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -323,7 +323,7 @@ Using ``BORG_PASSCOMMAND`` with a properly permissioned file
 
   Then in an automated script one can put::
 
-    export BORG_PASSCOMMAND="cat ~/.borg-passphrase"
+    export BORG_PASSCOMMAND="cat $HOME/.borg-passphrase"
 
   and Borg will automatically use that passphrase.
 
diff --git a/docs/man/borg.1 b/docs/man/borg.1
index 03e324faf..5e89a2ebd 100644
--- a/docs/man/borg.1
+++ b/docs/man/borg.1
@@ -393,7 +393,8 @@ See also BORG_NEW_PASSPHRASE.
 When set, use the standard output of the command (trailing newlines are stripped) to answer the
 passphrase question for encrypted repositories.
 It is used when a passphrase is needed to access an encrypted repo as well as when a new
-passphrase should be initially set when initializing an encrypted repo.
+passphrase should be initially set when initializing an encrypted repo. Note that the command
+is executed without a shell. So variables, like \fB$HOME\fP\ will work, but \fB~\fP\ won't.
 If BORG_PASSPHRASE is also set, it takes precedence.
 See also BORG_NEW_PASSPHRASE.
 .TP
diff --git a/docs/usage_general.rst.inc b/docs/usage_general.rst.inc
index 7f7aff024..9ab1f5933 100644
--- a/docs/usage_general.rst.inc
+++ b/docs/usage_general.rst.inc
@@ -171,7 +171,8 @@ General:
         When set, use the standard output of the command (trailing newlines are stripped) to answer the
         passphrase question for encrypted repositories.
         It is used when a passphrase is needed to access an encrypted repo as well as when a new
-        passphrase should be initially set when initializing an encrypted repo.
+        passphrase should be initially set when initializing an encrypted repo. Note that the command
+        is executed without a shell. So variables, like ``$HOME`` will work, but ``~`` won't.
         If BORG_PASSPHRASE is also set, it takes precedence.
         See also BORG_NEW_PASSPHRASE.
     BORG_PASSPHRASE_FD