From 94f4f1338894f744a4512b877cc27aa302573784 Mon Sep 17 00:00:00 2001 From: Erik Rigtorp Date: Mon, 4 Nov 2019 22:03:38 -0800 Subject: [PATCH] Add documentation on exit status codes to man pages This is step one to start defining useful exit codes for all the commands. --- cmd/restic/cmd_backup.go | 8 ++++++++ cmd/restic/cmd_cache.go | 5 +++++ cmd/restic/cmd_cat.go | 5 +++++ cmd/restic/cmd_check.go | 5 +++++ cmd/restic/cmd_debug.go | 8 +++++++- cmd/restic/cmd_diff.go | 5 +++++ cmd/restic/cmd_dump.go | 5 +++++ cmd/restic/cmd_find.go | 8 +++++++- cmd/restic/cmd_forget.go | 8 +++++++- cmd/restic/cmd_generate.go | 5 +++++ cmd/restic/cmd_init.go | 5 +++++ cmd/restic/cmd_key.go | 5 +++++ cmd/restic/cmd_list.go | 5 +++++ cmd/restic/cmd_ls.go | 5 +++++ cmd/restic/cmd_migrate.go | 5 +++++ cmd/restic/cmd_mount.go | 5 +++++ cmd/restic/cmd_options.go | 5 +++++ cmd/restic/cmd_prune.go | 5 +++++ cmd/restic/cmd_rebuild_index.go | 5 +++++ cmd/restic/cmd_recover.go | 5 +++++ cmd/restic/cmd_restore.go | 5 +++++ cmd/restic/cmd_self_update.go | 5 +++++ cmd/restic/cmd_snapshots.go | 5 +++++ cmd/restic/cmd_stats.go | 5 +++++ cmd/restic/cmd_tag.go | 5 +++++ cmd/restic/cmd_unlock.go | 5 +++++ cmd/restic/cmd_version.go | 5 +++++ 27 files changed, 144 insertions(+), 3 deletions(-) diff --git a/cmd/restic/cmd_backup.go b/cmd/restic/cmd_backup.go index 83a4038ad..25984b623 100644 --- a/cmd/restic/cmd_backup.go +++ b/cmd/restic/cmd_backup.go @@ -35,6 +35,14 @@ var cmdBackup = &cobra.Command{ Long: ` The "backup" command creates a new snapshot and saves the files and directories given as the arguments. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. + +Note that some issues such as unreadable or deleted files during backup +currently doesn't result in a non-zero error exit status. `, PreRun: func(cmd *cobra.Command, args []string) { if backupOptions.Host == "" { diff --git a/cmd/restic/cmd_cache.go b/cmd/restic/cmd_cache.go index 9a2ebd826..2b75419b6 100644 --- a/cmd/restic/cmd_cache.go +++ b/cmd/restic/cmd_cache.go @@ -19,6 +19,11 @@ var cmdCache = &cobra.Command{ Short: "Operate on local cache directories", Long: ` The "cache" command allows listing and cleaning local cache directories. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_cat.go b/cmd/restic/cmd_cat.go index 0dffc0508..1c16a2f62 100644 --- a/cmd/restic/cmd_cat.go +++ b/cmd/restic/cmd_cat.go @@ -18,6 +18,11 @@ var cmdCat = &cobra.Command{ Short: "Print internal objects to stdout", Long: ` The "cat" command is used to print internal objects to stdout. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_check.go b/cmd/restic/cmd_check.go index d0735d07e..34fd61ce1 100644 --- a/cmd/restic/cmd_check.go +++ b/cmd/restic/cmd_check.go @@ -25,6 +25,11 @@ finds. It can also be used to read all data and therefore simulate a restore. By default, the "check" command will always load all data directly from the repository and not use a local cache. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_debug.go b/cmd/restic/cmd_debug.go index 8f25933f9..8e7bdfb8e 100644 --- a/cmd/restic/cmd_debug.go +++ b/cmd/restic/cmd_debug.go @@ -27,7 +27,13 @@ var cmdDebugDump = &cobra.Command{ Short: "Dump data structures", Long: ` The "dump" command dumps data structures from the repository as JSON objects. It -is used for debugging purposes only.`, +is used for debugging purposes only. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. +`, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { return runDebugDump(globalOptions, args) diff --git a/cmd/restic/cmd_diff.go b/cmd/restic/cmd_diff.go index 773ff64f3..b2294d99d 100644 --- a/cmd/restic/cmd_diff.go +++ b/cmd/restic/cmd_diff.go @@ -26,6 +26,11 @@ directory: * U The metadata (access mode, timestamps, ...) for the item was updated * M The file's content was modified * T The type was changed, e.g. a file was made a symlink + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_dump.go b/cmd/restic/cmd_dump.go index 157b39403..fe224c843 100644 --- a/cmd/restic/cmd_dump.go +++ b/cmd/restic/cmd_dump.go @@ -27,6 +27,11 @@ prints its contents to stdout. The special snapshot "latest" can be used to use the latest snapshot in the repository. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_find.go b/cmd/restic/cmd_find.go index cdc5dfb75..d11b9f3db 100644 --- a/cmd/restic/cmd_find.go +++ b/cmd/restic/cmd_find.go @@ -27,7 +27,13 @@ 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`, +restic find --pack 025c1d06 + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. +`, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { return runFind(findOptions, globalOptions, args) diff --git a/cmd/restic/cmd_forget.go b/cmd/restic/cmd_forget.go index b047f1d45..ff71ee404 100644 --- a/cmd/restic/cmd_forget.go +++ b/cmd/restic/cmd_forget.go @@ -16,7 +16,13 @@ var cmdForget = &cobra.Command{ The "forget" command removes snapshots according to a policy. Please note that this command really only deletes the snapshot object in the repository, which is a reference to data stored there. In order to remove this (now unreferenced) -data after 'forget' was run successfully, see the 'prune' command. `, +data after 'forget' was run successfully, see the 'prune' command. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. +`, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { return runForget(forgetOptions, globalOptions, args) diff --git a/cmd/restic/cmd_generate.go b/cmd/restic/cmd_generate.go index 3c9fba3d2..d8588f33b 100644 --- a/cmd/restic/cmd_generate.go +++ b/cmd/restic/cmd_generate.go @@ -14,6 +14,11 @@ var cmdGenerate = &cobra.Command{ Long: ` The "generate" command writes automatically generated files (like the man pages and the auto-completion files for bash and zsh). + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: runGenerate, diff --git a/cmd/restic/cmd_init.go b/cmd/restic/cmd_init.go index cb6d6fbdb..becb02c55 100644 --- a/cmd/restic/cmd_init.go +++ b/cmd/restic/cmd_init.go @@ -12,6 +12,11 @@ var cmdInit = &cobra.Command{ Short: "Initialize a new repository", Long: ` The "init" command initializes a new repository. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_key.go b/cmd/restic/cmd_key.go index 38ad77790..4c056e1ef 100644 --- a/cmd/restic/cmd_key.go +++ b/cmd/restic/cmd_key.go @@ -20,6 +20,11 @@ var cmdKey = &cobra.Command{ Short: "Manage keys (passwords)", Long: ` The "key" command manages keys (passwords) for accessing the repository. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_list.go b/cmd/restic/cmd_list.go index 9aa7dc9eb..56b9b9f86 100644 --- a/cmd/restic/cmd_list.go +++ b/cmd/restic/cmd_list.go @@ -15,6 +15,11 @@ var cmdList = &cobra.Command{ Short: "List objects in the repository", Long: ` The "list" command allows listing objects in the repository based on type. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_ls.go b/cmd/restic/cmd_ls.go index db26467cd..0a5a242e4 100644 --- a/cmd/restic/cmd_ls.go +++ b/cmd/restic/cmd_ls.go @@ -33,6 +33,11 @@ will be listed. If the --recursive flag is used, then the filter will allow traversing into matching directories' subfolders. Any directory paths specified must be absolute (starting with a path separator); paths use the forward slash '/' as separator. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_migrate.go b/cmd/restic/cmd_migrate.go index d5738595e..7f8af12cc 100644 --- a/cmd/restic/cmd_migrate.go +++ b/cmd/restic/cmd_migrate.go @@ -13,6 +13,11 @@ var cmdMigrate = &cobra.Command{ Long: ` The "migrate" command applies migrations to a repository. When no migration name is explicitly given, a list of migrations that can be applied is printed. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_mount.go b/cmd/restic/cmd_mount.go index 69eea376e..1a0dee66f 100644 --- a/cmd/restic/cmd_mount.go +++ b/cmd/restic/cmd_mount.go @@ -44,6 +44,11 @@ You need to specify a sample format for exactly the following timestamp: For details please see the documentation for time.Format() at: https://godoc.org/time#Time.Format + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_options.go b/cmd/restic/cmd_options.go index 6edcbebec..d18a86570 100644 --- a/cmd/restic/cmd_options.go +++ b/cmd/restic/cmd_options.go @@ -13,6 +13,11 @@ var optionsCmd = &cobra.Command{ Short: "Print list of extended options", Long: ` The "options" command prints a list of extended options. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, Hidden: true, DisableAutoGenTag: true, diff --git a/cmd/restic/cmd_prune.go b/cmd/restic/cmd_prune.go index 125b41c7e..07d005c65 100644 --- a/cmd/restic/cmd_prune.go +++ b/cmd/restic/cmd_prune.go @@ -19,6 +19,11 @@ var cmdPrune = &cobra.Command{ Long: ` The "prune" command checks the repository and removes data that is not referenced and therefore not needed any more. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_rebuild_index.go b/cmd/restic/cmd_rebuild_index.go index ec4287af1..768080668 100644 --- a/cmd/restic/cmd_rebuild_index.go +++ b/cmd/restic/cmd_rebuild_index.go @@ -16,6 +16,11 @@ var cmdRebuildIndex = &cobra.Command{ Long: ` The "rebuild-index" command creates a new index based on the pack files in the repository. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_recover.go b/cmd/restic/cmd_recover.go index 677442be7..2a06f301f 100644 --- a/cmd/restic/cmd_recover.go +++ b/cmd/restic/cmd_recover.go @@ -16,6 +16,11 @@ var cmdRecover = &cobra.Command{ The "recover" command build a new snapshot from all directories it can find in the raw data of the repository. It can be used if, for example, a snapshot has been removed by accident with "forget". + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_restore.go b/cmd/restic/cmd_restore.go index 7c056fdab..89741e11b 100644 --- a/cmd/restic/cmd_restore.go +++ b/cmd/restic/cmd_restore.go @@ -20,6 +20,11 @@ a directory. The special snapshot "latest" can be used to restore the latest snapshot in the repository. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_self_update.go b/cmd/restic/cmd_self_update.go index 5aed085de..310c5100f 100644 --- a/cmd/restic/cmd_self_update.go +++ b/cmd/restic/cmd_self_update.go @@ -18,6 +18,11 @@ The command "self-update" 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. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_snapshots.go b/cmd/restic/cmd_snapshots.go index 94cd08836..0e3daa290 100644 --- a/cmd/restic/cmd_snapshots.go +++ b/cmd/restic/cmd_snapshots.go @@ -18,6 +18,11 @@ var cmdSnapshots = &cobra.Command{ Short: "List all snapshots", Long: ` The "snapshots" command lists all snapshots stored in the repository. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_stats.go b/cmd/restic/cmd_stats.go index cc2aa4ce8..a202fd029 100644 --- a/cmd/restic/cmd_stats.go +++ b/cmd/restic/cmd_stats.go @@ -38,6 +38,11 @@ The modes are: * blobs-per-file: A combination of files-by-contents and raw-data. Refer to the online manual for more details about each mode. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_tag.go b/cmd/restic/cmd_tag.go index f120f9cf4..a85f9dc0c 100644 --- a/cmd/restic/cmd_tag.go +++ b/cmd/restic/cmd_tag.go @@ -21,6 +21,11 @@ You can either set/replace the entire set of tags on a snapshot, or add tags to/remove tags from the existing set. When no snapshot-ID is given, all snapshots matching the host, tag and path filter criteria are modified. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_unlock.go b/cmd/restic/cmd_unlock.go index 4b216905d..7f5d44ada 100644 --- a/cmd/restic/cmd_unlock.go +++ b/cmd/restic/cmd_unlock.go @@ -10,6 +10,11 @@ var unlockCmd = &cobra.Command{ Short: "Remove locks other processes created", Long: ` The "unlock" command removes stale locks that have been created by other restic processes. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/cmd/restic/cmd_version.go b/cmd/restic/cmd_version.go index 677079a50..b17103706 100644 --- a/cmd/restic/cmd_version.go +++ b/cmd/restic/cmd_version.go @@ -13,6 +13,11 @@ var versionCmd = &cobra.Command{ Long: ` The "version" command prints detailed information about the build environment and the version of this software. + +EXIT STATUS +=========== + +Exit status is 0 if the command was successful, and non-zero if there was any error. `, DisableAutoGenTag: true, Run: func(cmd *cobra.Command, args []string) {