From fc2798fc31a08997c049f609c19dd4ab8d75964e Mon Sep 17 00:00:00 2001
From: "Kay-Uwe (Kiwi) Lorenz" <kiwi@moduleworks.com>
Date: Sun, 7 Mar 2021 15:13:52 +0100
Subject: fix: make secret helper more user friendly

---
 docs/cli-usage.rst | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/cli-usage.rst b/docs/cli-usage.rst
index 71c8577..c27e6c5 100644
--- a/docs/cli-usage.rst
+++ b/docs/cli-usage.rst
@@ -48,7 +48,7 @@ example:
 
    [elsewhere]
    url = http://else.whe.re:8080
-   private_token = lookup: pass show path/to/password | head -n1
+   private_token = helper: path/to/helper.sh
    timeout = 1
 
 The ``default`` option of the ``[global]`` section defines the GitLab server to
@@ -119,6 +119,27 @@ server, with very limited permissions.
    * - ``http_password``
      - Password for optional HTTP authentication
 
+For all settings, which contain secrets (``http_password``, 
+``personal_token``, ``oauth_token``, ``job_token``), you can specify
+a helper program to retrieve the secret indicated by ``helper:`` 
+prefix.  You can only specify a path to a program without any 
+parameters.  It is expected, that the program prints the secret to 
+standard output.
+
+Example for a `keyring <https://github.com/jaraco/keyring>`_ helper:
+
+.. code-block:: bash
+
+    #!/bin/bash
+    keyring get Service Username
+
+Example for a `pass <https://www.passwordstore.org>`_ helper:
+
+.. code-block:: bash
+
+    #!/bin/bash
+    pass show path/to/password | head -n 1
+
 CLI
 ===
 
-- 
cgit v1.2.1