Merge pull request #21810 from MichaelEischer/cmd-doc-typos

Fix command doc typos and update help for check/rewrite

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
 ===========

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

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 {

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
 ===========

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.
 

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 "key passwd" command creates a new key, validates the key and removes the old key ID.
+Returns the new key ID.
 
 EXIT STATUS
 ===========

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. 
+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
 ===========

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
 ====================

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,
 	}

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

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.
@@ -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 {

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.

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