Merge pull request #2682 from MichaelEischer/cleanup-cli-paramter-names

Cleanup CLI parameter names for backup / global flags

cmd/restic/cmd_backup.go

@@ -103,24 +103,24 @@ func init() {
 	cmdRoot.AddCommand(cmdBackup)
 
 	f := cmdBackup.Flags()
-	f.StringVar(&backupOptions.Parent, "parent", "", "use this parent snapshot (default: last snapshot in the repo that has the same target files/directories)")
+	f.StringVar(&backupOptions.Parent, "parent", "", "use this parent `snapshot` (default: last snapshot in the repo that has the same target files/directories)")
 	f.BoolVarP(&backupOptions.Force, "force", "f", false, `force re-reading the target files/directories (overrides the "parent" flag)`)
 	f.StringArrayVarP(&backupOptions.Excludes, "exclude", "e", nil, "exclude a `pattern` (can be specified multiple times)")
-	f.StringArrayVar(&backupOptions.InsensitiveExcludes, "iexclude", nil, "same as `--exclude` but ignores the casing of filenames")
+	f.StringArrayVar(&backupOptions.InsensitiveExcludes, "iexclude", nil, "same as --exclude `pattern` but ignores the casing of filenames")
 	f.StringArrayVar(&backupOptions.ExcludeFiles, "exclude-file", nil, "read exclude patterns from a `file` (can be specified multiple times)")
 	f.BoolVarP(&backupOptions.ExcludeOtherFS, "one-file-system", "x", false, "exclude other file systems")
-	f.StringArrayVar(&backupOptions.ExcludeIfPresent, "exclude-if-present", nil, "takes filename[:header], exclude contents of directories containing filename (except filename itself) if header of that file is as provided (can be specified multiple times)")
+	f.StringArrayVar(&backupOptions.ExcludeIfPresent, "exclude-if-present", nil, "takes `filename[:header]`, exclude contents of directories containing filename (except filename itself) if header of that file is as provided (can be specified multiple times)")
 	f.BoolVar(&backupOptions.ExcludeCaches, "exclude-caches", false, `excludes cache directories that are marked with a CACHEDIR.TAG file. See http://bford.info/cachedir/spec.html for the Cache Directory Tagging Standard`)
 	f.BoolVar(&backupOptions.Stdin, "stdin", false, "read backup from stdin")
-	f.StringVar(&backupOptions.StdinFilename, "stdin-filename", "stdin", "file name to use when reading from stdin")
+	f.StringVar(&backupOptions.StdinFilename, "stdin-filename", "stdin", "`filename` to use when reading from stdin")
 	f.StringArrayVar(&backupOptions.Tags, "tag", nil, "add a `tag` for the new snapshot (can be specified multiple times)")
 
 	f.StringVarP(&backupOptions.Host, "host", "H", "", "set the `hostname` for the snapshot manually. To prevent an expensive rescan use the \"parent\" flag")
 	f.StringVar(&backupOptions.Host, "hostname", "", "set the `hostname` for the snapshot manually")
 	f.MarkDeprecated("hostname", "use --host")
 
-	f.StringArrayVar(&backupOptions.FilesFrom, "files-from", nil, "read the files to backup from file (can be combined with file args/can be specified multiple times)")
+	f.StringArrayVar(&backupOptions.FilesFrom, "files-from", nil, "read the files to backup from `file` (can be combined with file args/can be specified multiple times)")
-	f.StringVar(&backupOptions.TimeStamp, "time", "", "time of the backup (ex. '2012-11-01 22:08:41') (default: now)")
+	f.StringVar(&backupOptions.TimeStamp, "time", "", "`time` of the backup (ex. '2012-11-01 22:08:41') (default: now)")
 	f.BoolVar(&backupOptions.WithAtime, "with-atime", false, "store the atime for all files and directories")
 	f.BoolVar(&backupOptions.IgnoreInode, "ignore-inode", false, "ignore inode number changes when checking for modified files")
 }

cmd/restic/global.go

@@ -94,18 +94,18 @@ func init() {
 	})
 
 	f := cmdRoot.PersistentFlags()
-	f.StringVarP(&globalOptions.Repo, "repo", "r", os.Getenv("RESTIC_REPOSITORY"), "repository to backup to or restore from (default: $RESTIC_REPOSITORY)")
+	f.StringVarP(&globalOptions.Repo, "repo", "r", os.Getenv("RESTIC_REPOSITORY"), "`repository` to backup to or restore from (default: $RESTIC_REPOSITORY)")
-	f.StringVarP(&globalOptions.PasswordFile, "password-file", "p", os.Getenv("RESTIC_PASSWORD_FILE"), "read the repository password from a file (default: $RESTIC_PASSWORD_FILE)")
+	f.StringVarP(&globalOptions.PasswordFile, "password-file", "p", os.Getenv("RESTIC_PASSWORD_FILE"), "read the repository password from a `file` (default: $RESTIC_PASSWORD_FILE)")
-	f.StringVarP(&globalOptions.KeyHint, "key-hint", "", os.Getenv("RESTIC_KEY_HINT"), "key ID of key to try decrypting first (default: $RESTIC_KEY_HINT)")
+	f.StringVarP(&globalOptions.KeyHint, "key-hint", "", os.Getenv("RESTIC_KEY_HINT"), "`key` ID of key to try decrypting first (default: $RESTIC_KEY_HINT)")
-	f.StringVarP(&globalOptions.PasswordCommand, "password-command", "", os.Getenv("RESTIC_PASSWORD_COMMAND"), "specify a shell command to obtain a password (default: $RESTIC_PASSWORD_COMMAND)")
+	f.StringVarP(&globalOptions.PasswordCommand, "password-command", "", os.Getenv("RESTIC_PASSWORD_COMMAND"), "specify a shell `command` to obtain a password (default: $RESTIC_PASSWORD_COMMAND)")
 	f.BoolVarP(&globalOptions.Quiet, "quiet", "q", false, "do not output comprehensive progress report")
 	f.CountVarP(&globalOptions.Verbose, "verbose", "v", "be verbose (specify --verbose multiple times or level `n`)")
 	f.BoolVar(&globalOptions.NoLock, "no-lock", false, "do not lock the repo, this allows some operations on read-only repos")
 	f.BoolVarP(&globalOptions.JSON, "json", "", false, "set output mode to JSON for commands that support it")
-	f.StringVar(&globalOptions.CacheDir, "cache-dir", "", "set the cache directory. (default: use system default cache directory)")
+	f.StringVar(&globalOptions.CacheDir, "cache-dir", "", "set the cache `directory`. (default: use system default cache directory)")
 	f.BoolVar(&globalOptions.NoCache, "no-cache", false, "do not use a local cache")
 	f.StringSliceVar(&globalOptions.CACerts, "cacert", nil, "`file` to load root certificates from (default: use system certificates)")
-	f.StringVar(&globalOptions.TLSClientCert, "tls-client-cert", "", "path to a file containing PEM encoded TLS client certificate and private key")
+	f.StringVar(&globalOptions.TLSClientCert, "tls-client-cert", "", "path to a `file` containing PEM encoded TLS client certificate and private key")
 	f.BoolVar(&globalOptions.CleanupCache, "cleanup-cache", false, "auto remove old cache directories")
 	f.IntVar(&globalOptions.LimitUploadKb, "limit-upload", 0, "limits uploads to a maximum rate in KiB/s. (default: unlimited)")
 	f.IntVar(&globalOptions.LimitDownloadKb, "limit-download", 0, "limits downloads to a maximum rate in KiB/s. (default: unlimited)")

doc/020_installation.rst

@@ -288,7 +288,7 @@ Restic can write out man pages and bash/zsh compatible autocompletion scripts:
 
     $ ./restic generate --help
 
-    The "generate" command writes automatically generated files like the man pages
+    The "generate" command writes automatically generated files (like the man pages
     and the auto-completion files for bash and zsh).
 
     Usage:

doc/manual_rest.rst

@@ -22,7 +22,7 @@ Usage help is available:
       check         Check the repository for errors
       diff          Show differences between two snapshots
       dump          Print a backed-up file to stdout
-      find          Find a file or directory
+      find          Find a file, a directory or restic IDs
       forget        Remove snapshots from the repository
       generate      Generate manual pages and auto-completion files (bash, zsh)
       help          Help about any command
@@ -34,30 +34,33 @@ Usage help is available:
       mount         Mount the repository
       prune         Remove unneeded data from the repository
       rebuild-index Build a new index file
+      recover       Recover data from the repository
       restore       Extract the data from a snapshot
+      self-update   Update the restic binary
       snapshots     List all snapshots
-      stats         Count up sizes and show information about repository data
+      stats         Scan the repository and show basic statistics
       tag           Modify tags on snapshots
       unlock        Remove locks other processes created
       version       Print version information
 
     Flags:
-          --cacert file              file to load root certificates from (default: use system certificates)
+          --cacert file                file to load root certificates from (default: use system certificates)
-          --cache-dir string         set the cache directory. (default: use system default cache directory)
+          --cache-dir directory        set the cache directory. (default: use system default cache directory)
-          --cleanup-cache            auto remove old cache directories
+          --cleanup-cache              auto remove old cache directories
-      -h, --help                     help for restic
+      -h, --help                       help for restic
-          --json                     set output mode to JSON for commands that support it
+          --json                       set output mode to JSON for commands that support it
-          --key-hint string          key ID of key to try decrypting first (default: $RESTIC_KEY_HINT)
+          --key-hint key               key ID of key to try decrypting first (default: $RESTIC_KEY_HINT)
-          --limit-download int       limits downloads to a maximum rate in KiB/s. (default: unlimited)
+          --limit-download int         limits downloads to a maximum rate in KiB/s. (default: unlimited)
-          --limit-upload int         limits uploads to a maximum rate in KiB/s. (default: unlimited)
+          --limit-upload int           limits uploads to a maximum rate in KiB/s. (default: unlimited)
-          --no-cache                 do not use a local cache
+          --no-cache                   do not use a local cache
-          --no-lock                  do not lock the repo, this allows some operations on read-only repos
+          --no-lock                    do not lock the repo, this allows some operations on read-only repos
-      -o, --option key=value         set extended option (key=value, can be specified multiple times)
+      -o, --option key=value           set extended option (key=value, can be specified multiple times)
-      -p, --password-file string     read the repository password from a file (default: $RESTIC_PASSWORD_FILE)
+          --password-command command   specify a shell command to obtain a password (default: $RESTIC_PASSWORD_COMMAND)
-      -q, --quiet                    do not output comprehensive progress report
+      -p, --password-file file         read the repository password from a file (default: $RESTIC_PASSWORD_FILE)
-      -r, --repo string              repository to backup to or restore from (default: $RESTIC_REPOSITORY)
+      -q, --quiet                      do not output comprehensive progress report
-          --tls-client-cert string   path to a file containing PEM encoded TLS client certificate and private key
+      -r, --repo repository            repository to backup to or restore from (default: $RESTIC_REPOSITORY)
-      -v, --verbose n[=-1]           be verbose (specify --verbose multiple times or level n)
+          --tls-client-cert file       path to a file containing PEM encoded TLS client certificate and private key
+      -v, --verbose n                  be verbose (specify --verbose multiple times or level n)
 
     Use "restic [command] --help" for more information about a command.
 
@@ -73,42 +76,53 @@ command:
     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.
+
     Usage:
       restic backup [flags] FILE/DIR [FILE/DIR] ...
 
     Flags:
-      -e, --exclude pattern                  exclude a pattern (can be specified multiple times)
+      -e, --exclude pattern                        exclude a pattern (can be specified multiple times)
-          --exclude-caches                   excludes cache directories that are marked with a CACHEDIR.TAG file. See http://bford.info/cachedir/spec.html for the Cache Directory Tagging Standard
+          --exclude-caches                         excludes cache directories that are marked with a CACHEDIR.TAG file. See http://bford.info/cachedir/spec.html for the Cache Directory Tagging Standard
-          --exclude-file file                read exclude patterns from a file (can be specified multiple times)
+          --exclude-file file                      read exclude patterns from a file (can be specified multiple times)
-          --exclude-if-present stringArray   takes filename[:header], exclude contents of directories containing filename (except filename itself) if header of that file is as provided (can be specified multiple times)
+          --exclude-if-present filename[:header]   takes filename[:header], exclude contents of directories containing filename (except filename itself) if header of that file is as provided (can be specified multiple times)
-          --files-from string                read the files to backup from file (can be combined with file args/can be specified multiple times)
+          --files-from file                        read the files to backup from file (can be combined with file args/can be specified multiple times)
-      -f, --force                            force re-reading the target files/directories (overrides the "parent" flag)
+      -f, --force                                  force re-reading the target files/directories (overrides the "parent" flag)
-      -h, --help                             help for backup
+      -h, --help                                   help for backup
-          --hostname hostname                set the hostname for the snapshot manually. To prevent an expensive rescan use the "parent" flag
+      -H, --host hostname                          set the hostname for the snapshot manually. To prevent an expensive rescan use the "parent" flag
-      -x, --one-file-system                  exclude other file systems
+          --iexclude pattern                       same as --exclude pattern but ignores the casing of filenames
-          --parent string                    use this parent snapshot (default: last snapshot in the repo that has the same target files/directories)
+          --ignore-inode                           ignore inode number changes when checking for modified files
-          --stdin                            read backup from stdin
+      -x, --one-file-system                        exclude other file systems
-          --stdin-filename string            file name to use when reading from stdin (default "stdin")
+          --parent snapshot                        use this parent snapshot (default: last snapshot in the repo that has the same target files/directories)
-          --tag tag                          add a tag for the new snapshot (can be specified multiple times)
+          --stdin                                  read backup from stdin
-          --time string                      time of the backup (ex. '2012-11-01 22:08:41') (default: now)
+          --stdin-filename filename                filename to use when reading from stdin (default "stdin")
-          --with-atime                       store the atime for all files and directories
+          --tag tag                                add a tag for the new snapshot (can be specified multiple times)
+          --time time                              time of the backup (ex. '2012-11-01 22:08:41') (default: now)
+          --with-atime                             store the atime for all files and directories
 
     Global Flags:
-          --cacert file              file to load root certificates from (default: use system certificates)
+          --cacert file                file to load root certificates from (default: use system certificates)
-          --cache-dir string         set the cache directory. (default: use system default cache directory)
+          --cache-dir directory        set the cache directory. (default: use system default cache directory)
-          --cleanup-cache            auto remove old cache directories
+          --cleanup-cache              auto remove old cache directories
-          --json                     set output mode to JSON for commands that support it
+          --json                       set output mode to JSON for commands that support it
-          --key-hint string          key ID of key to try decrypting first (default: $RESTIC_KEY_HINT)
+          --key-hint key               key ID of key to try decrypting first (default: $RESTIC_KEY_HINT)
-          --limit-download int       limits downloads to a maximum rate in KiB/s. (default: unlimited)
+          --limit-download int         limits downloads to a maximum rate in KiB/s. (default: unlimited)
-          --limit-upload int         limits uploads to a maximum rate in KiB/s. (default: unlimited)
+          --limit-upload int           limits uploads to a maximum rate in KiB/s. (default: unlimited)
-          --no-cache                 do not use a local cache
+          --no-cache                   do not use a local cache
-          --no-lock                  do not lock the repo, this allows some operations on read-only repos
+          --no-lock                    do not lock the repo, this allows some operations on read-only repos
-      -o, --option key=value         set extended option (key=value, can be specified multiple times)
+      -o, --option key=value           set extended option (key=value, can be specified multiple times)
-      -p, --password-file string     read the repository password from a file (default: $RESTIC_PASSWORD_FILE)
+          --password-command command   specify a shell command to obtain a password (default: $RESTIC_PASSWORD_COMMAND)
-      -q, --quiet                    do not output comprehensive progress report
+      -p, --password-file file         read the repository password from a file (default: $RESTIC_PASSWORD_FILE)
-      -r, --repo string              repository to backup to or restore from (default: $RESTIC_REPOSITORY)
+      -q, --quiet                      do not output comprehensive progress report
-          --tls-client-cert string   path to a file containing PEM encoded TLS client certificate and private key
+      -r, --repo repository            repository to backup to or restore from (default: $RESTIC_REPOSITORY)
-      -v, --verbose n[=-1]           be verbose (specify --verbose multiple times or level n)
+          --tls-client-cert file       path to a file containing PEM encoded TLS client certificate and private key
+      -v, --verbose n                  be verbose (specify --verbose multiple times or level n)
 
 Subcommand that support showing progress information such as ``backup``,
 ``check`` and ``prune`` will do so unless the quiet flag ``-q`` or