From bc74cd3ae566d3e60d6d5560c53f2230aaa53c9b Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Fri, 3 Apr 2020 19:44:33 +0200 Subject: [PATCH 1/2] backup/global: Use proper name for command line argument parameters Several paramters printed a generic "string" or "stringArray" name. --- cmd/restic/cmd_backup.go | 12 ++++++------ cmd/restic/global.go | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/cmd/restic/cmd_backup.go b/cmd/restic/cmd_backup.go index 6c0f44863..7df9addcf 100644 --- a/cmd/restic/cmd_backup.go +++ b/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.StringVar(&backupOptions.TimeStamp, "time", "", "time of the backup (ex. '2012-11-01 22:08:41') (default: now)") + 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.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") } diff --git a/cmd/restic/global.go b/cmd/restic/global.go index 6a46b57ee..2c4d1fccd 100644 --- a/cmd/restic/global.go +++ b/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.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.PasswordCommand, "password-command", "", os.Getenv("RESTIC_PASSWORD_COMMAND"), "specify a shell command to obtain a password (default: $RESTIC_PASSWORD_COMMAND)") + 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.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.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)") From 6bee62e3469cd5c63d40cfc2802d35394482c9a6 Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Fri, 3 Apr 2020 19:46:30 +0200 Subject: [PATCH 2/2] Update doc excerpts for `--help` This adds some previously missing changes and the new paramters names from the previous commit. --- doc/020_installation.rst | 2 +- doc/manual_rest.rst | 110 ++++++++++++++++++++++----------------- 2 files changed, 63 insertions(+), 49 deletions(-) diff --git a/doc/020_installation.rst b/doc/020_installation.rst index 8262daaea..92361984d 100644 --- a/doc/020_installation.rst +++ b/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: diff --git a/doc/manual_rest.rst b/doc/manual_rest.rst index e2d9a1b35..2f963f050 100644 --- a/doc/manual_rest.rst +++ b/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) - --cache-dir string set the cache directory. (default: use system default cache directory) - --cleanup-cache auto remove old cache directories - -h, --help help for restic - --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) - --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) - --no-cache do not use a local cache - --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) - -p, --password-file string read the repository password from a file (default: $RESTIC_PASSWORD_FILE) - -q, --quiet do not output comprehensive progress report - -r, --repo string repository to backup to or restore from (default: $RESTIC_REPOSITORY) - --tls-client-cert string path to a file containing PEM encoded TLS client certificate and private key - -v, --verbose n[=-1] be verbose (specify --verbose multiple times or level n) + --cacert file file to load root certificates from (default: use system certificates) + --cache-dir directory set the cache directory. (default: use system default cache directory) + --cleanup-cache auto remove old cache directories + -h, --help help for restic + --json set output mode to JSON for commands that support it + --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-upload int limits uploads to a maximum rate in KiB/s. (default: unlimited) + --no-cache do not use a local cache + --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) + --password-command command specify a shell command to obtain a password (default: $RESTIC_PASSWORD_COMMAND) + -p, --password-file file read the repository password from a file (default: $RESTIC_PASSWORD_FILE) + -q, --quiet do not output comprehensive progress report + -r, --repo repository repository to backup to or restore from (default: $RESTIC_REPOSITORY) + --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) - --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-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) - --files-from string 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) - -h, --help help for backup - --hostname 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 - --parent string use this parent snapshot (default: last snapshot in the repo that has the same target files/directories) - --stdin read backup from stdin - --stdin-filename string file name to use when reading from stdin (default "stdin") - --tag tag add a tag for the new snapshot (can be specified multiple times) - --time string time of the backup (ex. '2012-11-01 22:08:41') (default: now) - --with-atime store the atime for all files and directories + -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-file file read exclude patterns from a file (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 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) + -h, --help help for backup + -H, --host hostname set the hostname for the snapshot manually. To prevent an expensive rescan use the "parent" flag + --iexclude pattern same as --exclude pattern but ignores the casing of filenames + --ignore-inode ignore inode number changes when checking for modified files + -x, --one-file-system exclude other file systems + --parent snapshot use this parent snapshot (default: last snapshot in the repo that has the same target files/directories) + --stdin read backup from stdin + --stdin-filename filename filename to use when reading from stdin (default "stdin") + --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) - --cache-dir string set the cache directory. (default: use system default cache directory) - --cleanup-cache auto remove old cache directories - --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) - --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) - --no-cache do not use a local cache - --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) - -p, --password-file string read the repository password from a file (default: $RESTIC_PASSWORD_FILE) - -q, --quiet do not output comprehensive progress report - -r, --repo string repository to backup to or restore from (default: $RESTIC_REPOSITORY) - --tls-client-cert string path to a file containing PEM encoded TLS client certificate and private key - -v, --verbose n[=-1] be verbose (specify --verbose multiple times or level n) + --cacert file file to load root certificates from (default: use system certificates) + --cache-dir directory set the cache directory. (default: use system default cache directory) + --cleanup-cache auto remove old cache directories + --json set output mode to JSON for commands that support it + --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-upload int limits uploads to a maximum rate in KiB/s. (default: unlimited) + --no-cache do not use a local cache + --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) + --password-command command specify a shell command to obtain a password (default: $RESTIC_PASSWORD_COMMAND) + -p, --password-file file read the repository password from a file (default: $RESTIC_PASSWORD_FILE) + -q, --quiet do not output comprehensive progress report + -r, --repo repository repository to backup to or restore from (default: $RESTIC_REPOSITORY) + --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