doc: describe effects of relative paths on snapshot structure

doc/040_backup.rst

@@ -279,6 +279,41 @@ the corresponding folder and use relative paths.
     processed 5307 files, 1.720 GiB in 0:03
     skipped creating snapshot
 
+.. _absolute-and-relative-paths:
+
+Absolute and relative paths
+***************************
+
+Depending on whether absolute or relative paths are used, the folder structure in the
+resulting snapshot will be different. Absolute paths will contain the full folder structure,
+starting from the root directory. Relative paths will contain the relative path structure,
+starting from the current working directory.
+
+The following example shows the result for a backup of the file ``/home/user/work.txt`` using
+an absolute path and a relative path. The ``ls`` command shows the files in the snapshot.
+Note that the snapshot metadata will always contain the absolute path.
+
+.. code-block:: console
+
+    $ restic -r /srv/restic-repo backup /home/user/work.txt
+    [...]
+    snapshot c0899509 saved
+
+    $ restic -r /srv/restic-repo ls c0899509
+    snapshot c0899509 of [/home/user/work.txt] at 2026-02-01 14:05:20.623159838 +0100 CET by user@host filtered by []:
+    /home
+    /home/user
+    /home/user/work.txt
+
+    $ cd /home
+    $ restic -r /srv/restic-repo backup user/work.txt
+    [...]
+    snapshot 90de7fb2 saved
+
+    $ restic -r /srv/restic-repo ls
+    snapshot 90de7fb2 of [/home/user/work.txt] at 2026-02-01 14:07:30.856406104 +0100 CET by user@host filtered by []:
+    /user
+    /user/work.txt
 
 Dry Runs
 ********

doc/045_working_with_repos.rst

@@ -20,7 +20,9 @@ Listing all snapshots
 
 Now, you can list all the snapshots stored in the repository. The size column
 only exists for snapshots created using restic 0.17.0 or later. It reflects the
-size of the contained files at the time when the snapshot was created.
+size of the contained files at the time when the snapshot was created. The
+directory of a snapshot may differ from the directory structure in the snapshot,
+see :ref:`absolute-and-relative-paths` for details.
 
 .. code-block:: console
 

doc/050_restore.rst

@@ -254,6 +254,17 @@ e.g.:
 
     $ restic -r /srv/restic-repo dump --path /production.sql latest production.sql | mysql
 
+If a snapshot was backed up using relative paths, then the directory shown in the output
+of ``snapshots`` may differ from the directory structure in the snapshot.
+See :ref:`absolute-and-relative-paths` for details. Use ``ls`` to determine the correct path:
+
+.. code-block:: console
+
+    $ restic -r /srv/restic-repo ls e922c858
+    snapshot e922c858 of [/home/other/work] at 2018-07-14 20:18:10.884408621 +0200 CEST by mopped filtered by []:
+    /other
+    /other/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: