Merge pull request #5066 from ThomasWaldmann/finefoot-p4

Update prevalence of env vars to set config and cache paths

docs/usage/general/environment.rst.inc

@@ -93,23 +93,32 @@ Some automatic "answerers" (if set, they automatically answer confirmation quest
     answer or ask you interactively, depending on whether retries are allowed (they by default are
     allowed). So please test your scripts interactively before making them a non-interactive script.
 
+.. _XDG env var: https://specifications.freedesktop.org/basedir-spec/0.6/ar01s03.html
+
 Directories and files:
     BORG_BASE_DIR
-        Defaults to '$HOME', '~$USER', '~' (in that order)'.
-        If we refer to ~ below, we in fact mean BORG_BASE_DIR.
+        Defaults to ``$HOME`` or ``~$USER`` or ``~`` (in that order).
+        If you want to move all borg-specific folders to a custom path at once, all you need to do is
+        to modify ``BORG_BASE_DIR``: the other paths for cache, config etc. will adapt accordingly
+        (assuming you didn't set them to a different custom value).
     BORG_CACHE_DIR
-        Defaults to '~/.cache/borg'. This directory contains the local cache and might need a lot
+        Defaults to ``$BORG_BASE_DIR/.cache/borg``. If ``BORG_BASE_DIR`` is not explicitly set while
+        `XDG env var`_ ``XDG_CACHE_HOME`` is set, then ``$XDG_CACHE_HOME/borg`` is being used instead.
+        This directory contains the local cache and might need a lot
         of space for dealing with big repositories. Make sure you're aware of the associated
         security aspects of the cache location: :ref:`cache_security`
     BORG_CONFIG_DIR
-        Defaults to '~/.config/borg'. This directory contains the whole config directories. See FAQ
-        for security advisory about the data in this directory: :ref:`home_config_borg`
+        Defaults to ``$BORG_BASE_DIR/.config/borg``. If ``BORG_BASE_DIR`` is not explicitly set while
+        `XDG env var`_ ``XDG_CONFIG_HOME`` is set, then ``$XDG_CONFIG_HOME/borg`` is being used instead.
+        This directory contains all borg configuration directories, see the FAQ
+        for a security advisory about the data in this directory: :ref:`home_config_borg`
     BORG_SECURITY_DIR
-        Defaults to '~/.config/borg/security'. This directory contains information borg uses to
-        track its usage of NONCES ("numbers used once" - usually in encryption context) and other
-        security relevant data. Will move with BORG_CONFIG_DIR variable unless specified.
+        Defaults to ``$BORG_CONFIG_DIR/security``.
+        This directory contains information borg uses to track its usage of NONCES ("numbers used
+        once" - usually in encryption context) and other security relevant data.
     BORG_KEYS_DIR
-        Defaults to '~/.config/borg/keys'. This directory contains keys for encrypted repositories.
+        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.
     TMPDIR

src/borg/helpers/fs.py

@@ -60,8 +60,14 @@ def get_security_dir(repository_id=None):
 
 def get_cache_dir():
     """Determine where to repository keys and cache"""
-    xdg_cache = os.environ.get('XDG_CACHE_HOME', os.path.join(get_base_dir(), '.cache'))
-    cache_dir = os.environ.get('BORG_CACHE_DIR', os.path.join(xdg_cache, 'borg'))
+    # Get cache home path
+    cache_home = os.path.join(get_base_dir(), '.cache')
+    # Try to use XDG_CACHE_HOME instead if BORG_BASE_DIR isn't explicitly set
+    if not os.environ.get('BORG_BASE_DIR'):
+        cache_home = os.environ.get('XDG_CACHE_HOME', cache_home)
+    # Use BORG_CACHE_DIR if set, otherwise assemble final path from cache home path
+    cache_dir = os.environ.get('BORG_CACHE_DIR', os.path.join(cache_home, 'borg'))
+    # Create path if it doesn't exist yet
     if not os.path.exists(cache_dir):
         os.makedirs(cache_dir)
         os.chmod(cache_dir, stat.S_IRWXU)
@@ -77,8 +83,14 @@ def get_cache_dir():
 
 def get_config_dir():
     """Determine where to store whole config"""
-    xdg_config = os.environ.get('XDG_CONFIG_HOME', os.path.join(get_base_dir(), '.config'))
-    config_dir = os.environ.get('BORG_CONFIG_DIR', os.path.join(xdg_config, 'borg'))
+    # Get config home path
+    config_home = os.path.join(get_base_dir(), '.config')
+    # Try to use XDG_CONFIG_HOME instead if BORG_BASE_DIR isn't explicitly set
+    if not os.environ.get('BORG_BASE_DIR'):
+        config_home = os.environ.get('XDG_CONFIG_HOME', config_home)
+    # Use BORG_CONFIG_DIR if set, otherwise assemble final path from config home path
+    config_dir = os.environ.get('BORG_CONFIG_DIR', os.path.join(config_home, 'borg'))
+    # Create path if it doesn't exist yet
     if not os.path.exists(config_dir):
         os.makedirs(config_dir)
         os.chmod(config_dir, stat.S_IRWXU)