From 496ea804a6c9735ee99118da1025e3d0ca082ca6 Mon Sep 17 00:00:00 2001
From: Michael Eischer <michael.eischer@fau.de>
Date: Sat, 16 May 2026 11:39:14 +0200
Subject: [PATCH 1/6] check/dump/mount/repair/rewrite: update command
 description

---
 cmd/restic/cmd_check.go   | 10 +++++++---
 cmd/restic/cmd_dump.go    |  2 +-
 cmd/restic/cmd_mount.go   |  4 ++--
 cmd/restic/cmd_repair.go  |  8 ++++++--
 cmd/restic/cmd_rewrite.go | 12 +++++-------
 5 files changed, 21 insertions(+), 15 deletions(-)

diff --git a/cmd/restic/cmd_check.go b/cmd/restic/cmd_check.go
index 6ec24baf2..27f7720e4 100644
--- a/cmd/restic/cmd_check.go
+++ b/cmd/restic/cmd_check.go
@@ -31,10 +31,14 @@ func newCheckCommand(globalOptions *global.Options) *cobra.Command {
 		Short: "Check the repository for errors",
 		Long: `
 The "check" command tests the repository for errors and reports any errors it
-finds. It can also be used to read all data and therefore simulate a restore.
+finds.
 
-By default, the "check" command will always load all data directly from the
-repository and not use a local cache.
+By default, check verifies the structural consistency and integrity of
+snapshots, trees and pack files. To also verify the integrity of the actual
+backed-up data, use the --read-data or --read-data-subset flags.
+
+By default, check creates a new temporary cache directory to verify data.
+To reuse the existing cache, use the --with-cache flag.
 
 EXIT STATUS
 ===========
diff --git a/cmd/restic/cmd_dump.go b/cmd/restic/cmd_dump.go
index 6a5e3adb6..20904b43c 100644
--- a/cmd/restic/cmd_dump.go
+++ b/cmd/restic/cmd_dump.go
@@ -23,7 +23,7 @@ func newDumpCommand(globalOptions *global.Options) *cobra.Command {
 	var opts DumpOptions
 	cmd := &cobra.Command{
 		Use:   "dump [flags] snapshotID file",
-		Short: "Print a backed-up file to stdout",
+		Short: "Print backed-up files or folders to stdout",
 		Long: `
 The "dump" command extracts files from a snapshot from the repository. If a
 single file is selected, it prints its contents to stdout. Folders are output
diff --git a/cmd/restic/cmd_mount.go b/cmd/restic/cmd_mount.go
index 96f217880..c0f446193 100644
--- a/cmd/restic/cmd_mount.go
+++ b/cmd/restic/cmd_mount.go
@@ -36,8 +36,8 @@ func newMountCommand(globalOptions *global.Options) *cobra.Command {
 		Use:   "mount [flags] mountpoint",
 		Short: "Mount the repository",
 		Long: `
-The "mount" command mounts the repository via fuse over a writeable directory.
-The repository will be mounted read-only.
+The "mount" command mounts the repository read-only via FUSE at the given
+mountpoint.
 
 Snapshot Directories
 ====================
diff --git a/cmd/restic/cmd_repair.go b/cmd/restic/cmd_repair.go
index 6181e7dfe..fccb47992 100644
--- a/cmd/restic/cmd_repair.go
+++ b/cmd/restic/cmd_repair.go
@@ -7,8 +7,12 @@ import (
 
 func newRepairCommand(globalOptions *global.Options) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:               "repair",
-		Short:             "Repair the repository",
+		Use:   "repair",
+		Short: "Repair the repository",
+		Long: `
+The "repair" command repairs damaged repositories. It provides subcommands to
+rebuild the index, salvage damaged pack files, and repair broken snapshots.
+`,
 		GroupID:           cmdGroupDefault,
 		DisableAutoGenTag: true,
 	}
diff --git a/cmd/restic/cmd_rewrite.go b/cmd/restic/cmd_rewrite.go
index f5826c79f..976fe4f73 100644
--- a/cmd/restic/cmd_rewrite.go
+++ b/cmd/restic/cmd_rewrite.go
@@ -24,14 +24,12 @@ func newRewriteCommand(globalOptions *global.Options) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "rewrite [flags] [snapshotID ...]",
-		Short: "Rewrite snapshots to exclude unwanted files",
+		Short: "Rewrite snapshots to exclude files or change metadata",
 		Long: `
-The "rewrite" command excludes files from existing snapshots. It creates new
-snapshots containing the same data as the original ones, but without the files
-you specify to exclude. All metadata (time, host, tags) will be preserved.
-
-Alternatively you can use one of the --include variants to only include files
-in the new snapshot which you want to preserve.
+The "rewrite" command creates new snapshots from existing ones. You can use
+exclude or include filters to control which files are included in the new
+snapshots. Unless --new-host or --new-time is specified, metadata (time, host,
+tags) is preserved.
 
 The snapshots to rewrite are specified using the --host, --tag and --path options,
 or by providing a list of snapshot IDs. Please note that specifying neither any of

From 2b72f3eb4214df0b4823fb2287128c0a10cc2786 Mon Sep 17 00:00:00 2001
From: Michael Eischer <michael.eischer@fau.de>
Date: Sat, 16 May 2026 11:39:53 +0200
Subject: [PATCH 2/6] find: fix placement of exit status section

---
 cmd/restic/cmd_find.go | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/cmd/restic/cmd_find.go b/cmd/restic/cmd_find.go
index 851407292..6f7a6396a 100644
--- a/cmd/restic/cmd_find.go
+++ b/cmd/restic/cmd_find.go
@@ -33,16 +33,11 @@ func newFindCommand(globalOptions *global.Options) *cobra.Command {
 		Short: "Find a file, a directory or restic IDs",
 		Long: `
 The "find" command searches for files or directories in snapshots stored in the
-repo.
-It can also be used to search for restic blobs or trees for troubleshooting.
+repository. It can also be used to search for restic blobs, trees or pack
+files for troubleshooting.
+
 The default sort option for the snapshots is youngest to oldest. To sort the
-output from oldest to youngest specify --reverse.`,
-		Example: `restic find config.json
-restic find --json "*.yml" "*.json"
-restic find --json --blob 420f620f b46ebe8a ddd38656
-restic find --show-pack-id --blob 420f620f
-restic find --tree 577c2bc9 f81f2e22 a62827a9
-restic find --pack 025c1d06
+output from oldest to youngest specify --reverse.
 
 EXIT STATUS
 ===========
@@ -53,6 +48,12 @@ Exit status is 10 if the repository does not exist.
 Exit status is 11 if the repository is already locked.
 Exit status is 12 if the password is incorrect.
 `,
+		Example: `restic find config.json
+restic find --json "*.yml" "*.json"
+restic find --json --blob 420f620f b46ebe8a ddd38656
+restic find --show-pack-id --blob 420f620f
+restic find --tree 577c2bc9 f81f2e22 a62827a9
+restic find --pack 025c1d06`,
 		GroupID:           cmdGroupDefault,
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {

From 9299c4581827a81189cf80e2279b39e29c11457d Mon Sep 17 00:00:00 2001
From: Michael Eischer <michael.eischer@fau.de>
Date: Sat, 16 May 2026 11:40:22 +0200
Subject: [PATCH 3/6] fix typos in cmd descriptions

---
 cmd/restic/cmd_key_passwd.go  | 4 ++--
 cmd/restic/cmd_key_remove.go  | 4 ++--
 cmd/restic/cmd_self_update.go | 2 +-
 cmd/restic/cmd_tag.go         | 2 +-
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/cmd/restic/cmd_key_passwd.go b/cmd/restic/cmd_key_passwd.go
index c45ac96ed..51ed7aa0e 100644
--- a/cmd/restic/cmd_key_passwd.go
+++ b/cmd/restic/cmd_key_passwd.go
@@ -20,8 +20,8 @@ func newKeyPasswdCommand(globalOptions *global.Options) *cobra.Command {
 		Use:   "passwd",
 		Short: "Change key (password); creates a new key ID and removes the old key ID, returns new key ID",
 		Long: `
-The "passwd" sub-command creates a new key, validates the key and remove the old key ID.
-Returns the new key ID. 
+The "passwd" sub-command creates a new key, validates the key and removes the old key ID.
+Returns the new key ID.
 
 EXIT STATUS
 ===========
diff --git a/cmd/restic/cmd_key_remove.go b/cmd/restic/cmd_key_remove.go
index 90ab6b7fe..22a1e8cfa 100644
--- a/cmd/restic/cmd_key_remove.go
+++ b/cmd/restic/cmd_key_remove.go
@@ -16,10 +16,10 @@ import (
 func newKeyRemoveCommand(globalOptions *global.Options) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "remove [ID]",
-		Short: "Remove key ID (password) from the repository.",
+		Short: "Remove key ID (password) from the repository",
 		Long: `
 The "remove" sub-command removes the selected key ID. The "remove" command does not allow
-removing the current key being used to access the repository. 
+removing the current key being used to access the repository.
 
 EXIT STATUS
 ===========
diff --git a/cmd/restic/cmd_self_update.go b/cmd/restic/cmd_self_update.go
index 5b684b22e..0470d5d94 100644
--- a/cmd/restic/cmd_self_update.go
+++ b/cmd/restic/cmd_self_update.go
@@ -28,7 +28,7 @@ func newSelfUpdateCommand(globalOptions *global.Options) *cobra.Command {
 		Use:   "self-update [flags]",
 		Short: "Update the restic binary",
 		Long: `
-The command "self-update" downloads the latest stable release of restic from
+The "self-update" command downloads the latest stable release of restic from
 GitHub and replaces the currently running binary. After download, the
 authenticity of the binary is verified using the GPG signature on the release
 files.
diff --git a/cmd/restic/cmd_tag.go b/cmd/restic/cmd_tag.go
index 65df7c292..6b1503f96 100644
--- a/cmd/restic/cmd_tag.go
+++ b/cmd/restic/cmd_tag.go
@@ -22,7 +22,7 @@ func newTagCommand(globalOptions *global.Options) *cobra.Command {
 		Use:   "tag [flags] [snapshotID ...]",
 		Short: "Modify tags on snapshots",
 		Long: `
-The "tag" command allows you to modify tags on exiting snapshots.
+The "tag" command allows you to modify tags on existing snapshots.
 
 You can either set/replace the entire set of tags on a snapshot, or
 add tags to/remove tags from the existing set.

From df03e8a0ec6d0c66414dc402c4abee8e4f8e2d7f Mon Sep 17 00:00:00 2001
From: Michael Eischer <michael.eischer@fau.de>
Date: Sat, 16 May 2026 11:41:24 +0200
Subject: [PATCH 4/6] self update: remove not possible exit codes

---
 cmd/restic/cmd_self_update.go | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/cmd/restic/cmd_self_update.go b/cmd/restic/cmd_self_update.go
index 0470d5d94..387c9b1d7 100644
--- a/cmd/restic/cmd_self_update.go
+++ b/cmd/restic/cmd_self_update.go
@@ -38,9 +38,6 @@ EXIT STATUS
 
 Exit status is 0 if the command was successful.
 Exit status is 1 if there was any error.
-Exit status is 10 if the repository does not exist.
-Exit status is 11 if the repository is already locked.
-Exit status is 12 if the password is incorrect.
 `,
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {

From 850ab61cdfbf1200f804743256a700fdbce4da66 Mon Sep 17 00:00:00 2001
From: Michael Eischer <michael.eischer@fau.de>
Date: Sat, 16 May 2026 11:42:03 +0200
Subject: [PATCH 5/6] key: include full command name in subcommand descriptions

---
 cmd/restic/cmd_key_add.go    | 2 +-
 cmd/restic/cmd_key_list.go   | 2 +-
 cmd/restic/cmd_key_passwd.go | 2 +-
 cmd/restic/cmd_key_remove.go | 4 ++--
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/cmd/restic/cmd_key_add.go b/cmd/restic/cmd_key_add.go
index 5df3819ac..f83a048ab 100644
--- a/cmd/restic/cmd_key_add.go
+++ b/cmd/restic/cmd_key_add.go
@@ -20,7 +20,7 @@ func newKeyAddCommand(globalOptions *global.Options) *cobra.Command {
 		Use:   "add",
 		Short: "Add a new key (password) to the repository; returns the new key ID",
 		Long: `
-The "add" sub-command creates a new key and validates the key. Returns the new key ID.
+The "key add" command creates a new key and validates the key. Returns the new key ID.
 
 EXIT STATUS
 ===========
diff --git a/cmd/restic/cmd_key_list.go b/cmd/restic/cmd_key_list.go
index 73527ae48..a7828b44f 100644
--- a/cmd/restic/cmd_key_list.go
+++ b/cmd/restic/cmd_key_list.go
@@ -20,7 +20,7 @@ func newKeyListCommand(globalOptions *global.Options) *cobra.Command {
 		Use:   "list",
 		Short: "List keys (passwords)",
 		Long: `
-The "list" sub-command lists all the keys (passwords) associated with the repository.
+The "key list" command lists all the keys (passwords) associated with the repository.
 Returns the key ID, username, hostname, created time and if it's the current key being
 used to access the repository.
 
diff --git a/cmd/restic/cmd_key_passwd.go b/cmd/restic/cmd_key_passwd.go
index 51ed7aa0e..2f4a9507f 100644
--- a/cmd/restic/cmd_key_passwd.go
+++ b/cmd/restic/cmd_key_passwd.go
@@ -20,7 +20,7 @@ func newKeyPasswdCommand(globalOptions *global.Options) *cobra.Command {
 		Use:   "passwd",
 		Short: "Change key (password); creates a new key ID and removes the old key ID, returns new key ID",
 		Long: `
-The "passwd" sub-command creates a new key, validates the key and removes the old key ID.
+The "key passwd" command creates a new key, validates the key and removes the old key ID.
 Returns the new key ID.
 
 EXIT STATUS
diff --git a/cmd/restic/cmd_key_remove.go b/cmd/restic/cmd_key_remove.go
index 22a1e8cfa..2d85c0122 100644
--- a/cmd/restic/cmd_key_remove.go
+++ b/cmd/restic/cmd_key_remove.go
@@ -18,8 +18,8 @@ func newKeyRemoveCommand(globalOptions *global.Options) *cobra.Command {
 		Use:   "remove [ID]",
 		Short: "Remove key ID (password) from the repository",
 		Long: `
-The "remove" sub-command removes the selected key ID. The "remove" command does not allow
-removing the current key being used to access the repository.
+The "key remove" command removes the selected key ID. It does not allow removing the
+current key being used to access the repository.
 
 EXIT STATUS
 ===========

From 77f6795b324e7eb9b4b309ee3a45d8821d1b38ad Mon Sep 17 00:00:00 2001
From: Michael Eischer <michael.eischer@fau.de>
Date: Sat, 16 May 2026 11:46:48 +0200
Subject: [PATCH 6/6] doc: update embedded help output

---
 doc/manual_rest.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/manual_rest.rst b/doc/manual_rest.rst
index 18c782769..71eefe01c 100644
--- a/doc/manual_rest.rst
+++ b/doc/manual_rest.rst
@@ -25,7 +25,7 @@ Usage help is available:
       check         Check the repository for errors
       copy          Copy snapshots from one repository to another
       diff          Show differences between two snapshots
-      dump          Print a backed-up file to stdout
+      dump          Print backed-up files or folders to stdout
       find          Find a file, a directory or restic IDs
       forget        Remove snapshots from the repository
       init          Initialize a new repository
@@ -38,7 +38,7 @@ Usage help is available:
       recover       Recover data from the repository not referenced by snapshots
       repair        Repair the repository
       restore       Extract the data from a snapshot
-      rewrite       Rewrite snapshots to exclude unwanted files
+      rewrite       Rewrite snapshots to exclude files or change metadata
       snapshots     List all snapshots
       stats         Scan the repository and show basic statistics
       tag           Modify tags on snapshots