Merge pull request #7463 from ThomasWaldmann/docs-borg-key-file-master

BORG_KEY_FILE: clarify docs, fixes #7444

Author: ThomasWaldmann

docs/usage/general/environment.rst.inc

@@ -145,7 +145,16 @@ Directories and files:
         Defaults to ``$BORG_CONFIG_DIR/keys``.
         This directory contains keys for encrypted repositories.
     BORG_KEY_FILE
-        When set, use the given filename as repository key file.
+        When set, use the given path as repository key file. Please note that this is only
+        for rather special applications that externally fully manage the key files:
+
+        - this setting only applies to the keyfile modes (not to the repokey modes).
+        - using a full, absolute path to the key file is recommended.
+        - all directories in the given path must exist.
+        - this setting forces borg to use the key file at the given location.
+        - the key file must either exist (for most commands) or will be created (``borg rcreate``).
+        - you need to give a different path for different repositories.
+        - you need to point to the correct key file matching the repository the command will operate on.
     TMPDIR
         This is where temporary files are stored (might need a lot of temporary space for some
         operations), see tempfile_ for details.