diff --git a/doc/040_backup.rst b/doc/040_backup.rst index 614d58ee0..ad7deb3d9 100644 --- a/doc/040_backup.rst +++ b/doc/040_backup.rst @@ -279,6 +279,45 @@ 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 + +.. note:: When switching between absolute and relative paths, the change detection in restic + will not be able to detect unmodified files. This is because the change detection depends + on the file path inside the snapshot. Dry Runs ******** diff --git a/doc/045_working_with_repos.rst b/doc/045_working_with_repos.rst index f03674383..3fbfaff8a 100644 --- a/doc/045_working_with_repos.rst +++ b/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 diff --git a/doc/050_restore.rst b/doc/050_restore.rst index 980fa7b3d..4b01f94f4 100644 --- a/doc/050_restore.rst +++ b/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: