Browse Source

Add a doc page on caching.

Add some explanations about how the cache is working.
Damien Goutte-Gattat 2 years ago
3 changed files with 40 additions and 1 deletions
  1. +38
  2. +1
  3. +1

+ 38
- 0
docs/caching.rst View File

@ -0,0 +1,38 @@
Pebble keeps a local cache of a vault contents within the
``$XDG_DATA_HOME/pebble`` directory. This cache allows Pebble to be used
locally without a network connection (for read operations only).
When Pebble is invoked, it checks the age of the cache (as indicated by
the cache file’s last modification time). If the cache is older than the
value indicated by the ``max_age`` setting in the :ref:`configuration
file <vault-sections>`, or if the cache file does not exists, Pebble
will then download the vault contents from the server. Otherwise it will
read the contents from the cache.
All later read operations (listing or showing credentials) will be done
using the cache, without any network access.
.. note::
The cache will never contain decrypted credentials.
Write operations (adding, editing, or deleting a credential), however,
will always be performed by contacting the server directly, the local
cache being updated afterwards. Therefore, such operations cannot be
done while offline.
Independently of the ``max_age`` setting, the cache can be forcefully
refreshed by calling Pebble with the ``-f`` or ``--refresh`` option.
Conversely, the ``--no-refresh`` option may be used to prevent
refreshing the cache even if it is older than the ``max_age`` value
(refresh will still occur if the cache does not actually exist).
Local caching for a vault can be completely disabled by setting the
``nocache`` key to ``true`` in the :ref:`configuration file
<vault-sections>`. In that case, the vault contents will only be kept in
memory and never written to disk, which implies that the contents will
have to be downloaded from the server upon each invocation.

+ 1
- 1
docs/configuration.rst View File

@ -37,7 +37,7 @@ Section types
Pebble’s configuration file may contain two types of section: *vault
sections* and *server sections*.
.. vault-sections
.. _vault-sections:
Vault sections

+ 1
- 0
docs/index.rst View File

@ -25,3 +25,4 @@ It is written in Python and should work with both Python 2.7 and Python