Add cache

This commits adds rudimentary support for a cache directory, enabled by
default. The cache directory is created if it does not exist. The cache
is used if there's anything in it, newly created snapshot and index
files are written to the cache automatically.

doc/cache.rst

@@ -0,0 +1,26 @@
+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.
+
+Versions
+--------
+
+The cache directory is selected according to the `XDG base dir specification
+<http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`__.
+Each repository has its own cache sub-directory, consting 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 and Indexes
+---------------------
+
+Snapshot, Data and Index files are cached in the sub-directories ``snapshots``,
+``data`` and  ``index``, as read from the repository.

doc/manual.rst

@@ -1240,3 +1240,19 @@ instead of the default, set the environment variable like this:
 
     $ export TMPDIR=/var/tmp/restic-tmp
     $ restic -r /tmp/backup backup ~/work
+
+Caching
+-------
+
+Restic keeps a cache with some files from the repository on the local machine.
+This allows faster operations, since meta data does not need to be loaded from
+a remote repository. The cache is automatically created, usually in the
+directory ``.cache/restic`` in the user's home directory. The environment
+variable ``XDG_CACHE_DIR`` or the command line parameter ``--cache-dir`` can
+each be used to specify where the cache is located. The parameter
+``--no-cache`` disables the cache entirely. In this case, all data is loaded
+from the repo.
+
+The cache is ephemeral: When a file cannot be read from the cache, it is loaded
+from the repository.
+

doc/references.rst

@@ -7,3 +7,7 @@ References
 ------------------------
 
 .. include:: rest_backend.rst
+
+------------------------
+
+.. include:: cache.rst