Update docs

doc/010_introduction.rst

@@ -14,3 +14,6 @@
 Introduction
 ############
 
+Restic is a fast and secure backup program. In the following sections, we will
+present typical workflows, starting with installing, preparing a new
+repository, and making the first backup.

doc/020_installation.rst

@@ -145,9 +145,17 @@ Admin rights.
 Docker Container
 ****************
 
+We're maintaining a bare docker container with just a few files and the restic
+binary, you can get it with `docker pull` like this:
+
+.. code-block:: console
+
+    $ docker pull restic/restic
+
 .. note::
-   | A docker container is available as a contribution (Thank you!).
+   | Another docker container which offers more configuration options is
-   | You can find it at https://github.com/Lobaro/restic-backup-docker
+   | available as a contribution (Thank you!). You can find it at
+   | https://github.com/Lobaro/restic-backup-docker
 
 From Source
 ***********
@@ -173,7 +181,7 @@ You can easily cross-compile restic for all supported platforms, just
 supply the target OS and platform via the command-line options like this
 (for Windows and FreeBSD respectively):
 
-::
+.. code-block:: console
 
     $ go run build.go --goos windows --goarch amd64
 

doc/030_preparing_a_new_repo.rst

@@ -15,20 +15,24 @@ Preparing a new repository
 ##########################
 
 The place where your backups will be saved at is called a "repository".
-This chapter explains how to create ("init") such a repository.
+This chapter explains how to create ("init") such a repository. The repository
+can be stored locally, or on some remote server or service. We'll first cover
+using a local repository, the remaining sections of this chapter cover all the
+other options. You can skip to the next chapter once you've read the relevant
+section here.
 
 Local
 *****
 
-In order to create a repository at ``/tmp/backup``, run the following
+In order to create a repository at ``/srv/restic-repo``, run the following
 command and enter the same password twice:
 
 .. code-block:: console
 
-    $ restic init --repo /tmp/backup
+    $ restic init --repo /srv/restic-repo
     enter password for new backend:
     enter password again:
-    created restic backend 085b3c76b9 at /tmp/backup
+    created restic backend 085b3c76b9 at /srv/restic-repo
     Please note that knowledge of your password is required to access the repository.
     Losing your password means that your data is irrecoverably lost.
 
@@ -55,10 +59,10 @@ simply be achieved by changing the URL scheme in the ``init`` command:
 
 .. code-block:: console
 
-    $ restic -r sftp:user@host:/tmp/backup init
+    $ restic -r sftp:user@host:/srv/restic-repo init
     enter password for new backend:
     enter password again:
-    created restic backend f1c6108821 at sftp:user@host:/tmp/backup
+    created restic backend f1c6108821 at sftp:user@host:/srv/restic-repo
     Please note that knowledge of your password is required to access the repository.
     Losing your password means that your data is irrecoverably lost.
 
@@ -87,7 +91,7 @@ specify the user name in this case):
 
 ::
 
-    $ restic -r sftp:foo:/tmp/backup init
+    $ restic -r sftp:foo:/srv/restic-repo init
 
 You can also add an entry with a special host name which does not exist,
 just for use with restic, and use the ``Hostname`` option to set the
@@ -104,7 +108,7 @@ Then use it in the backend specification:
 
 ::
 
-    $ restic -r sftp:restic-backup-host:/tmp/backup init
+    $ restic -r sftp:restic-backup-host:/srv/restic-repo init
 
 Last, if you'd like to use an entirely different program to create the
 SFTP connection, you can specify the command to be run with the option
@@ -509,5 +513,5 @@ On MSYS2, you can install ``winpty`` as follows:
 .. code-block:: console
 
     $ pacman -S winpty
-    $ winpty restic -r /tmp/backup init
+    $ winpty restic -r /srv/restic-repo init
 

doc/040_backup.rst

@@ -21,43 +21,88 @@ again:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup backup ~/work
+    $ restic -r /srv/restic-repo --verbose backup ~/work
+    open repository
     enter password for repository:
-    scan [/home/user/work]
+    password is correct
-    scanned 764 directories, 1816 files in 0:00
+    lock repository
-    [0:29] 100.00%  54.732 MiB/s  1.582 GiB / 1.582 GiB  2580 / 2580 items  0 errors  ETA 0:00
+    load index files
-    duration: 0:29, 54.47MiB/s
+    start scan
+    start backup
+    scan finished in 1.837s
+    processed 1.720 GiB in 0:12
+    Files:        5307 new,     0 changed,     0 unmodified
+    Dirs:         1867 new,     0 changed,     0 unmodified
+    Added:      1.700 GiB
     snapshot 40dc1520 saved
 
 As you can see, restic created a backup of the directory and was pretty
 fast! The specific snapshot just created is identified by a sequence of
 hexadecimal characters, ``40dc1520`` in this case.
 
+If you don't pass the ``--verbose`` option, restic will print less data (but
+you'll still get a nice live status display).
+
 If you run the command again, restic will create another snapshot of
 your data, but this time it's even faster. This is de-duplication at
 work!
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup backup ~/work
+    $ restic -r /srv/restic-repo backup --verbose ~/work
+    open repository
     enter password for repository:
-    using parent snapshot 40dc1520aa6a07b7b3ae561786770a01951245d2367241e71e9485f18ae8228c
+    password is correct
-    scan [/home/user/work]
+    lock repository
-    scanned 764 directories, 1816 files in 0:00
+    load index files
-    [0:00] 100.00%  0B/s  1.582 GiB / 1.582 GiB  2580 / 2580 items  0 errors  ETA 0:00
+    using parent snapshot d875ae93
-    duration: 0:00, 6572.38MiB/s
+    start scan
+    start backup
+    scan finished in 1.881s
+    processed 1.720 GiB in 0:03
+    Files:           0 new,     0 changed,  5307 unmodified
+    Dirs:            0 new,     0 changed,  1867 unmodified
+    Added:      0 B
     snapshot 79766175 saved
 
-You can even backup individual files in the same repository.
+You can even backup individual files in the same repository (not passing
+``--verbose`` means less output):
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup backup ~/work.txt
+    $ restic -r /srv/restic-repo backup ~/work.txt
-    scan [/home/user/work.txt]
+    enter password for repository:
-    scanned 0 directories, 1 files in 0:00
+    password is correct
-    [0:00] 100.00%  0B/s  220B / 220B  1 / 1 items  0 errors  ETA 0:00
+    snapshot 249d0210 saved
-    duration: 0:00, 0.03MiB/s
+
-    snapshot 31f7bd63 saved
+If you're interested in what restic does, pass ``--verbose`` twice (or
+``--verbose 2``) to display detailed information about each file and directory
+restic encounters:
+
+.. code-block:: console
+
+    $ echo 'more data foo bar' >> ~/work.txt
+
+    $ restic -r /srv/restic-repo backup --verbose --verbose ~/work.txt
+    open repository
+    enter password for repository:
+    password is correct
+    lock repository
+    load index files
+    using parent snapshot f3f8d56b
+    start scan
+    start backup
+    scan finished in 2.115s
+    modified  /home/user/work.txt, saved in 0.007s (22 B added)
+    modified  /home/user/, saved in 0.008s (0 B added, 378 B metadata)
+    modified  /home/, saved in 0.009s (0 B added, 375 B metadata)
+    processed 22 B in 0:02
+    Files:           0 new,     1 changed,     0 unmodified
+    Dirs:            0 new,     2 changed,     0 unmodified
+    Data Blobs:      1 new
+    Tree Blobs:      3 new
+    Added:      1.116 KiB
+    snapshot 8dc503fc saved
 
 In fact several hosts may use the same repository to backup directories
 and files leading to a greater de-duplication.
@@ -87,33 +132,53 @@ the exclude options are:
 -  ``--exclude-if-present`` Specified one or more times to exclude a folders content
    if it contains a given file (optionally having a given header)
 
-Basic example:
+ Let's say we have a file called ``excludes.txt`` with the following content:
 
-.. code-block:: console
+::
-
-    $ cat exclude
     # exclude go-files
     *.go
     # exclude foo/x/y/z/bar foo/x/bar foo/bar
     foo/**/bar
-    $ restic -r /tmp/backup backup ~/work --exclude="*.c" --exclude-file=exclude
+
+It can be used like this:
+
+.. code-block:: console
+
+    $ restic -r /srv/restic-repo backup ~/work --exclude="*.c" --exclude-file=excludes.txt
+
+This instruct restic to exclude files matching the following criteria:
+
+ * All files matching ``*.go`` (second line in ``excludes.txt``)
+ * All files and sub-directories named ``bar`` which reside somewhere below a directory called ``foo`` (fourth line in ``excludes.txt``)
+ * All files matching ``*.c`` (parameter ``--exclude``)
 
 Please see ``restic help backup`` for more specific information about each exclude option.
 
 Patterns use `filepath.Glob <https://golang.org/pkg/path/filepath/#Glob>`__ internally,
-see `filepath.Match <https://golang.org/pkg/path/filepath/#Match>`__ for syntax.
+see `filepath.Match <https://golang.org/pkg/path/filepath/#Match>`__ for
-Patterns are tested against the full path of a file/dir to be saved, not only
+syntax. Patterns are tested against the full path of a file/dir to be saved,
-against the relative path below the argument given to restic backup.
+even if restic is passed a relative path to save. Environment-variables in
-Patterns need to match on complete path components. (``foo`` matches
+exclude-files are expanded with `os.ExpandEnv <https://golang.org/pkg/os/#ExpandEnv>`__.
-``/dir1/foo/dir2/file`` and ``/dir/foo`` but does not match ``/dir/foobar`` or
+
-``barfoo``.) A trailing ``/`` is ignored. A leading ``/`` anchors the
+Patterns need to match on complete path components. For example, the pattern ``foo``:
-pattern at the root directory. (``/bin`` matches ``/bin/bash`` but does not
+
-match ``/usr/bin/restic``.) Regular wildcards cannot be used to match over the
+ * matches ``/dir1/foo/dir2/file`` and ``/dir/foo``
-directory separator ``/``. (``b*ash`` matches ``/bin/bash`` but does not match
+ * does not match ``/dir/foobar`` or ``barfoo``
-``/bin/ash``.) However ``**`` matches arbitrary subdirectories. (``foo/**/bar``
+   
-matches ``/dir1/foo/dir2/bar/file``, ``/foo/bar/file`` and ``/tmp/foo/bar``.)
+A trailing ``/`` is ignored, a leading ``/`` anchors the
-Environment-variables in exclude-files are expanded with
+pattern at the root directory. This means, ``/bin`` matches ``/bin/bash`` but
-`os.ExpandEnv <https://golang.org/pkg/os/#ExpandEnv>`__.
+does not match ``/usr/bin/restic``.
+
+Regular wildcards cannot be used to match over the
+directory separator ``/``. For example: ``b*ash`` matches ``/bin/bash`` but does not match
+``/bin/ash``.
+
+For this, the special wildcard ``**`` can be used to match arbitrary
+sub-directories: The pattern ``foo/**/bar`` matches:
+
+ * ``/dir1/foo/dir2/bar/file``
+ * ``/foo/bar/file`` 
+ * ``/tmp/foo/bar``
 
 By specifying the option ``--one-file-system`` you can instruct restic
 to only backup files from the file systems the initially specified files
@@ -122,15 +187,15 @@ backup ``/sys`` or ``/dev`` on a Linux system:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup backup --one-file-system /
+    $ restic -r /srv/restic-repo backup --one-file-system /
 
 By using the ``--files-from`` option you can read the files you want to
 backup from a file. This is especially useful if a lot of files have to
 be backed up that are not in the same folder or are maybe pre-filtered
 by other software.
 
-For example maybe you want to backup files that have a certain filename
+For example maybe you want to backup files which have a name that matches a
-in them:
+certain pattern:
 
 .. code-block:: console
 
@@ -140,14 +205,14 @@ You can then use restic to backup the filtered files:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup backup --files-from /tmp/files_to_backup
+    $ restic -r /srv/restic-repo backup --files-from /tmp/files_to_backup
 
 Incidentally you can also combine ``--files-from`` with the normal files
 args:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup backup --files-from /tmp/files_to_backup /tmp/some_additional_file
+    $ restic -r /srv/restic-repo backup --files-from /tmp/files_to_backup /tmp/some_additional_file
 
 Paths in the listing file can be absolute or relative.
 
@@ -159,7 +224,7 @@ and displays a small statistic, just pass the command two snapshot IDs:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup diff 5845b002 2ab627a6
+    $ restic -r /srv/restic-repo diff 5845b002 2ab627a6
     password is correct
     comparing snapshot ea657ce5 to 2ab627a6:
 
@@ -206,7 +271,7 @@ this mode of operation, just supply the option ``--stdin`` to the
 
 .. code-block:: console
 
-    $ mysqldump [...] | restic -r /tmp/backup backup --stdin
+    $ mysqldump [...] | restic -r /srv/restic-repo backup --stdin
 
 This creates a new snapshot of the output of ``mysqldump``. You can then
 use e.g. the fuse mounting option (see below) to mount the repository
@@ -217,7 +282,7 @@ specified with ``--stdin-filename``, e.g. like this:
 
 .. code-block:: console
 
-    $ mysqldump [...] | restic -r /tmp/backup backup --stdin --stdin-filename production.sql
+    $ mysqldump [...] | restic -r /srv/restic-repo backup --stdin --stdin-filename production.sql
 
 Tags for backup
 ***************
@@ -227,7 +292,7 @@ information. Just specify the tags for a snapshot one by one with ``--tag``:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup backup --tag projectX --tag foo --tag bar ~/work
+    $ restic -r /srv/restic-repo backup --tag projectX --tag foo --tag bar ~/work
     [...]
 
 The tags can later be used to keep (or forget) snapshots with the ``forget``

doc/045_working_with_repos.rst

@@ -22,7 +22,7 @@ Now, you can list all the snapshots stored in the repository:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup snapshots
+    $ restic -r /srv/restic-repo snapshots
     enter password for repository:
     ID        Date                 Host    Tags   Directory
     ----------------------------------------------------------------------
@@ -36,7 +36,7 @@ You can filter the listing by directory path:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup snapshots --path="/srv"
+    $ restic -r /srv/restic-repo snapshots --path="/srv"
     enter password for repository:
     ID        Date                 Host    Tags   Directory
     ----------------------------------------------------------------------
@@ -47,7 +47,7 @@ Or filter by host:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup snapshots --host luigi
+    $ restic -r /srv/restic-repo snapshots --host luigi
     enter password for repository:
     ID        Date                 Host    Tags   Directory
     ----------------------------------------------------------------------
@@ -74,7 +74,7 @@ backup data is consistent and the integrity is unharmed:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup check
+    $ restic -r /srv/restic-repo check
     Load indexes
     ciphertext verification failed
 
@@ -83,7 +83,7 @@ yield the same error:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup restore 79766175 --target /tmp/restore-work
+    $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore-work
     Load indexes
     ciphertext verification failed
 
@@ -93,7 +93,7 @@ data files:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup check --read-data
+    $ restic -r /srv/restic-repo check --read-data
     load indexes
     check all packs
     check snapshots, trees and blobs
@@ -107,9 +107,9 @@ commands check all repository data files over 5 separate invocations:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup check --read-data-subset=1/5
+    $ restic -r /srv/restic-repo check --read-data-subset=1/5
-    $ restic -r /tmp/backup check --read-data-subset=2/5
+    $ restic -r /srv/restic-repo check --read-data-subset=2/5
-    $ restic -r /tmp/backup check --read-data-subset=3/5
+    $ restic -r /srv/restic-repo check --read-data-subset=3/5
-    $ restic -r /tmp/backup check --read-data-subset=4/5
+    $ restic -r /srv/restic-repo check --read-data-subset=4/5
-    $ restic -r /tmp/backup check --read-data-subset=5/5
+    $ restic -r /srv/restic-repo check --read-data-subset=5/5
 

doc/050_restore.rst

@@ -23,7 +23,7 @@ command to restore the contents of the latest snapshot to
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup restore 79766175 --target /tmp/restore-work
+    $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore-work
     enter password for repository:
     restoring <Snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST> to /tmp/restore-work
 
@@ -33,7 +33,7 @@ backup for a specific host, path or both.
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup restore latest --target /tmp/restore-art --path "/home/art" --host luigi
+    $ restic -r /srv/restic-repo restore latest --target /tmp/restore-art --path "/home/art" --host luigi
     enter password for repository:
     restoring <Snapshot of [/home/art] at 2015-05-08 21:45:17.884408621 +0200 CEST> to /tmp/restore-art
 
@@ -42,7 +42,7 @@ files in the snapshot. For example, to restore a single file:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup restore 79766175 --target /tmp/restore-work --include /work/foo
+    $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore-work --include /work/foo
     enter password for repository:
     restoring <Snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST> to /tmp/restore-work
 
@@ -58,9 +58,9 @@ command to serve the repository with FUSE:
 .. code-block:: console
 
     $ mkdir /mnt/restic
-    $ restic -r /tmp/backup mount /mnt/restic
+    $ restic -r /srv/restic-repo mount /mnt/restic
     enter password for repository:
-    Now serving /tmp/backup at /mnt/restic
+    Now serving /srv/restic-repo at /mnt/restic
     Don't forget to umount after quitting!
 
 Mounting repositories via FUSE is not possible on OpenBSD, Solaris/illumos
@@ -80,4 +80,4 @@ the data directly. This can be achieved by using the `dump` command, like this:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup dump latest production.sql | mysql
+    $ restic -r /srv/restic-repo dump latest production.sql | mysql

doc/060_forget.rst

@@ -35,7 +35,7 @@ repository like this:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup snapshots
+    $ restic -r /srv/restic-repo snapshots
     enter password for repository:
     ID        Date                 Host      Tags  Directory
     ----------------------------------------------------------------------
@@ -50,7 +50,7 @@ command and specify the snapshot ID on the command line:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup forget bdbd3439
+    $ restic -r /srv/restic-repo forget bdbd3439
     enter password for repository:
     removed snapshot d3f01f63
 
@@ -58,7 +58,7 @@ Afterwards this snapshot is removed:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup snapshots
+    $ restic -r /srv/restic-repo snapshots
     enter password for repository:
     ID        Date                 Host     Tags  Directory
     ----------------------------------------------------------------------
@@ -73,7 +73,7 @@ command must be run:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup prune
+    $ restic -r /srv/restic-repo prune
     enter password for repository:
 
     counting files in repo

doc/070_encryption.rst

@@ -16,8 +16,8 @@ Encryption
 
 
 *"The design might not be perfect, but it’s good. Encryption is a first-class feature,
-the implementation looks sane and I guess the deduplication trade-off is worth it. So… I’m going to use restic for 
+the implementation looks sane and I guess the deduplication trade-off is worth
-my personal backups.*" `Filippo Valsorda`_
+it. So… I’m going to use restic for my personal backups.*" `Filippo Valsorda`_
 
 .. _Filippo Valsorda: https://blog.filippo.io/restic-cryptography/
 
@@ -31,19 +31,19 @@ per repository. In fact, you can use the ``list``, ``add``, ``remove``, and
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup key list
+    $ restic -r /srv/restic-repo key list
     enter password for repository:
      ID          User        Host        Created
     ----------------------------------------------------------------------
     *eb78040b    username    kasimir   2015-08-12 13:29:57
 
-    $ restic -r /tmp/backup key add
+    $ restic -r /srv/restic-repo key add
     enter password for repository:
     enter password for new key:
     enter password again:
     saved new key as <Key of username@kasimir, created on 2015-08-12 13:35:05.316831933 +0200 CEST>
 
-    $ restic -r backup key list
+    $ restic -r /srv/restic-repo key list
     enter password for repository:
      ID          User        Host        Created
     ----------------------------------------------------------------------

doc/075_scripting.rst

@@ -26,10 +26,10 @@ times. The command ``snapshots`` may be used for this purpose:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup snapshots
+    $ restic -r /srv/restic-repo snapshots
-    Fatal: unable to open config file: Stat: stat /tmp/backup/config: no such file or directory
+    Fatal: unable to open config file: Stat: stat /srv/restic-repo/config: no such file or directory
     Is there a repository at the following location?
-    /tmp/backup
+    /srv/restic-repo
 
 If a repository does not exist, restic will return a non-zero exit code
 and print an error message. Note that restic will also return a non-zero

doc/100_references.rst

@@ -625,14 +625,15 @@ are deleted, the particular snapshot vanished and all snapshots
 depending on data that has been added in the snapshot cannot be restored
 completely. Restic is not designed to detect this attack.
 
+******
 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>`__.
@@ -646,12 +647,21 @@ 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
+Snapshots, Data and Indexes
----------------------
+===========================
 
 Snapshot, Data and Index files are cached in the sub-directories ``snapshots``,
 ``data`` and  ``index``, as read from the repository.
 
+Expiry
+======
+
+Whenever a cache directory for a repo is used, that directory's modification
+timestamp is updated to the current time. By looking at the modification
+timestamps of the repo cache directories it is easy to decide which directories
+are old and haven't been used in a long time. Those are probably stale and can
+be removed.
+
 
 ************
 REST Backend
@@ -798,24 +808,3 @@ Returns "200 OK" if the blob with the given name and type has been
 deleted from the repository, an HTTP error otherwise.
 
 
-*****
-Talks
-*****
-
-The following talks will be or have been given about restic:
-
--  2016-01-31: Lightning Talk at the Go Devroom at FOSDEM 2016,
-   Brussels, Belgium
--  2016-01-29: `restic - Backups mal
-   richtig <https://media.ccc.de/v/c4.openchaos.2016.01.restic>`__:
-   Public lecture in German at `CCC Cologne
-   e.V. <https://koeln.ccc.de>`__ in Cologne, Germany
--  2015-08-23: `A Solution to the Backup
-   Inconvenience <https://programm.froscon.de/2015/events/1515.html>`__:
-   Lecture at `FROSCON 2015 <https://www.froscon.de>`__ in Bonn, Germany
--  2015-02-01: `Lightning Talk at FOSDEM
-   2015 <https://www.youtube.com/watch?v=oM-MfeflUZ8&t=11m40s>`__: A
-   short introduction (with slightly outdated command line)
--  2015-01-27: `Talk about restic at CCC
-   Aachen <https://videoag.fsmpi.rwth-aachen.de/?view=player&lectureid=4442#content>`__
-   (in German)

doc/110_talks.rst

@@ -0,0 +1,34 @@
+..
+  Normally, there are no heading levels assigned to certain characters as the structure is
+  determined from the succession of headings. However, this convention is used in Python’s
+  Style Guide for documenting which you may follow:
+
+  # with overline, for parts
+  * for chapters
+  = for sections
+  - for subsections
+  ^ for subsubsections
+  " for paragraphs
+
+
+#####
+Talks
+#####
+
+The following talks will be or have been given about restic:
+
+-  2016-01-31: Lightning Talk at the Go Devroom at FOSDEM 2016,
+   Brussels, Belgium
+-  2016-01-29: `restic - Backups mal
+   richtig <https://media.ccc.de/v/c4.openchaos.2016.01.restic>`__:
+   Public lecture in German at `CCC Cologne
+   e.V. <https://koeln.ccc.de>`__ in Cologne, Germany
+-  2015-08-23: `A Solution to the Backup
+   Inconvenience <https://programm.froscon.de/2015/events/1515.html>`__:
+   Lecture at `FROSCON 2015 <https://www.froscon.de>`__ in Bonn, Germany
+-  2015-02-01: `Lightning Talk at FOSDEM
+   2015 <https://www.youtube.com/watch?v=oM-MfeflUZ8&t=11m40s>`__: A
+   short introduction (with slightly outdated command line)
+-  2015-01-27: `Talk about restic at CCC
+   Aachen <https://videoag.fsmpi.rwth-aachen.de/?view=player&lectureid=4442#content>`__
+   (in German)

doc/cache.rst

@@ -1,36 +0,0 @@
-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, Data and Indexes
----------------------------
-
-Snapshot, Data and Index files are cached in the sub-directories ``snapshots``,
-``data`` and  ``index``, as read from the repository.
-
-Expiry
-------
-
-Whenever a cache directory for a repo is used, that directory's modification
-timestamp is updated to the current time. By looking at the modification
-timestamps of the repo cache directories it is easy to decide which directories
-are old and haven't been used in a long time. Those are probably stale and can
-be removed.
-

doc/conf.py

@@ -35,7 +35,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'restic'
-copyright = '2017, restic authors'
+copyright = '2018, restic authors'
 author = 'fd0'
 
 # The version info for the project you're documenting, acts as replacement for

doc/index.rst

@@ -16,5 +16,6 @@ Restic Documentation
    080_examples
    090_participating
    100_references
+   110_talks
    faq
    manual_rest

doc/manual_rest.rst

@@ -19,6 +19,7 @@ Usage help is available:
       backup        Create a new backup of files and/or directories
       cat           Print internal objects to stdout
       check         Check the repository for errors
+      diff          Show differences between two snapshots
       dump          Print a backed-up file to stdout
       find          Find a file or directory
       forget        Remove snapshots from the repository
@@ -39,24 +40,24 @@ Usage help is available:
       version       Print version information
 
     Flags:
-          --cacert stringSlice      path to load root certificates from (default: use system certificates)
+          --cacert stringSlice       path to load root certificates from (default: use system certificates)
-          --cache-dir string        set the cache directory
+          --cache-dir string         set the cache directory
-      -h, --help                    help for restic
+          --cleanup-cache            auto remove old cache directories
-          --json                    set output mode to JSON for commands that support it
+      -h, --help                     help for restic
-          --limit-download int      limits downloads to a maximum rate in KiB/s. (default: unlimited)
+          --json                     set output mode to JSON for commands that support it
-          --limit-upload int        limits uploads to a maximum rate in KiB/s. (default: unlimited)
+          --limit-download int       limits downloads to a maximum rate in KiB/s. (default: unlimited)
-          --no-cache                do not use a local cache
+          --limit-upload int         limits uploads to a maximum rate in KiB/s. (default: unlimited)
-          --no-lock                 do not lock the repo, this allows some operations on read-only repos
+          --no-cache                 do not use a local cache
-      -o, --option key=value        set extended option (key=value, can be specified multiple times)
+          --no-lock                  do not lock the repo, this allows some operations on read-only repos
-      -p, --password-file string    read the repository password from a file (default: $RESTIC_PASSWORD_FILE)
+      -o, --option key=value         set extended option (key=value, can be specified multiple times)
-      -q, --quiet                   do not output comprehensive progress report
+      -p, --password-file string     read the repository password from a file (default: $RESTIC_PASSWORD_FILE)
-      -r, --repo string             repository to backup to or restore from (default: $RESTIC_REPOSITORY)
+      -q, --quiet                    do not output comprehensive progress report
+      -r, --repo string              repository to backup to or restore from (default: $RESTIC_REPOSITORY)
           --tls-client-cert string   path to a file containing PEM encoded TLS client certificate and private key
-
+      -v, --verbose count[=-1]       be verbose (can be specified multiple times)
 
     Use "restic [command] --help" for more information about a command.
 
-
 Similar to programs such as ``git``, restic has a number of
 sub-commands. You can see these commands in the listing above. Each
 sub-command may have own command-line options, and there is a help
@@ -87,21 +88,23 @@ command:
           --stdin-filename string            file name to use when reading from stdin (default "stdin")
           --tag tag                          add a tag for the new snapshot (can be specified multiple times)
           --time string                      time of the backup (ex. '2012-11-01 22:08:41') (default: now)
+          --with-atime                       store the atime for all files and directories
 
     Global Flags:
-          --cacert stringSlice      path to load root certificates from (default: use system certificates)
+          --cacert stringSlice       path to load root certificates from (default: use system certificates)
-          --cache-dir string        set the cache directory
+          --cache-dir string         set the cache directory
-          --json                    set output mode to JSON for commands that support it
+          --cleanup-cache            auto remove old cache directories
-          --limit-download int      limits downloads to a maximum rate in KiB/s. (default: unlimited)
+          --json                     set output mode to JSON for commands that support it
-          --limit-upload int        limits uploads to a maximum rate in KiB/s. (default: unlimited)
+          --limit-download int       limits downloads to a maximum rate in KiB/s. (default: unlimited)
-          --no-cache                do not use a local cache
+          --limit-upload int         limits uploads to a maximum rate in KiB/s. (default: unlimited)
-          --no-lock                 do not lock the repo, this allows some operations on read-only repos
+          --no-cache                 do not use a local cache
-      -o, --option key=value        set extended option (key=value, can be specified multiple times)
+          --no-lock                  do not lock the repo, this allows some operations on read-only repos
-      -p, --password-file string    read the repository password from a file (default: $RESTIC_PASSWORD_FILE)
+      -o, --option key=value         set extended option (key=value, can be specified multiple times)
-      -q, --quiet                   do not output comprehensive progress report
+      -p, --password-file string     read the repository password from a file (default: $RESTIC_PASSWORD_FILE)
-      -r, --repo string             repository to backup to or restore from (default: $RESTIC_REPOSITORY)
+      -q, --quiet                    do not output comprehensive progress report
-          --tls-client-cert string  path to a TLS client certificate
+      -r, --repo string              repository to backup to or restore from (default: $RESTIC_REPOSITORY)
-          --tls-client-key string   path to a TLS client certificate key
+          --tls-client-cert string   path to a file containing PEM encoded TLS client certificate and private key
+      -v, --verbose n[=-1]           be verbose (specify --verbose multiple times or level n)
 
 Subcommand that support showing progress information such as ``backup``,
 ``check`` and ``prune`` will do so unless the quiet flag ``-q`` or
@@ -128,7 +131,7 @@ command does that:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup tag --set NL --set CH 590c8fc8
+    $ restic -r /srv/restic-repo tag --set NL --set CH 590c8fc8
     create exclusive lock for repository
     modified tags on 1 snapshots
 
@@ -141,19 +144,19 @@ So we can add and remove tags incrementally like this:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup tag --tag NL --remove CH
+    $ restic -r /srv/restic-repo tag --tag NL --remove CH
     create exclusive lock for repository
     modified tags on 1 snapshots
 
-    $ restic -r /tmp/backup tag --tag NL --add UK
+    $ restic -r /srv/restic-repo tag --tag NL --add UK
     create exclusive lock for repository
     modified tags on 1 snapshots
 
-    $ restic -r /tmp/backup tag --tag NL --remove NL
+    $ restic -r /srv/restic-repo tag --tag NL --remove NL
     create exclusive lock for repository
     modified tags on 1 snapshots
 
-    $ restic -r /tmp/backup tag --tag NL --add SOMETHING
+    $ restic -r /srv/restic-repo tag --tag NL --add SOMETHING
     no snapshots were modified
 
 Under the hood
@@ -170,7 +173,7 @@ locks with the following command:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup list snapshots
+    $ restic -r /srv/restic-repo list snapshots
     d369ccc7d126594950bf74f0a348d5d98d9e99f3215082eb69bf02dc9b3e464c
 
 The ``find`` command searches for a given
@@ -191,7 +194,7 @@ objects or their raw content.
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup cat snapshot d369ccc7d126594950bf74f0a348d5d98d9e99f3215082eb69bf02dc9b3e464c
+    $ restic -r /srv/restic-repo cat snapshot d369ccc7d126594950bf74f0a348d5d98d9e99f3215082eb69bf02dc9b3e464c
     enter password for repository:
     {
       "time": "2015-08-12T12:52:44.091448856+02:00",
@@ -242,7 +245,7 @@ lists all snapshots as JSON and uses ``jq`` to pretty-print the result:
 
 .. code-block:: console
 
-    $ restic -r /tmp/backup snapshots --json | jq .
+    $ restic -r /srv/restic-repo snapshots --json | jq .
     [
       {
         "time": "2017-03-11T09:57:43.26630619+01:00",
@@ -283,7 +286,7 @@ instead of the default, set the environment variable like this:
 .. code-block:: console
 
     $ export TMPDIR=/var/tmp/restic-tmp
-    $ restic -r /tmp/backup backup ~/work
+    $ restic -r /srv/restic-repo backup ~/work