Merge pull request #2461 from rigtorp/man-exit-status

Add documentation on exit status codes to man pages

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

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 {

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 {

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 {

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)

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 {

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 {

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)

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)

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,

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 {

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 {

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 {

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 {

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 {

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 {

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,

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 {

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 {

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 {

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 {

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 {

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 {

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 {

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 {

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 {

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) {