From 0673b58d7cf48346910471ae0be36a800f6a8d66 Mon Sep 17 00:00:00 2001 From: Kjetil Torgrim Homme Date: Fri, 5 Dec 2025 17:50:53 +0100 Subject: [PATCH 1/6] doc: restore: explain explicitly effect of specifying snapshot:subfolder The effect could be read from the examples, but it was easy to miss. --- doc/050_restore.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/050_restore.rst b/doc/050_restore.rst index 980fa7b3d..745cb165a 100644 --- a/doc/050_restore.rst +++ b/doc/050_restore.rst @@ -50,7 +50,9 @@ This will restore the file ``foo`` to ``/tmp/restore-work/work/foo``. To only restore a specific subfolder, you can use the ``:`` 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. This changes the root for the +arguments to ``--include`` or ``--exclude``, they should be specified relative +to ``subfolder``. .. code-block:: console @@ -58,7 +60,7 @@ and ``subfolder`` is a path within the snapshot. enter password for repository: restoring to /tmp/restore-work -This will restore the file ``foo`` to ``/tmp/restore-work/foo``. +This will restore the file ``/work/foo`` to ``/tmp/restore-work/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 From d34ba9b6bdd421cb0d0f0d955f3cdf6b397c51d7 Mon Sep 17 00:00:00 2001 From: Kjetil Torgrim Homme Date: Fri, 5 Dec 2025 17:59:56 +0100 Subject: [PATCH 2/6] doc: restore: explain how --delete and --exclude work together --- doc/050_restore.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/050_restore.rst b/doc/050_restore.rst index 745cb165a..5e91fdf75 100644 --- a/doc/050_restore.rst +++ b/doc/050_restore.rst @@ -136,6 +136,14 @@ 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. +With ``--delete``, ``--exclude`` has a dual purpose: + +* It will exclude files from being restored. The exclude argument is taken + relative to the subfolder given with the snapshot (if any; otherwise ``/`` of + the snapshot.) +* It will exclude files in the target directory from being deleted. The exclude + argument is here relative to the target directory. + The ``--delete`` option also allows overwriting a non-empty directory if the snapshot contains a file with the same name. From 655e5277657524438ce1e4c50af8e9dad6e9b6ca Mon Sep 17 00:00:00 2001 From: Kjetil Torgrim Homme Date: Fri, 5 Dec 2025 18:04:46 +0100 Subject: [PATCH 3/6] doc: restore: be clearer about resulting filenames in restore --- doc/050_restore.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/050_restore.rst b/doc/050_restore.rst index 5e91fdf75..83eec1d38 100644 --- a/doc/050_restore.rst +++ b/doc/050_restore.rst @@ -37,6 +37,8 @@ backup for a specific host, path or both. enter password for repository: restoring to /tmp/restore-art +The files will be restored to ``/tmp/restore-art/home/art``. + Use ``--exclude`` and ``--include`` to restrict the restore to a subset of files in the snapshot. For example, to restore a single file: @@ -46,7 +48,7 @@ files in the snapshot. For example, to restore a single file: enter password for repository: restoring to /tmp/restore-work -This will restore the file ``foo`` to ``/tmp/restore-work/work/foo``. +This will restore the file ``/work/foo`` to ``/tmp/restore-work/work/foo``. To only restore a specific subfolder, you can use the ``:`` syntax, where ``snapshot`` is the ID of a snapshot (or the string ``latest``) From ee099e466241a32e6511aa8eb4b0a7f1c036cbce Mon Sep 17 00:00:00 2001 From: Kjetil Torgrim Homme Date: Fri, 5 Dec 2025 18:07:11 +0100 Subject: [PATCH 4/6] doc: restore: simplify restore target name the suffix "-work" is visually distracting since it copies a part of the directory path being restored. this makes it easy to gloss over where the "work" string actually comes from. as a bonus, it makes the examples slightly shorter to read. --- doc/050_restore.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/doc/050_restore.rst b/doc/050_restore.rst index 83eec1d38..52a5fc711 100644 --- a/doc/050_restore.rst +++ b/doc/050_restore.rst @@ -19,13 +19,13 @@ 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 to /tmp/restore-work + restoring 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 @@ -33,22 +33,22 @@ 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 --target /tmp/restore --path "/home/art" --host luigi enter password for repository: - restoring to /tmp/restore-art + restoring to /tmp/restore -The files will be restored to ``/tmp/restore-art/home/art``. +The files will be restored to ``/tmp/restore/home/art``. 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 to /tmp/restore-work + restoring to /tmp/restore -This will restore the file ``/work/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 ``:`` syntax, where ``snapshot`` is the ID of a snapshot (or the string ``latest``) @@ -58,11 +58,11 @@ to ``subfolder``. .. 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 to /tmp/restore-work + restoring to /tmp/restore -This will restore the file ``/work/foo`` to ``/tmp/restore-work/foo``. +This will restore the file ``/work/foo`` to ``/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 @@ -103,9 +103,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 to /tmp/restore-work + restoring to /tmp/restore Restoring in-place ------------------ @@ -156,8 +156,8 @@ 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 @@ -173,7 +173,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 From acc95531a4588f7a56ec7fbe071ca31d75a95b5b Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Thu, 14 May 2026 13:42:33 +0200 Subject: [PATCH 5/6] docs/restore: clarify --path option example, subfolder syntax and --delete option --- doc/050_restore.rst | 33 ++++++++++++++------------------- 1 file changed, 14 insertions(+), 19 deletions(-) diff --git a/doc/050_restore.rst b/doc/050_restore.rst index 52a5fc711..ead7fcd43 100644 --- a/doc/050_restore.rst +++ b/doc/050_restore.rst @@ -29,15 +29,17 @@ command to restore the contents of the latest snapshot to 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 --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 to /tmp/restore + restoring to /tmp/restore -The files will be restored to ``/tmp/restore/home/art``. +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: @@ -52,9 +54,10 @@ This will restore the file ``/work/foo`` to ``/tmp/restore/work/foo``. To only restore a specific subfolder, you can use the ``:`` syntax, where ``snapshot`` is the ID of a snapshot (or the string ``latest``) -and ``subfolder`` is a path within the snapshot. This changes the root for the -arguments to ``--include`` or ``--exclude``, they should be specified relative -to ``subfolder``. +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 @@ -62,7 +65,7 @@ to ``subfolder``. enter password for repository: restoring to /tmp/restore -This will restore the file ``/work/foo`` to ``/tmp/restore/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 @@ -138,17 +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. -With ``--delete``, ``--exclude`` has a dual purpose: - -* It will exclude files from being restored. The exclude argument is taken - relative to the subfolder given with the snapshot (if any; otherwise ``/`` of - the snapshot.) -* It will exclude files in the target directory from being deleted. The exclude - argument is here relative to the target directory. - -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 @@ -163,6 +155,9 @@ When using ``--target / --delete`` then the ``restore`` command only works if ei 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 ------- From 6c63c1c2441a1c4c8ad4f003f2b41d97575a1f12 Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Thu, 14 May 2026 13:43:54 +0200 Subject: [PATCH 6/6] partially modernize restore command output --- doc/050_restore.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/050_restore.rst b/doc/050_restore.rst index ead7fcd43..36a8ccc60 100644 --- a/doc/050_restore.rst +++ b/doc/050_restore.rst @@ -25,7 +25,7 @@ command to restore the contents of the latest snapshot to $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore enter password for repository: - restoring to /tmp/restore + 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 @@ -35,7 +35,7 @@ backup for a specific host, path or both: $ restic -r /srv/restic-repo restore latest --path /home/art --host luigi --target /tmp/restore enter password for repository: - restoring to /tmp/restore + 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 @@ -48,7 +48,7 @@ files in the snapshot. For example, to restore a single file: $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore --include /work/foo enter password for repository: - restoring to /tmp/restore + restoring snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST to /tmp/restore This will restore the file ``/work/foo`` to ``/tmp/restore/work/foo``. @@ -63,7 +63,7 @@ of ``/work/foo``). $ restic -r /srv/restic-repo restore 79766175:/work --target /tmp/restore --include /foo enter password for repository: - restoring to /tmp/restore + restoring snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST to /tmp/restore This will restore the file ``/work/foo`` at the path ``/tmp/restore/foo``. @@ -108,7 +108,7 @@ user and security namespaced extended attributes for files: $ restic -r /srv/restic-repo restore 79766175 --target /tmp/restore --include-xattr user.* --include-xattr security.* enter password for repository: - restoring to /tmp/restore + restoring snapshot of [/home/user/work] at 2015-05-08 21:40:19.884408621 +0200 CEST to /tmp/restore Restoring in-place ------------------