From 18990dbed8bb3fca31be4f0c39f0cbdb52e2d924 Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Sat, 25 May 2024 20:47:22 +0200 Subject: [PATCH 1/2] backup: refer to backed up data as backup source not target A backup reads from the source and writes it to the backup target (repository). The name "target" is kept within the source code as it's used there excessively. --- cmd/restic/cmd_backup.go | 6 +++--- doc/faq.rst | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/cmd/restic/cmd_backup.go b/cmd/restic/cmd_backup.go index 4890f82ff..e5369f7b9 100644 --- a/cmd/restic/cmd_backup.go +++ b/cmd/restic/cmd_backup.go @@ -101,7 +101,7 @@ func init() { f.StringVar(&backupOptions.Parent, "parent", "", "use this parent `snapshot` (default: latest snapshot in the group determined by --group-by and not newer than the timestamp determined by --time)") backupOptions.GroupBy = restic.SnapshotGroupByOptions{Host: true, Path: true} f.VarP(&backupOptions.GroupBy, "group-by", "g", "`group` snapshots by host, paths and/or tags, separated by comma (disable grouping with '')") - f.BoolVarP(&backupOptions.Force, "force", "f", false, `force re-reading the target files/directories (overrides the "parent" flag)`) + f.BoolVarP(&backupOptions.Force, "force", "f", false, `force re-reading the source files/directories (overrides the "parent" flag)`) initExcludePatternOptions(f, &backupOptions.excludePatternOptions) @@ -158,7 +158,7 @@ func filterExisting(items []string) (result []string, err error) { } if len(result) == 0 { - return nil, errors.Fatal("all target directories/files do not exist") + return nil, errors.Fatal("all source directories/files do not exist") } return @@ -403,7 +403,7 @@ func collectTargets(opts BackupOptions, args []string) (targets []string, err er // and have the ability to use both files-from and args at the same time. targets = append(targets, args...) if len(targets) == 0 && !opts.Stdin { - return nil, errors.Fatal("nothing to backup, please specify target files/dirs") + return nil, errors.Fatal("nothing to backup, please specify source files/dirs") } targets, err = filterExisting(targets) diff --git a/doc/faq.rst b/doc/faq.rst index 8e56b5d9e..19879d817 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -100,7 +100,7 @@ Restic handles globbing and expansion in the following ways: - Globbing is only expanded for lines read via ``--files-from`` - Environment variables are not expanded in the file read via ``--files-from`` - ``*`` is expanded for paths read via ``--files-from`` -- e.g. For backup targets given to restic as arguments on the shell, neither glob expansion nor shell variable replacement is done. If restic is called as ``restic backup '*' '$HOME'``, it will try to backup the literal file(s)/dir(s) ``*`` and ``$HOME`` +- e.g. For backup sources given to restic as arguments on the shell, neither glob expansion nor shell variable replacement is done. If restic is called as ``restic backup '*' '$HOME'``, it will try to backup the literal file(s)/dir(s) ``*`` and ``$HOME`` - Double-asterisk ``**`` only works in exclude patterns as this is a custom extension built into restic; the shell must not expand it From 107f18849ceadfaa03a66815ab95cab1189e8b89 Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Sat, 25 May 2024 23:16:22 +0200 Subject: [PATCH 2/2] doc: update help output in manual_rest.rst --- doc/manual_rest.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/doc/manual_rest.rst b/doc/manual_rest.rst index 34116fe86..188ebcb70 100644 --- a/doc/manual_rest.rst +++ b/doc/manual_rest.rst @@ -13,6 +13,8 @@ Usage help is available: restic is a backup program which allows saving multiple revisions of files and directories in an encrypted repository stored on different backends. + The full documentation can be found at https://restic.readthedocs.io/ . + Usage: restic [command] @@ -47,17 +49,19 @@ Usage help is available: 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 or $RESTIC_CACERT) --cache-dir directory set the cache directory. (default: use system default cache directory) --cleanup-cache auto remove old cache directories --compression mode compression mode (only available for repository format version 2), one of (auto|off|max) (default: $RESTIC_COMPRESSION) (default auto) -h, --help help for restic + --insecure-no-password use an empty password for the repository, must be passed to every restic command (insecure) --insecure-tls skip TLS certificate verification when connecting to the repository (insecure) --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 rate limits downloads to a maximum rate in KiB/s. (default: unlimited) --limit-upload rate limits uploads to a maximum rate in KiB/s. (default: unlimited) --no-cache do not use a local cache + --no-extra-verify skip additional verification of data before upload (see documentation) --no-lock do not lock the repository, this allows some operations on read-only repositories -o, --option key=value set extended option (key=value, can be specified multiple times) --pack-size size set target pack size in MiB, created pack files may be larger (default: $RESTIC_PACK_SIZE) @@ -67,7 +71,7 @@ Usage help is available: -r, --repo repository repository to backup to or restore from (default: $RESTIC_REPOSITORY) --repository-file file file to read the repository location from (default: $RESTIC_REPOSITORY_FILE) --retry-lock duration retry to lock the repository if it is already locked, takes a value like 5m or 2h (default: no retries) - --tls-client-cert file path to a file containing PEM encoded TLS client certificate and private key + --tls-client-cert file path to a file containing PEM encoded TLS client certificate and private key (default: $RESTIC_TLS_CLIENT_CERT) -v, --verbose be verbose (specify multiple times or a level using --verbose=n, max level/times is 2) Use "restic [command] --help" for more information about a command. @@ -105,10 +109,10 @@ command: --files-from file read the files to backup from file (can be combined with file args; can be specified multiple times) --files-from-raw file read the files to backup from file (can be combined with file args; can be specified multiple times) --files-from-verbatim 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 source files/directories (overrides the "parent" flag) -g, --group-by group group snapshots by host, paths and/or tags, separated by comma (disable grouping with '') (default host,paths) -h, --help help for backup - -H, --host 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 (default: $RESTIC_HOST). To prevent an expensive rescan use the "parent" flag --iexclude pattern same as --exclude pattern but ignores the casing of filenames --iexclude-file file same as --exclude-file but ignores casing of filenames in patterns --ignore-ctime ignore ctime changes when checking for modified files @@ -119,22 +123,25 @@ command: --read-concurrency n read n files concurrently (default: $RESTIC_READ_CONCURRENCY or 2) --stdin read backup from stdin --stdin-filename filename filename to use when reading from stdin (default "stdin") + --stdin-from-command interpret arguments as command to execute and store its stdout --tag tags add tags for the new snapshot in the format `tag[,tag,...]` (can be specified multiple times) (default []) --time time time of the backup (ex. '2012-11-01 22:08:41') (default: now) --use-fs-snapshot use filesystem snapshot where possible (currently only Windows VSS) --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 or $RESTIC_CACERT) --cache-dir directory set the cache directory. (default: use system default cache directory) --cleanup-cache auto remove old cache directories --compression mode compression mode (only available for repository format version 2), one of (auto|off|max) (default: $RESTIC_COMPRESSION) (default auto) + --insecure-no-password use an empty password for the repository, must be passed to every restic command (insecure) --insecure-tls skip TLS certificate verification when connecting to the repository (insecure) --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 rate limits downloads to a maximum rate in KiB/s. (default: unlimited) --limit-upload rate limits uploads to a maximum rate in KiB/s. (default: unlimited) --no-cache do not use a local cache + --no-extra-verify skip additional verification of data before upload (see documentation) --no-lock do not lock the repository, this allows some operations on read-only repositories -o, --option key=value set extended option (key=value, can be specified multiple times) --pack-size size set target pack size in MiB, created pack files may be larger (default: $RESTIC_PACK_SIZE) @@ -144,7 +151,7 @@ command: -r, --repo repository repository to backup to or restore from (default: $RESTIC_REPOSITORY) --repository-file file file to read the repository location from (default: $RESTIC_REPOSITORY_FILE) --retry-lock duration retry to lock the repository if it is already locked, takes a value like 5m or 2h (default: no retries) - --tls-client-cert file path to a file containing PEM encoded TLS client certificate and private key + --tls-client-cert file path to a file containing PEM encoded TLS client certificate and private key (default: $RESTIC_TLS_CLIENT_CERT) -v, --verbose be verbose (specify multiple times or a level using --verbose=n, max level/times is 2) Subcommands that support showing progress information such as ``backup``,