restic
restic is a backup program which allows saving multiple revisions of files and directories in an encrypted repository stored on different backends.
Usage
Usage: restic [command] [options]
Global Options
| Option | Environment | Description |
|---|---|---|
--cacert file | $RESTIC_CACERT | 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 | $RESTIC_COMPRESSION | compression mode (only available for repository format version 2), one of (auto/off/max) (default: $RESTIC_COMPRESSION) (default auto) |
-h, --help | help for restic | |
--http-user-agent string | set a http user agent for outgoing http requests | |
--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 | $RESTIC_KEY_HINT | 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 | $RESTIC_PACK_SIZE | set target pack size in MiB, created pack files may be larger (default: $RESTIC_PACK_SIZE) |
--password-command command | $RESTIC_PASSWORD_COMMAND | shell command to obtain the repository password from (default: $RESTIC_PASSWORD_COMMAND) |
-p, --password-file file | $RESTIC_PASSWORD_FILE | file to read the repository password from (default: $RESTIC_PASSWORD_FILE) |
-q, --quiet | do not output comprehensive progress report | |
-r, --repo repository | $RESTIC_REPOSITORY | repository to backup to or restore from (default: $RESTIC_REPOSITORY) |
--repository-file file | $RESTIC_REPOSITORY_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) | |
--stuck-request-timeout duration | duration after which to retry stuck requests (default 5m0s) | |
--tls-client-cert file | $RESTIC_TLS_CLIENT_CERT | 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) |
backup
The “backup” command creates a new snapshot and saves the files and directories given as the arguments.
Exit Codes:
- Exit status is 0 if the command was successful.
- Exit status is 1 if there was a fatal error (no snapshot created).
- Exit status is 3 if some source data could not be read (incomplete snapshot created).
- Exit status is 10 if the repository does not exist.
- Exit status is 11 if the repository is already locked.
- Exit status is 12 if the password is incorrect.
Usage: restic backup [flags] [FILE/DIR] ...
| Option | Environment | Description |
|---|---|---|
-n, --dry-run | do not upload or write any data, just show what would be done | |
-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 https://bford.info/cachedir/ 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) | |
--exclude-larger-than size | max size of the files to be backed up (allowed suffixes: k/K, m/M, g/G, t/T) | |
--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 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, --host hostname | $RESTIC_HOST | 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 | |
--iexclude-file file | same as —exclude-file but ignores casing of filenames in patterns | |
--ignore-ctime | ignore ctime changes when checking for modified files | |
--ignore-inode | ignore inode number and ctime changes when checking for modified files | |
--no-scan | do not run scanner to estimate size of backup | |
-x, --one-file-system | exclude other file systems, don’t cross filesystem boundaries and subvolumes | |
--parent snapshot | use this parent snapshot (default: latest snapshot in the group determined by —group-by and not newer than the timestamp determined by —time) | |
--read-concurrency n | $RESTIC_READ_CONCURRENCY | read n files concurrently (default: $RESTIC_READ_CONCURRENCY or 2) |
--skip-if-unchanged | skip snapshot creation if identical to parent snapshot | |
--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) | |
--with-atime | store the atime for all files and directories |
cache
The “cache” command allows listing and cleaning local cache directories.
Exit Codes:
- Exit status is 0 if the command was successful.
- Exit status is 1 if there was any error.
Usage: restic cache [flags]
| Option | Environment | Description |
|---|---|---|
--cleanup | remove old cache directories | |
--max-age days | max age in days for cache directories to be considered old (default 30) | |
--no-size | do not output the size of the cache directories |
cat
The “cat” command is used to print internal objects to stdout.
Exit Codes:
- Exit status is 0 if the command was successful.
- Exit status is 1 if there was any error.
- Exit status is 10 if the repository does not exist.
- Exit status is 11 if the repository is already locked.
- Exit status is 12 if the password is incorrect.
Usage: restic cat [flags] [masterkey|config|pack ID|blob ID|snapshot ID|index ID|key ID|lock ID|tree snapshot:subfolder]
check
The “check” command tests the repository for errors and reports any errors it 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 Codes:
- Exit status is 0 if the command was successful.
- Exit status is 1 if there was any error.
- Exit status is 10 if the repository does not exist.
- Exit status is 11 if the repository is already locked.
- Exit status is 12 if the password is incorrect.
Usage: restic check [flags]
| Option | Description |
|---|---|
--read-data | read all data blobs |
--read-data-subset subset | read a subset of data packs, specified as ‘n/t’ for specific part, or either ‘x%’ or ‘x.y%’ or a size in bytes with suffixes k/K, m/M, g/G, t/T for a random subset |
--with-cache | use existing cache, only read uncached data from repository |
copy
The “copy” command copies one or more snapshots from one repository to another.
NOTE: This process will have to both download (read) and upload (write) the entire snapshot(s) due to the different encryption keys used in the source and destination repositories. This may incur higher bandwidth usage and costs than expected during normal backup runs.
NOTE: The copying process does not re-chunk files, which may break deduplication between the files copied and files already stored in the destination repository. This means that copied files, which existed in both the source and destination repository, may occupy up to twice their space in the destination repository. This can be mitigated by the
--copy-chunker-paramsoption when initializing a new destination repository using the “init” command.
Exit Codes:
- Exit status is 0 if the command was successful.
- Exit status is 1 if there was any error.
- Exit status is 10 if the repository does not exist.
- Exit status is 11 if the repository is already locked.
- Exit status is 12 if the password is incorrect.
Usage: restic copy [flags] [snapshotID ...]
| Option | Environment | Description |
|---|---|---|
--from-insecure-no-password | use an empty password for the source repository (insecure) | |
--from-key-hint string | $RESTIC_FROM_KEY_HINT | key ID of key to try decrypting the source repository first (default: $RESTIC_FROM_KEY_HINT) |
--from-password-command command | $RESTIC_FROM_PASSWORD_COMMAND | shell command to obtain the source repository password from (default: $RESTIC_FROM_PASSWORD_COMMAND) |
--from-password-file file | $RESTIC_FROM_PASSWORD_FILE | file to read the source repository password from (default: $RESTIC_FROM_PASSWORD_FILE) |
--from-repo repository | $RESTIC_FROM_REPOSITORY | source repository to copy snapshots from (default: $RESTIC_FROM_REPOSITORY) |
--from-repository-file file | $RESTIC_FROM_REPOSITORY_FILE | file from which to read the source repository location to copy snapshots from (default: $RESTIC_FROM_REPOSITORY_FILE) |
-H, --host host | $RESTIC_HOST | only consider snapshots for this host (can be specified multiple times) (default: $RESTIC_HOST) |
--path path | only consider snapshots including this (absolute) path (can be specified multiple times, snapshots must include all specified paths) | |
--tag tag[,tag,...] | only consider snapshots including tag[,tag,...] (can be specified multiple times) (default []) |
diff
The “diff” command shows differences from the first to the second snapshot. The first characters in each line display what has happened to a particular file or directory:
+The item was added-The item was removedUThe metadata (access mode, timestamps, …) for the item was updatedMThe file’s content was modifiedTThe type was changed, e.g. a file was made a symlink?Bitrot detected: The file’s content has changed but all metadata is the same
Metadata comparison will likely not work if a backup was created using the --ignore-inode or --ignore-ctime option.
To only compare files in specific subfolders, you can use the snapshotID:subfolder syntax, where subfolder is a path within the snapshot.
Exit Codes:
- Exit status is 0 if the command was successful.
- Exit status is 1 if there was any error.
- Exit status is 10 if the repository does not exist.
- Exit status is 11 if the repository is already locked.
- Exit status is 12 if the password is incorrect.
Usage: restic diff [--metadata] snapshotID snapshotID
dump
The “dump” command extracts files from a snapshot from the repository. If a single file is selected, it prints its contents to stdout. Folders are output as a tar (default) or zip file containing the contents of the specified folder. Pass ”/” as file name to dump the whole snapshot as an archive file.
The special snapshotID “latest” can be used to use the latest snapshot in the repository.
To include the folder content at the root of the archive, you can use the snapshotID:subfolder syntax, where subfolder is a path within the snapshot.
Exit Codes:
- Exit status is 0 if the command was successful.
- Exit status is 1 if there was any error.
- Exit status is 10 if the repository does not exist.
- Exit status is 11 if the repository is already locked.
- Exit status is 12 if the password is incorrect.
Usage: restic dump [flags] snapshotID file
| Option | Environment | Description |
|---|---|---|
-a, --archive format | set archive format as “tar” or “zip” (default “tar”) | |
-H, --host host | $RESTIC_HOST | only consider snapshots for this host, when snapshot ID “latest” is given (can be specified multiple times) (default: $RESTIC_HOST) |
--path path | only consider snapshots including this (absolute) path, when snapshot ID “latest” is given (can be specified multiple times, snapshots must include all specified paths) | |
--tag tag[,tag,...] | only consider snapshots including tag[,tag,...], when snapshot ID “latest” is given (can be specified multiple times) (default []) | |
-t, --target path | write the output to target path |
find
The “find” command searches for files or directories in snapshots stored in the repo.
It can also be used to search for restic blobs or trees for troubleshooting.
The default sort option for the snapshots is youngest to oldest. To sort the output from oldest to youngest specify --reverse.
Usage: restic find [flags] PATTERN...
Examples:
restic find config.json
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
Exit Codes:
- Exit status is 0 if the command was successful.
- Exit status is 1 if there was any error.
- Exit status is 10 if the repository does not exist.
- Exit status is 11 if the repository is already locked.
- Exit status is 12 if the password is incorrect.
| Option | Environment | Description |
|---|---|---|
--blob | pattern is a blob-ID | |
-H, --host host | $RESTIC_HOST | only consider snapshots for this host (can be specified multiple times) (default: $RESTIC_HOST) |
--human-readable | print sizes in human readable format | |
-i, --ignore-case | ignore case for pattern | |
-l, --long | use a long listing format showing size and mode | |
-N, --newest string | newest modification date/time | |
-O, --oldest string | oldest modification date/time | |
--pack | pattern is a pack-ID | |
--path path | only consider snapshots including this (absolute) path (can be specified multiple times, snapshots must include all specified paths) | |
-R, --reverse | reverse sort order oldest to newest | |
--show-pack-id | display the pack-ID the blobs belong to (with —blob or —tree) | |
-s, --snapshot id | snapshot id to search in (can be given multiple times) | |
--tag tag[,tag,...] | only consider snapshots including tag[,tag,...] (can be specified multiple times) (default []) | |
--tree | pattern is a tree-ID |
forget
The “forget” command removes snapshots according to a policy. All snapshots are first divided into groups according to --group-by, and after that the policy specified by the --keep-* options is applied to each group individually.
If there are not enough snapshots to keep one for each duration related --keep-{within-,}* option, the oldest snapshot in the group is kept additionally.
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 the unreferenced data after “forget” was run successfully, see the “prune” command.
Please also read the documentation for “forget” to learn about some important security considerations.
Exit Codes:
- Exit status is 0 if the command was successful.
- Exit status is 1 if there was any error.
- Exit status is 10 if the repository does not exist.
- Exit status is 11 if the repository is already locked.
- Exit status is 12 if the password is incorrect.
Usage: restic forget [flags] [snapshot ID] [...]
| Option | Environment | Description |
|---|---|---|
-l, --keep-last n | keep the last n snapshots (use ‘unlimited’ to keep all snapshots) | |
-H, --keep-hourly n | keep the last n hourly snapshots (use ‘unlimited’ to keep all hourly snapshots) | |
-d, --keep-daily n | keep the last n daily snapshots (use ‘unlimited’ to keep all daily snapshots) | |
-w, --keep-weekly n | keep the last n weekly snapshots (use ‘unlimited’ to keep all weekly snapshots) | |
-m, --keep-monthly n | keep the last n monthly snapshots (use ‘unlimited’ to keep all monthly snapshots) | |
-y, --keep-yearly n | keep the last n yearly snapshots (use ‘unlimited’ to keep all yearly snapshots) | |
--keep-within duration | keep snapshots that are newer than duration (e.g., 1y5m7d2h) relative to the latest snapshot | |
--keep-within-hourly duration | keep hourly snapshots newer than duration (e.g., 1y5m7d2h) relative to the latest snapshot | |
--keep-within-daily duration | keep daily snapshots newer than duration (e.g., 1y5m7d2h) relative to the latest snapshot | |
--keep-within-weekly duration | keep weekly snapshots newer than duration (e.g., 1y5m7d2h) relative to the latest snapshot | |
--keep-within-monthly duration | keep monthly snapshots newer than duration (e.g., 1y5m7d2h) relative to the latest snapshot | |
--keep-within-yearly duration | keep yearly snapshots newer than duration (e.g., 1y5m7d2h) relative to the latest snapshot | |
--keep-tag taglist | keep snapshots with this taglist (can be specified multiple times) (default []) | |
--unsafe-allow-remove-all | allow deleting all snapshots of a snapshot group | |
--host host | $RESTIC_HOST | only consider snapshots for this host (can be specified multiple times) (default: $RESTIC_HOST) |
--tag tag[,tag,...] | only consider snapshots including tag[,tag,...] (can be specified multiple times) (default []) | |
--path path | only consider snapshots including this (absolute) path (can be specified multiple times, snapshots must include all specified paths) | |
-c, --compact | use compact output format | |
-g, --group-by group | group snapshots by host, paths and/or tags, separated by comma (disable grouping with ”) (default host,paths) | |
-n, --dry-run | do not delete anything, just print what would be done | |
--prune | automatically run the ‘prune’ command if snapshots have been removed | |
--max-unused limit | tolerate given limit of unused data (absolute bytes with suffixes k/K, m/M, g/G, t/T, %, or ‘unlimited’) (default “5%“) | |
--max-repack-size size | stop after repacking this much data in total (allowed suffixes: k/K, m/M, g/G, t/T) | |
--repack-cacheable-only | only repack packs which are cacheable | |
--repack-small | repack pack files below 80% of target pack size | |
--repack-uncompressed | repack all uncompressed data | |
--repack-smaller-than below-limit | pack below-limit packfiles (allowed suffixes: k/K, m/M) |
init
The “init” command initializes a new repository.
Exit Codes:
- Exit status is 0 if the command was successful.
- Exit status is 1 if there was any error.
Usage: restic init [flags]
| Option | Environment | Description |
|---|---|---|
--copy-chunker-params | Copy chunker parameters from the secondary repository (useful with the copy command) | |
--from-insecure-no-password | Use an empty password for the source repository (insecure) | |
--from-key-hint | $RESTIC_FROM_KEY_HINT | Key ID of key to try decrypting the source repository first |
--from-password-command | $RESTIC_FROM_PASSWORD_COMMAND | Shell command to obtain the source repository password from |
--from-password-file | $RESTIC_FROM_PASSWORD_FILE | File to read the source repository password from |
--from-repo | $RESTIC_FROM_REPOSITORY | Source repository to copy chunker parameters from |
--from-repository-file | $RESTIC_FROM_REPOSITORY_FILE | File from which to read the source repository location to copy chunker parameters from |
--repository-version | Repository format version to use, allowed values are a format version, latest and stable (default “stable”) |
key
The “key” command allows you to set multiple access keys or passwords per repository.
Usage: restic key [command]
key add
Add a new key (password) to the repository; returns the new key ID
Usage: restic key add [flags]
| Option | Environment | Description |
|---|---|---|
-h, --help | help for add | |
--host string | the hostname for new key | |
--new-insecure-no-password | add an empty password for the repository (insecure) | |
--new-password-file file | file from which to read the new password | |
--user string | the username for new key |
key passwd
Change key (password); creates a new key ID and removes the old key ID, returns new key ID
Usage: restic key passwd [flags]
| Option | Environment | Description |
|---|---|---|
-h, --help | help for add | |
--host string | the hostname for new key | |
--new-insecure-no-password | add an empty password for the repository (insecure) | |
--new-password-file file | file from which to read the new password | |
--user string | the username for new key |
key list
List keys (passwords)
Usage: restic key list
key remove
Remove key ID (password) from the repository.
Usage: restic key remove [ID] [flags]
list
The “list” command allows listing objects in the repository based on type.
Exit Codes:
- Exit status is 0 if the command was successful.
- Exit status is 1 if there was any error.
- Exit status is 10 if the repository does not exist.
- Exit status is 11 if the repository is already locked.
- Exit status is 12 if the password is incorrect.
Usage: restic list [flags] [blobs|packs|index|snapshots|keys|locks]
ls
The “ls” command lists files and directories in a snapshot.
The special snapshot ID “latest” can be used to list files and directories of the latest snapshot in the repository. The --host flag can be used in conjunction to select the latest snapshot originating from a certain host only.
File listings can optionally be filtered by directories. Any positional arguments after the snapshot ID are interpreted as absolute directory paths, and only files inside those directories 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.
File listings can be sorted by specifying --sort followed by one of the sort specifiers (name|size|time=mtime|atime|ctime|extension).
The sorting can be reversed by specifying --reverse.
Exit Codes:
- Exit status is 0 if the command was successful.
- Exit status is 1 if there was any error.
- Exit status is 10 if the repository does not exist.
- Exit status is 11 if the repository is already locked.
- Exit status is 12 if the password is incorrect.
Usage: restic ls [flags] snapshotID [dir...]
| Option | Environment | Description |
|---|---|---|
-H, --host | $RESTIC_HOST | Only consider snapshots for this host, when snapshot ID “latest” is given (can be specified multiple times) |
--human-readable | Print sizes in human readable format | |
-l, --long | Use a long listing format showing size and mode | |
--ncdu | Output NCDU export format (pipe into ncdu -f -) | |
--path | Only consider snapshots including this (absolute) path, when snapshot ID “latest” is given (can be specified multiple times) | |
--recursive | Include files in subfolders of the listed directories | |
--reverse | Reverse sorted output | |
-s, --sort | Sort output by (name|size|time=mtime|atime|ctime|extension) (default name) | |
--tag | Only consider snapshots including tag[,tag,…], when snapshot ID “latest” is given (can be specified multiple times) (default []) |
mount
The “mount” command mounts the repository via fuse to a directory. This is a read-only mount.
Snapshot Directories:
If you need a different template for directories that contain snapshots,
you can pass a time template via --time-template and path templates via --path-template.
Example time template without colons: --time-template "2006-01-02_15-04-05"
You need to specify a sample format for exactly the following timestamp: Mon Jan 2 15:04:05 -0700 MST 2006
For path templates, you can use the following patterns which will be replaced:
%iby short snapshot ID%Iby long snapshot ID%uby username%hby hostname%tby tags%Tby timestamp as specified by--time-template
The default path templates are:
ids/%isnapshots/%Thosts/%h/%Ttags/%t/%T
Exit Codes:
- Exit status is 0 if the command was successful.
- Exit status is 1 if there was any error.
- Exit status is 10 if the repository does not exist.
- Exit status is 11 if the repository is already locked.
- Exit status is 12 if the password is incorrect.
Usage: restic mount [flags] mountpoint
| Option | Environment | Description |
|---|---|---|
--allow-other | Allow other users to access the data in the mounted directory | |
-H, --host | $RESTIC_HOST | Only consider snapshots for this host (can be specified multiple times) |
--no-default-permissions | For --allow-other, ignore Unix permissions and allow users to read all snapshot files | |
--owner-root | Use root as the owner of files and dirs | |
--path | Only consider snapshots including this (absolute) path (can be specified multiple times, snapshots must include all specified paths) | |
--path-template | Set template for path names (can be specified multiple times) | |
--tag | Only consider snapshots including tag[,tag,...] (can be specified multiple times) (default []) | |
--time-template | Set template to use for times (default “2006-01-02T15:04:05Z07:00”) |
prune
The “prune” command checks the repository and removes data that is not referenced and therefore not needed any more.
Usage: restic prune [flags]
| Option | Environment | Description |
|---|---|---|
-n, --dry-run | Do not modify the repository, just print what would be done | |
--max-repack-size | Stop after repacking this much data in total (allowed suffixes: k/K, m/M, g/G, t/T) | |
--max-unused | Tolerate given limit of unused data (absolute value in bytes with suffixes k/K, m/M, g/G, t/T, a value in % or the word ‘unlimited’) (default “5%“) | |
--repack-cacheable-only | Only repack packs which are cacheable | |
--repack-small | Repack pack files below 80% of target pack size | |
--repack-smaller-than | Pack below-limit packfiles (allowed suffixes: k/K, m/M) | |
--repack-uncompressed | Repack all uncompressed data | |
--unsafe-recover-no-free-space | UNSAFE, read the documentation before using! Try to recover a repository stuck with no free space. Do not use without trying ‘prune —max-repack-size 0’ first. |
restore
The “restore” command extracts the data from a snapshot from the repository to a directory.
The special snapshotID “latest” can be used to restore the latest snapshot in the repository.
To only restore a specific subfolder, you can use the snapshotID:subfolder syntax, where subfolder is a path within the snapshot.
Usage: restic restore [flags] snapshotID
| Option | Environment | Description |
|---|---|---|
--delete | Delete files from target directory if they do not exist in snapshot. Use --dry-run -vv to check what would be deleted | |
--dry-run | Do not write any data, just show what would be done | |
-e, --exclude | Exclude a pattern (can be specified multiple times) | |
--exclude-file | Read exclude patterns from a file (can be specified multiple times) | |
--exclude-xattr | Exclude xattr by pattern (can be specified multiple times) | |
-H, --host | $RESTIC_HOST | Only consider snapshots for this host, when snapshot ID “latest” is given (can be specified multiple times) |
--iexclude | Same as --exclude but ignores the casing of filenames | |
--iexclude-file | Same as --exclude-file but ignores casing of filenames in patterns | |
--iinclude | Same as --include but ignores the casing of filenames | |
--iinclude-file | Same as --include-file but ignores casing of filenames in patterns | |
-i, --include | Include a pattern (can be specified multiple times) | |
--include-file | Read include patterns from a file (can be specified multiple times) | |
--include-xattr | Include xattr by pattern (can be specified multiple times) | |
--overwrite | Overwrite behavior, one of (always|if-changed|if-newer|never) (default always) | |
--path | Only consider snapshots including this (absolute) path, when snapshot ID “latest” is given (can be specified multiple times) | |
--sparse | Restore files as sparse | |
--tag | Only consider snapshots including tag[,tag,...], when snapshot ID “latest” is given (can be specified multiple times) (default []) | |
-t, --target | Directory to extract data to | |
--verify | Verify restored files content |
rewrite
The “rewrite” command excludes files from existing snapshots. It creates new snapshots containing the same data as the original ones, but without the files you specify to exclude. All metadata (time, host, tags) will be preserved.
The snapshots to rewrite are specified using the --host, --tag and --path options, or by providing a list of snapshot IDs. Please note that specifying neither any of these options nor a snapshot ID will cause the command to rewrite all snapshots.
The special tag ‘rewrite’ will be added to the new snapshots to distinguish them from the original ones, unless --forget is used. If the --forget option is used, the original snapshots will instead be directly removed from the repository.
Please note that the --forget option only removes the snapshots and not the actual data stored in the repository. In order to delete the no longer referenced data, use the “prune” command.
When rewrite is used with the --snapshot-summary option, a new snapshot is created containing statistics summary data. Only two fields in the summary will be non-zero: TotalFilesProcessed and TotalBytesProcessed.
When rewrite is called with one of the --exclude options, TotalFilesProcessed and TotalBytesProcessed will be updated in the snapshot summary.
Usage: restic rewrite [flags] [snapshotID ...]
| Option | Environment | Description |
|---|---|---|
-n, --dry-run | Do not do anything, just print what would be done | |
-e, --exclude | Exclude a pattern (can be specified multiple times) | |
--exclude-file | Read exclude patterns from a file (can be specified multiple times) | |
--forget | Remove original snapshots after creating new ones | |
-H, --host | $RESTIC_HOST | Only consider snapshots for this host (can be specified multiple times) |
--iexclude | Same as --exclude but ignores the casing of filenames | |
--iexclude-file | Same as --exclude-file but ignores casing of filenames in patterns | |
--new-host | Replace hostname | |
--new-time | Replace time of the backup | |
--path | Only consider snapshots including this (absolute) path (can be specified multiple times; snapshots must include all specified paths) | |
-s, --snapshot-summary | Create snapshot summary record if it does not exist | |
--tag | Only consider snapshots including tag[,tag,…] (can be specified multiple times) (default: []) |
snapshots
The “snapshots” command lists all snapshots stored in the repository.
Usage: restic snapshots [flags] [snapshotID ...]
| Option | Environment | Description |
|---|---|---|
-c, --compact | use compact output format | |
-g, --group-by group | group snapshots by host, paths and/or tags, separated by comma | |
-H, --host host | $RESTIC_HOST | only consider snapshots for this host (can be specified multiple times) |
--latest n | only show the last n snapshots for each host and path | |
--path path | only consider snapshots including this (absolute) path (can be specified multiple times, snapshots must include all specified paths) | |
--tag tag[,tag,...] | only consider snapshots including tag[,tag,...] (can be specified multiple times) (default []) |
stats
The “stats” command walks one or multiple snapshots in a repository and accumulates statistics about the data stored therein. It reports on the number of unique files and their sizes, according to one of the counting modes as given by the --mode flag.
It operates on all snapshots matching the selection criteria or all snapshots if nothing is specified. The special snapshot ID “latest” is also supported. Some modes make more sense over just a single snapshot, while others are useful across all snapshots, depending on what you are trying to calculate.
The modes are:
- restore-size: (default) Counts the size of the restored files.
- files-by-contents: Counts total size of unique files, where a file is considered unique if it has unique contents.
- raw-data: Counts the size of blobs in the repository, regardless of how many files reference them.
- blobs-per-file: A combination of files-by-contents and raw-data.
Refer to the online manual for more details about each mode.
Usage: restic stats [flags] [snapshot ID] [...]
| Option | Environment | Description |
|---|---|---|
-H, --host host | $RESTIC_HOST | only consider snapshots for this host (can be specified multiple times) |
--mode string | counting mode: restore-size (default), files-by-contents, blobs-per-file or raw-data (default “restore-size”) | |
--path path | only consider snapshots including this (absolute) path (can be specified multiple times, snapshots must include all specified paths) | |
--tag tag[,tag,...] | only consider snapshots including tag[,tag,...] (can be specified multiple times) (default []) |
tag
The “tag” command allows you to modify tags on exiting snapshots.
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 snapshotID is given, all snapshots matching the host, tag and path filter criteria are modified.
Usage: restic tag [flags] [snapshotID ...]
| Option | Environment | Description |
|---|---|---|
--add tags | tags which will be added to the existing tags in the format tag[,tag,...] (can be given multiple times) (default []) | |
-H, --host host | $RESTIC_HOST | only consider snapshots for this host (can be specified multiple times) (default: $RESTIC_HOST) |
--path path | only consider snapshots including this (absolute) path (can be specified multiple times, snapshots must include all specified paths) | |
--remove tags | tags which will be removed from the existing tags in the format tag[,tag,...] (can be given multiple times) (default []) | |
--set tags | tags which will replace the existing tags in the format tag[,tag,...] (can be given multiple times) (default []) | |
--tag tag[,tag,...] | only consider snapshots including tag[,tag,…] (can be specified multiple times) (default []) |
unlock
The “unlock” command removes stale locks that have been created by other restic processes.
Usage: restic unlock [--remove-all] [flags]