# Scripting

This is a list of how certain tasks may be accomplished when you use restic via scripts.

## Check if a repository is already initialized

You may find a need to check if a repository is already initialized, perhaps to prevent your script from trying to initialize a repository multiple times (the `init` command contains a check to prevent overwriting existing repositories). The command `cat config` may be used for this purpose:

    $ restic -r /srv/restic-repo cat config
    Fatal: repository does not exist: unable to open config file: stat /srv/restic-repo/config: no such file or directory
    Is there a repository at the following location?
    /srv/restic-repo

If a repository does not exist, restic (since 0.17.0) will return exit code `10` and print a corresponding error message. Older versions return exit code `1`. Note that restic will also return exit code `1` if a different error is encountered (e.g.: incorrect password to `cat config`) and it may print a different error message. If there are no errors, restic will return a zero exit code and print the repository metadata.

## Exit codes

Restic commands return an exit code that signals whether the command was successful. The following table provides a general description, see the help of each command for a more specific description.

Warning

New exit codes will be added over time. If an unknown exit code is returned, then it MUST be treated as a command failure.

0 | Command was successful
1 | Command failed, see command help for more details
2 | Go runtime error
3 | `backup` command could not read some source data
10 | Repository does not exist (since restic 0.17.0)
11 | Failed to lock repository (since restic 0.17.0)
12 | Wrong password (since restic 0.17.1)
130 | Restic was interrupted using SIGINT or SIGSTOP

## JSON output

Restic outputs JSON data to `stdout` if requested with the `--json` flag. The structure of that data varies depending on the circumstance. The JSON output of most restic commands are documented here.

Note

Not all commands support JSON output. If a command does not support JSON output, feel free to submit a pull request!

Warning

We try to keep the JSON output backwards compatible. However, new message types or fields may be added at any time. Similarly, enum-like fields for which a fixed list of allowed values is documented may be extended at any time.

### Output formats

Currently only the output on `stdout` is JSON formatted. Errors printed on `stderr` are still printed as plain text messages. The generated JSON output uses one of the following two formats.

#### Single JSON document

Several commands output a single JSON document that can be parsed in its entirety. Depending on the command, the output consists of either a single or multiple lines.

#### JSON lines

Several commands, in particular long running ones or those that generate a large output, use a format also known as JSON lines. It consists of a stream of new-line separated JSON messages. You can determine the nature of the message using the `message_type` field.

### backup

The `backup` command uses the JSON lines format with the following message types.

#### Status

`message_type` | Always “status”
`seconds_elapsed` | Time since backup started
`seconds_remaining` | Estimated time remaining
`percent_done` | Percentage of data backed up (bytes_done/total_bytes)
`total_files` | Total number of files detected
`files_done` | Files completed (backed up to repo)
`total_bytes` | Total number of bytes in backup set
`bytes_done` | Number of bytes completed (backed up to repo)
`error_count` | Number of errors
`current_files` | List of files currently being backed up

#### Error

`message_type` | Always “error”
`error.message` | Error message
`during` | What restic was trying to do
`item` | Usually, the path of the problematic file

#### Verbose Status

Verbose status provides details about the progress, including details about backed up files.

`message_type` | Always “verbose_status”
`action` | Either “new”, “unchanged”, “modified” or “scan_finished”
`item` | The item in question
`duration` | How long it took, in seconds
`data_size` | How big the item is
`metadata_size` | How big the metadata is
`total_files` | Total number of files

#### Summary

Summary is the last output line in a successful backup.

`message_type` | Always “summary”
`files_new` | Number of new files
`files_changed` | Number of files that changed
`files_unmodified` | Number of files that did not change
`dirs_new` | Number of new directories
`dirs_changed` | Number of directories that changed
`dirs_unmodified` | Number of directories that did not change
`data_blobs` | Number of data blobs added
`tree_blobs` | Number of tree blobs added
`data_added` | Amount of (uncompressed) data added, in bytes
`data_added_packed` | Amount of data added (after compression), in bytes
`total_files_processed` | Total number of files processed
`total_bytes_processed` | Total number of bytes processed
`total_duration` | Total time it took for the operation to complete
`snapshot_id` | ID of the new snapshot. Field is omitted if snapshot creation was skipped

### cat

The `cat` command returns data about various objects in the repository, which are stored in JSON form. Specifying `--json` or `--quiet` will suppress any non-JSON messages the command generates.

### diff

The `diff` command uses the JSON lines format with the following message types.

#### change

`message_type` | Always “change”
`path` | Path that has changed
`modifier` | Type of change, a concatenation of the following characters: “+” = added, “-” = removed, “T” = entry type changed, “M” = file content changed, “U” = metadata changed, “?” = bitrot detected

#### statistics

`message_type` | Always “statistics”
`source_snapshot` | ID of first snapshot
`target_snapshot` | ID of second snapshot
`changed_files` | Number of changed files
`added` | DiffStat object, see below
`removed` | DiffStat object, see below

DiffStat object

`files` | Number of changed files
`dirs` | Number of changed directories
`others` | Number of changed other directory entries
`data_blobs` | Number of data blobs
`tree_blobs` | Number of tree blobs
`bytes` | Number of bytes

### find

The `find` command outputs a single JSON document containing an array of JSON objects with matches for your search term. These matches are organized by snapshot.

If the `--blob` or `--tree` option is passed, then the output is an array of Blob objects.

`hits` | Number of matches in the snapshot
`snapshot` | ID of the snapshot
`matches` | Array of Match objects detailing a match

Match object

`path` | Object path
`permissions` | UNIX permissions
`type` | Object type e.g. file, dir, etc…
`atime` | Access time
`mtime` | Modification time
`ctime` | Change time
`name` | Object name
`user` | Name of owner
`group` | Name of group
`inode` | Inode number
`mode` | UNIX file mode, shorthand of `permissions`
`device_id` | OS specific device identifier
`links` | Number of hardlinks
`uid` | ID of owner
`gid` | ID of group
`size` | Size of object in bytes

Blob object

`object_type` | Either “blob” or “tree”
`id` | ID of found blob
`path` | Path in snapshot
`parent_tree` | Parent tree blob, only set for type “blob”
`snapshot` | Snapshot ID
`time` | Snapshot timestamp

### forget

The `forget` command prints a single JSON document containing an array of ForgetGroups. If specific snapshot IDs are specified, then no output is generated.

The `prune` command does not yet support JSON such that `forget --prune` results in a mix of JSON and text output.

#### ForgetGroup

`tags` | Tags identifying the snapshot group
`host` | Host identifying the snapshot group
`paths` | Paths identifying the snapshot group
`keep` | Array of Snapshot objects that are kept
`remove` | Array of Snapshot objects that were removed
`reasons` | Array of Reason objects describing why a snapshot is kept

Snapshot object

`time` | Timestamp of when the backup was started
`parent` | ID of the parent snapshot
`tree` | ID of the root tree blob
`paths` | List of paths included in the backup
`hostname` | Hostname of the backed up machine
`username` | Username the backup command was run as
`uid` | ID of owner
`gid` | ID of group
`excludes` | List of paths and globs excluded from the backup
`tags` | List of tags for the snapshot in question
`program_version` | restic version used to create snapshot
`id` | Snapshot ID
`short_id` | Snapshot ID, short form

Reason object

`snapshot` | Snapshot object, including `id` and `short_id` fields
`matches` | Array containing descriptions of the matching criteria
`counters` | Object containing counters used by the policies

### init

The `init` command uses the JSON lines format, but only outputs a single message.

`message_type` | Always “initialized”
`id` | ID of the created repository
`repository` | URL of the repository

### key list

The `key list` command returns an array of objects with the following structure.

`current` | Is currently used key?
`id` | Unique key ID
`userName` | User who created it
`hostName` | Name of machine it was created on
`created` | Timestamp when it was created

### ls

The `ls` command uses the JSON lines format with the following message types. As an exception, the `struct_type` field is used to determine the message type.

#### snapshot

`message_type` | Always “snapshot”
`struct_type` | Always “snapshot” (deprecated)
`time` | Timestamp of when the backup was started
`parent` | ID of the parent snapshot
`tree` | ID of the root tree blob
`paths` | List of paths included in the backup
`hostname` | Hostname of the backed up machine
`username` | Username the backup command was run as
`uid` | ID of owner
`gid` | ID of group
`excludes` | List of paths and globs excluded from the backup
`tags` | List of tags for the snapshot in question
`id` | Snapshot ID
`short_id` | Snapshot ID, short form

#### node

`message_type` | Always “node”
`struct_type` | Always “node” (deprecated)
`name` | Node name
`type` | Node type
`path` | Node path
`uid` | UID of node
`gid` | GID of node
`size` | Size in bytes
`mode` | Node mode
`atime` | Node access time
`mtime` | Node modification time
`ctime` | Node creation time
`inode` | Inode number of node

### restore

The `restore` command uses the JSON lines format with the following message types.

#### Status

`message_type` | Always “status”
`seconds_elapsed` | Time since restore started
`percent_done` | Percentage of data restored (bytes_restored/total_bytes)
`total_files` | Total number of files detected
`files_restored` | Files restored
`files_skipped` | Files skipped due to overwrite setting
`total_bytes` | Total number of bytes in restore set
`bytes_restored` | Number of bytes restored
`bytes_skipped` | Total size of skipped files

#### Error

`message_type` | Always “error”
`error.message` | Error message
`during` | Always “restore”
`item` | Usually, the path of the problematic file

#### Verbose Status

Verbose status provides details about the progress, including details about restored files. Only printed if –verbose=2 is specified.

`message_type` | Always “verbose_status”
`action` | Either “restored”, “updated”, “unchanged” or “deleted”
`item` | The item in question
`size` | Size of the item in bytes

#### Summary

`message_type` | Always “summary”
`seconds_elapsed` | Time since restore started
`total_files` | Total number of files detected
`files_restored` | Files restored
`files_skipped` | Files skipped due to overwrite setting
`total_bytes` | Total number of bytes in restore set
`bytes_restored` | Number of bytes restored
`bytes_skipped` | Total size of skipped files

### snapshots

The snapshots command returns a single JSON object, an array with objects of the structure outlined below.

`time` | Timestamp of when the backup was started
`parent` | ID of the parent snapshot
`tree` | ID of the root tree blob
`paths` | List of paths included in the backup
`hostname` | Hostname of the backed up machine
`username` | Username the backup command was run as
`uid` | ID of owner
`gid` | ID of group
`excludes` | List of paths and globs excluded from the backup
`tags` | List of tags for the snapshot in question
`program_version` | restic version used to create snapshot
`summary` | Snapshot statistics, see “Summary object”
`id` | Snapshot ID
`short_id` | Snapshot ID, short form

Summary object

The contained statistics reflect the information at the point in time when the snapshot was created.

`backup_start` | Time at which the backup was started
`backup_end` | Time at which the backup was completed
`files_new` | Number of new files
`files_changed` | Number of files that changed
`files_unmodified` | Number of files that did not change
`dirs_new` | Number of new directories
`dirs_changed` | Number of directories that changed
`dirs_unmodified` | Number of directories that did not change
`data_blobs` | Number of data blobs added
`tree_blobs` | Number of tree blobs added
`data_added` | Amount of (uncompressed) data added, in bytes
`data_added_packed` | Amount of data added (after compression), in bytes
`total_files_processed` | Total number of files processed
`total_bytes_processed` | Total number of bytes processed

### stats

The stats command returns a single JSON object.

`total_size` | Repository size in bytes
`total_file_count` | Number of files backed up in the repository
`total_blob_count` | Number of blobs in the repository
`snapshots_count` | Number of processed snapshots
`total_uncompressed_size` | Repository size in bytes if blobs were uncompressed
`compression_ratio` | Factor by which the already compressed data has shrunk due to compression
`compression_progress` | Percentage of already compressed data
`compression_space_saving` | Overall space saving due to compression

### version

The version command returns a single JSON object.

`version` | restic version
`go_version` | Go compile version
`go_os` | Go OS
`go_arch` | Go architecture