Merge pull request #2998 from greatroar/env-docs

Systematize documentation of environment variables

doc/040_backup.rst

@@ -433,6 +433,8 @@ environment variables. The following lists these environment variables:
     RESTIC_CACHE_DIR                    Location of the cache directory
     RESTIC_PROGRESS_FPS                 Frames per second by which the progress bar is updated
 
+    TMPDIR                              Location for temporary files
+
     AWS_ACCESS_KEY_ID                   Amazon S3 access key ID
     AWS_SECRET_ACCESS_KEY               Amazon S3 secret access key
     AWS_DEFAULT_REGION                  Amazon S3 default region
@@ -470,12 +472,12 @@ environment variables. The following lists these environment variables:
 
     RCLONE_BWLIMIT                      rclone bandwidth limit
 
-In addition to restic-specific environment variables, the following system-wide environment variables
-are taken into account for various operations:
+See :ref:`caching` for the rules concerning cache locations when
+``RESTIC_CACHE_DIR`` is not set.
 
- * ``$XDG_CACHE_HOME/restic``, ``$HOME/.cache/restic``: :ref:`caching`.
- * ``$TMPDIR``: :ref:`temporary_files`.
- * ``$PATH/fusermount``: Binary for ``restic mount``.
+The external programs that restic may execute include ``rclone`` (for rclone
+backends) and ``ssh`` (for the SFTP backend). These may respond to further
+environment variables and configuration files; see their respective manuals.
 
 
 Exit status codes

doc/050_restore.rst

@@ -71,10 +71,11 @@ command to serve the repository with FUSE:
     Now serving /srv/restic-repo at /mnt/restic
     When finished, quit with Ctrl-c or umount the mountpoint.
 
-Mounting repositories via FUSE is not possible on OpenBSD, Solaris/illumos
-and Windows. For Linux, the ``fuse`` kernel module needs to be loaded. For
-FreeBSD, you may need to install FUSE and load the kernel module (``kldload
-fuse``).
+Mounting repositories via FUSE is only possible on Linux, macOS and FreeBSD.
+On Linux, the ``fuse`` kernel module needs to be loaded and the ``fusermount``
+command needs to be in the ``PATH``. On macOS, you need `FUSE for macOS
+<https://osxfuse.github.io/>`__. On FreeBSD, you may need to install FUSE
+and load the kernel module (``kldload fuse``).
 
 Restic supports storage and preservation of hard links. However, since
 hard links exist in the scope of a filesystem by definition, restoring

doc/cache.rst

@@ -3,23 +3,13 @@ Local Cache
 ***********
 
 In order to speed up certain operations, restic manages a local cache of data.
-This document describes the data structures for the local cache with version 1.
+The location of the cache directory depends on the operating system and the
+environment; see :ref:`caching`.
 
-Versions
-========
-
-The cache directory is selected according to the `XDG base dir specification
-<https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`__.
 Each repository has its own cache sub-directory, consisting of the repository ID
 which is chosen at ``init``. All cache directories for different repos are
 independent of each other.
 
-The cache dir for a repo contains a file named ``version``, which contains a
-single ASCII integer line that stands for the current version of the cache. If
-a lower version number is found the cache is recreated with the current
-version. If a higher version number is found the cache is ignored and left as
-is.
-
 Snapshots, Data and Indexes
 ===========================
 

doc/manual_rest.rst

@@ -399,10 +399,14 @@ This allows faster operations, since meta data does not need to be loaded from
 a remote repository. The cache is automatically created, usually in an
 OS-specific cache folder:
 
- * Linux/other: ``~/.cache/restic`` (or ``$XDG_CACHE_HOME/restic``)
+ * Linux/other: ``$XDG_CACHE_HOME/restic``, or ``~/.cache/restic`` if
+   ``XDG_CACHE_HOME`` is not set
  * macOS: ``~/Library/Caches/restic``
  * Windows: ``%LOCALAPPDATA%/restic``
 
+If the relevant environment variables are not set, restic exits with an error
+message.
+
 The command line parameter ``--cache-dir`` or the environment variable
 ``$RESTIC_CACHE_DIR`` can be used to override the default cache location.  The
 parameter ``--no-cache`` disables the cache entirely. In this case, all data