Merge pull request #5643 from kjetilho/doc-restore

Improve documentation for restore

doc/050_restore.rst

@@ -19,46 +19,53 @@ Restoring from a snapshot
 
 Restoring a snapshot is as easy as it sounds, just use the following
 command to restore the contents of the latest snapshot to
-``/tmp/restore-work``:
+``/tmp/restore``:
 
 .. code-block:: console
 
-    $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore-work
+    $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore
     enter password for repository:
-    restoring <Snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST> to /tmp/restore-work
+    restoring snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST to /tmp/restore
 
 Use the word ``latest`` to restore the last backup. You can also combine
 ``latest`` with the ``--host`` and ``--path`` filters to choose the last
-backup for a specific host, path or both.
+backup for a specific host, path or both:
 
 .. code-block:: console
 
-    $ restic -r /srv/restic-repo restore latest --target /tmp/restore-art --path "/home/art" --host luigi
+    $ restic -r /srv/restic-repo restore latest --path /home/art --host luigi --target /tmp/restore
     enter password for repository:
-    restoring <Snapshot of [/home/art] at 2015-05-08 21:45:17.884408621 +0200 CEST> to /tmp/restore-art
+    restoring snapshot of [/home/art,/home/documents] at 2015-05-08 21:45:17.884408621 +0200 CEST to /tmp/restore
+
+Note that the ``--path`` option is only used to select the snapshot to restore, not to
+restrict the restore to a subset of files in the snapshot. This means that here the files
+will be restored to ``/tmp/restore/home/art`` and ``/tmp/restore/home/documents``.
 
 Use ``--exclude`` and ``--include`` to restrict the restore to a subset of
 files in the snapshot. For example, to restore a single file:
 
 .. code-block:: console
 
-    $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore-work --include /work/foo
+    $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore --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
+    restoring snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST to /tmp/restore
 
-This will restore the file ``foo`` to ``/tmp/restore-work/work/foo``.
+This will restore the file ``/work/foo`` to ``/tmp/restore/work/foo``.
 
 To only restore a specific subfolder, you can use the ``<snapshot>:<subfolder>``
 syntax, where ``snapshot`` is the ID of a snapshot (or the string ``latest``)
-and ``subfolder`` is a path within the snapshot.
+and ``subfolder`` is a path within the snapshot. Note that the subfolder syntax
+also affects options like ``--include`` and ``--exclude``, such that their
+arguments should be specified relative to ``subfolder`` (e.g. ``/foo`` instead
+of ``/work/foo``).
 
 .. code-block:: console
 
-    $ restic -r /srv/restic-repo restore 79766175:/work --target /tmp/restore-work --include /foo
+    $ restic -r /srv/restic-repo restore 79766175:/work --target /tmp/restore --include /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
+    restoring snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST to /tmp/restore
 
-This will restore the file ``foo`` to ``/tmp/restore-work/foo``.
+This will restore the file ``/work/foo`` at the path ``/tmp/restore/foo``.
 
 You can use the command ``restic ls latest`` or ``restic find foo`` to find the
 path to the file within the snapshot. This path you can then pass to
@@ -99,9 +106,9 @@ user and security namespaced extended attributes for files:
 
 .. code-block:: console
 
-    $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore-work --include-xattr user.* --include-xattr security.*
+    $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore --include-xattr user.* --include-xattr security.*
     enter password for repository:
-    restoring <Snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST> to /tmp/restore-work
+    restoring snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST to /tmp/restore
 
 Restoring in-place
 ------------------
@@ -134,9 +141,6 @@ files that do not exist in the snapshot. For this, pass the ``--delete`` option
 command. The command will then **delete all files** from the target directory that do not
 exist in the snapshot.
 
-The ``--delete`` option also allows overwriting a non-empty directory if the snapshot contains a
-file with the same name.
-
 .. warning::
 
     Always use the ``--dry-run -vv`` option to verify what would be deleted before running the actual
@@ -144,13 +148,16 @@ file with the same name.
 
 When specifying ``--include`` or ``--exclude`` options, only files or directories matched by those
 options will be deleted. For example, the command
-``restic -r /srv/restic-repo restore 79766175:/work --target /tmp/restore-work --include /foo --delete``
-would only delete files within ``/tmp/restore-work/foo``.
+``restic -r /srv/restic-repo restore 79766175:/work --target /tmp/restore --include /foo --delete``
+would only delete files within ``/tmp/restore/foo``.
 
 When using ``--target / --delete`` then the ``restore`` command only works if either an ``--include``
 or ``--exclude`` option is also specified. This ensures that one cannot accidentally delete
 the whole system.
 
+The ``--delete`` option also allows overwriting a non-empty directory if the snapshot contains a
+file with the same name.
+
 Dry run
 -------
 
@@ -161,7 +168,7 @@ restored files when specifying ``--verbose=2``.
 
 .. code-block:: console
 
-    $ restic restore --target /tmp/restore-work --dry-run --verbose=2 latest
+    $ restic restore --target /tmp/restore --dry-run --verbose=2 latest
 
     unchanged /restic/internal/walker/walker.go with size 2.812 KiB
     updated   /restic/internal/walker/walker_test.go with size 11.143 KiB