Merge 1925457b78 into 24c1822220

doc/040_backup.rst

@@ -45,6 +45,17 @@ size of the files and directories in ``~/work`` on the local file system. It
 also tells us that only 1.200 GiB was added to the repository. This means that
 some of the data was duplicate and restic was able to efficiently reduce it.
 
+We just attached the absolute path ``~/work`` to the backup, so the path
+within the snapshot is ``/home/user/work``.
+
+If we attach a relative path ``work``, the path within the snaphot is ``/work``.
+
+For example ``restic backup work`` run from ``/home/user`` creates a snapshot
+with a directory ``/home/user/work`` that contains the path ``/work``
+within the snapshot. This path-related discrepancy applies to each command
+that tries to access data within a snapshot. You can lookup the paths within
+a repository using the ``ls latest /`` command.
+
 If you don't pass the ``--verbose`` option, restic will print less data. You'll
 still get a nice live status display. Be aware that the live status shows the
 processed files and not the transferred data. Transferred volume might be lower

doc/045_working_with_repos.rst

@@ -34,6 +34,9 @@ size of the contained files at the time when the snapshot was created.
     590c8fc8  2015-05-08 21:47:38  kazik          /srv             580.200MiB
     9f0bc19e  2015-05-08 21:46:11  luigi          /srv             572.180MiB
 
+The Directory column shows the attached path, which may differ
+from the path within the repository, see https://restic.readthedocs.io/en/stable/040_backup.html#backing-up for details of this discrepancy.
+
 You can filter the listing by directory path:
 
 .. code-block:: console

doc/050_restore.rst

@@ -156,6 +156,31 @@ e.g.:
 
     $ restic -r /srv/restic-repo dump --path /production.sql latest production.sql | mysql
 
+This example assumes you ran a backup using an absolute path, which coincides with the
+path within the snaphots.
+See https://restic.readthedocs.io/en/stable/040_backup.html#backing-up for the difference
+between the path used to create the repository and the paths within the snaphots.
+
+If you ran a backup using the relative path ``work/``, the ``dump`` command would look like:
+
+.. code-block:: console
+
+    $ restic -r /srv/restic-repo dump latest /work/README.md
+
+
+If dump results in the error message ``cannot dump file: path "/home" not found in snapshot``
+first double check you used the path within the snaphot, using the ``ls latest /`` command,
+which for the repository above results in:
+
+.. code-block:: console
+
+    $ restic -r /srv/restic-repo ls latest /
+    enter password for repository:
+    snapshot 1541acae of [/home/other/work] filtered by [/] at 2023-08-09 04:00:03.533117139 +0200 CEST):
+    /work
+
+
+
 It is also possible to ``dump`` the contents of a whole folder structure to
 stdout. To retain the information about the files and folders Restic will
 output the contents in the tar (default) or zip format: