From 798256ec5218d334bfd8dddae5b70060e62b2f05 Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Fri, 31 May 2024 21:12:13 +0200 Subject: [PATCH] restore: add dry-run docs --- changelog/unreleased/pull-4839 | 7 +++++++ doc/050_restore.rst | 22 ++++++++++++++++++++++ doc/075_scripting.rst | 16 ++++++++++++++++ 3 files changed, 45 insertions(+) create mode 100644 changelog/unreleased/pull-4839 diff --git a/changelog/unreleased/pull-4839 b/changelog/unreleased/pull-4839 new file mode 100644 index 000000000..8d644407b --- /dev/null +++ b/changelog/unreleased/pull-4839 @@ -0,0 +1,7 @@ +Enhancement: Add dry-run support to `restore` command + +The `restore` command now supports the `--dry-run` option to perform +a dry run. Pass the `--verbose=2` option to see which files would +remain unchanged, which would be updated or freshly restored. + +https://github.com/restic/restic/pull/4839 diff --git a/doc/050_restore.rst b/doc/050_restore.rst index 9c24f09de..57251f135 100644 --- a/doc/050_restore.rst +++ b/doc/050_restore.rst @@ -111,6 +111,28 @@ values are supported: newer modification time (mtime). * ``--overwrite never``: never overwrite existing files. +Dry run +------- + +As restore operations can take a long time, it can be useful to perform a dry-run to +see what would be restored without having to run the full restore operation. The +restore command supports the ``--dry-run`` option and prints information about the +restored files when specifying ``--verbose=2``. + +.. code-block:: console + + $ restic restore --target /tmp/restore-work --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 + restored /restic/restic with size 35.318 MiB + restored /restic + [...] + Summary: Restored 9072 files/dirs (153.597 MiB) in 0:00 + +Files with already up to date content are reported as ``unchanged``. Files whose content +was modified are ``updated`` and files that are new are shown as ``restored``. Directories +and other file types like symlinks are always reported as ``restored``. Restore using mount =================== diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index d40f7c976..b83fe5eb5 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -511,6 +511,22 @@ Status |``bytes_skipped`` | Total size of skipped files | +----------------------+------------------------------------------------------------+ +Verbose Status +^^^^^^^^^^^^^^ + +Verbose status provides details about the progress, including details about restored files. +Only printed if `--verbose=2` is specified. + ++----------------------+-----------------------------------------------------------+ +| ``message_type`` | Always "verbose_status" | ++----------------------+-----------------------------------------------------------+ +| ``action`` | Either "restored", "updated" or "unchanged" | ++----------------------+-----------------------------------------------------------+ +| ``item`` | The item in question | ++----------------------+-----------------------------------------------------------+ +| ``size`` | Size of the item in bytes | ++----------------------+-----------------------------------------------------------+ + Summary ^^^^^^^