borgmatic

Command-line reference

borgmatic options

Here are all of the available borgmatic command-line options. This includes the separate options for each action sub-command:

usage: borgmatic [-h] [-c [CONFIG_PATHS ...]] [--excludes EXCLUDES_FILENAME]
                 [-n] [-nc] [-v {-1,0,1,2}] [--syslog-verbosity {-1,0,1,2}]
                 [--log-file-verbosity {-1,0,1,2}]
                 [--monitoring-verbosity {-1,0,1,2}] [--log-file LOG_FILE]
                 [--override SECTION.OPTION=VALUE [SECTION.OPTION=VALUE ...]]
                 [--no-environment-interpolation] [--bash-completion]
                 [--version]
                 ...

Simple, configuration-driven backup software for servers and workstations. If
none of the action options are given, then borgmatic defaults to: prune,
compact, create, and check.

options:
  -h, --help            show this help message and exit

global arguments:
  -c [CONFIG_PATHS ...], --config [CONFIG_PATHS ...]
                        Configuration filenames or directories, defaults to:
                        /etc/borgmatic/config.yaml /etc/borgmatic.d
                        $HOME/.config/borgmatic/config.yaml
                        $HOME/.config/borgmatic.d
  --excludes EXCLUDES_FILENAME
                        Deprecated in favor of exclude_patterns within
                        configuration
  -n, --dry-run         Go through the motions, but do not actually write to
                        any repositories
  -nc, --no-color       Disable colored output
  -v {-1,0,1,2}, --verbosity {-1,0,1,2}
                        Display verbose progress to the console (from only
                        errors to very verbose: -1, 0, 1, or 2)
  --syslog-verbosity {-1,0,1,2}
                        Log verbose progress to syslog (from only errors to
                        very verbose: -1, 0, 1, or 2). Ignored when console is
                        interactive or --log-file is given
  --log-file-verbosity {-1,0,1,2}
                        Log verbose progress to log file (from only errors to
                        very verbose: -1, 0, 1, or 2). Only used when --log-
                        file is given
  --monitoring-verbosity {-1,0,1,2}
                        Log verbose progress to monitoring integrations that
                        support logging (from only errors to very verbose: -1,
                        0, 1, or 2)
  --log-file LOG_FILE   Write log messages to this file instead of syslog
  --override SECTION.OPTION=VALUE [SECTION.OPTION=VALUE ...]
                        One or more configuration file options to override
                        with specified values
  --no-environment-interpolation
                        Do not resolve environment variables in configuration
                        file
  --bash-completion     Show bash completion script and exit
  --version             Display installed version number of borgmatic and exit

actions:
                        Specify zero or more actions. Defaults to prune,
                        compact, create, and check. Use --help with action for
                        details:
    rcreate (init, -I)  Create a new, empty Borg repository
    transfer            Transfer archives from one repository to another,
                        optionally upgrading the transferred data (Borg 2.0+
                        only)
    prune (-p)          Prune archives according to the retention policy (with
                        Borg 1.2+, run compact afterwards to actually free
                        space)
    compact             Compact segments to free space (Borg 1.2+ only)
    create (-C)         Create an archive (actually perform a backup)
    check (-k)          Check archives for consistency
    extract (-x)        Extract files from a named archive to the current
                        directory
    export-tar          Export an archive to a tar-formatted file or stream
    mount (-m)          Mount files from a named archive as a FUSE filesystem
    umount (-u)         Unmount a FUSE filesystem that was mounted with
                        "borgmatic mount"
    restore (-r)        Restore database dumps from a named archive
    rlist               List repository
    list (-l)           List archive
    rinfo               Show repository summary information such as disk space
                        used
    info (-i)           Show archive summary information such as disk space
                        used
    break-lock          Break the repository and cache locks left behind by
                        Borg aborting
    borg                Run an arbitrary Borg command

--------------------------------------------------------------------------------

usage: borgmatic rcreate -e ENCRYPTION_MODE
                         [--source-repository KEY_REPOSITORY]
                         [--copy-crypt-key] [--append-only]
                         [--storage-quota STORAGE_QUOTA] [--make-parent-dirs]
                         [-h]

Create a new, empty Borg repository

rcreate arguments:
  -e ENCRYPTION_MODE, --encryption ENCRYPTION_MODE
                        Borg repository encryption mode
  --source-repository KEY_REPOSITORY, --other-repo KEY_REPOSITORY
                        Path to an existing Borg repository whose key material
                        should be reused (Borg 2.x+ only)
  --copy-crypt-key      Copy the crypt key used for authenticated encryption
                        from the source repository, defaults to a new random
                        key (Borg 2.x+ only)
  --append-only         Create an append-only repository
  --storage-quota STORAGE_QUOTA
                        Create a repository with a fixed storage quota
  --make-parent-dirs    Create any missing parent directories of the
                        repository directory
  -h, --help            Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic transfer [--repository REPOSITORY] --source-repository
                          SOURCE_REPOSITORY [--archive ARCHIVE]
                          [--upgrader UPGRADER] [-a PATTERN] [--sort-by KEYS]
                          [--first N] [--last N] [-h]

Transfer archives from one repository to another, optionally upgrading the
transferred data (Borg 2.0+ only)

transfer arguments:
  --repository REPOSITORY
                        Path of existing destination repository to transfer
                        archives to, defaults to the configured repository if
                        there is only one
  --source-repository SOURCE_REPOSITORY
                        Path of existing source repository to transfer
                        archives from
  --archive ARCHIVE     Name of single archive to transfer (or "latest"),
                        defaults to transferring all archives
  --upgrader UPGRADER   Upgrader type used to convert the transfered data,
                        e.g. "From12To20" to upgrade data from Borg 1.2 to 2.0
                        format, defaults to no conversion
  -a PATTERN, --match-archives PATTERN, --glob-archives PATTERN
                        Only transfer archives with names matching this
                        pattern
  --sort-by KEYS        Comma-separated list of sorting keys
  --first N             Only transfer first N archives after other filters are
                        applied
  --last N              Only transfer last N archives after other filters are
                        applied
  -h, --help            Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic prune [--stats] [--list] [-h]

Prune archives according to the retention policy (with Borg 1.2+, run compact
afterwards to actually free space)

prune arguments:
  --stats     Display statistics of archive
  --list      List archives kept/pruned
  -h, --help  Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic compact [--progress] [--cleanup-commits]
                         [--threshold THRESHOLD] [-h]

Compact segments to free space (Borg 1.2+ only)

compact arguments:
  --progress            Display progress as each segment is compacted
  --cleanup-commits     Cleanup commit-only 17-byte segment files left behind
                        by Borg 1.1 (flag in Borg 1.2 only)
  --threshold THRESHOLD
                        Minimum saved space percentage threshold for
                        compacting a segment, defaults to 10
  -h, --help            Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic create [--progress] [--stats] [--list] [--json] [-h]

Create an archive (actually perform a backup)

create arguments:
  --progress       Display progress for each file as it is backed up
  --stats          Display statistics of archive
  --list, --files  Show per-file details
  --json           Output results as JSON
  -h, --help       Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic check [--progress] [--repair] [--only CHECK] [--force] [-h]

Check archives for consistency

check arguments:
  --progress    Display progress for each file as it is checked
  --repair      Attempt to repair any inconsistencies found (for interactive
                use)
  --only CHECK  Run a particular consistency check (repository, archives,
                data, or extract) instead of configured checks (subject to
                configured frequency, can specify flag multiple times)
  --force       Ignore configured check frequencies and run checks
                unconditionally
  -h, --help    Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic extract [--repository REPOSITORY] --archive ARCHIVE
                         [--path PATH [PATH ...]] [--destination PATH]
                         [--strip-components NUMBER] [--progress] [-h]

Extract a named archive to the current directory

extract arguments:
  --repository REPOSITORY
                        Path of repository to extract, defaults to the
                        configured repository if there is only one
  --archive ARCHIVE     Name of archive to extract (or "latest")
  --path PATH [PATH ...], --restore-path PATH [PATH ...]
                        Paths to extract from archive, defaults to the entire
                        archive
  --destination PATH    Directory to extract files into, defaults to the
                        current directory
  --strip-components NUMBER
                        Number of leading path components to remove from each
                        extracted path. Skip paths with fewer elements
  --progress            Display progress for each file as it is extracted
  -h, --help            Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic export-tar [--repository REPOSITORY] --archive ARCHIVE
                            [--path PATH [PATH ...]] --destination PATH
                            [--tar-filter TAR_FILTER] [--list]
                            [--strip-components NUMBER] [-h]

Export an archive to a tar-formatted file or stream

export-tar arguments:
  --repository REPOSITORY
                        Path of repository to export from, defaults to the
                        configured repository if there is only one
  --archive ARCHIVE     Name of archive to export (or "latest")
  --path PATH [PATH ...]
                        Paths to export from archive, defaults to the entire
                        archive
  --destination PATH    Path to destination export tar file, or "-" for stdout
                        (but be careful about dirtying output with --verbosity
                        or --list)
  --tar-filter TAR_FILTER
                        Name of filter program to pipe data through
  --list, --files       Show per-file details
  --strip-components NUMBER
                        Number of leading path components to remove from each
                        exported path. Skip paths with fewer elements
  -h, --help            Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic mount [--repository REPOSITORY] [--archive ARCHIVE]
                       --mount-point PATH [--path PATH [PATH ...]]
                       [--foreground] [--options OPTIONS] [-h]

Mount a named archive as a FUSE filesystem

mount arguments:
  --repository REPOSITORY
                        Path of repository to use, defaults to the configured
                        repository if there is only one
  --archive ARCHIVE     Name of archive to mount (or "latest")
  --mount-point PATH    Path where filesystem is to be mounted
  --path PATH [PATH ...]
                        Paths to mount from archive, defaults to the entire
                        archive
  --foreground          Stay in foreground until ctrl-C is pressed
  --options OPTIONS     Extra Borg mount options
  -h, --help            Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic umount --mount-point PATH [-h]

Unmount a mounted FUSE filesystem

umount arguments:
  --mount-point PATH  Path of filesystem to unmount
  -h, --help          Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic restore [--repository REPOSITORY] --archive ARCHIVE
                         [--database NAME [NAME ...]] [-h]

Restore database dumps from a named archive. (To extract files instead, use
"borgmatic extract".)

restore arguments:
  --repository REPOSITORY
                        Path of repository to restore from, defaults to the
                        configured repository if there is only one
  --archive ARCHIVE     Name of archive to restore from (or "latest")
  --database NAME [NAME ...]
                        Names of databases to restore from archive, defaults
                        to all databases. Note that any databases to restore
                        must be defined in borgmatic's configuration
  -h, --help            Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic rlist [--repository REPOSITORY] [--short] [--format FORMAT]
                       [--json] [-P PREFIX] [-a PATTERN] [--sort-by KEYS]
                       [--first N] [--last N] [-h]

List the archives in a repository

rlist arguments:
  --repository REPOSITORY
                        Path of repository to list, defaults to the configured
                        repositories
  --short               Output only archive names
  --format FORMAT       Format for archive listing
  --json                Output results as JSON
  -P PREFIX, --prefix PREFIX
                        Only list archive names starting with this prefix
  -a PATTERN, --match-archives PATTERN, --glob-archives PATTERN
                        Only list archive names matching this pattern
  --sort-by KEYS        Comma-separated list of sorting keys
  --first N             List first N archives after other filters are applied
  --last N              List last N archives after other filters are applied
  -h, --help            Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic list [--repository REPOSITORY] [--archive ARCHIVE]
                      [--path PATH [PATH ...]] [--find PATH [PATH ...]]
                      [--short] [--format FORMAT] [--json] [-P PREFIX]
                      [-a PATTERN] [--successful] [--sort-by KEYS] [--first N]
                      [--last N] [-e PATTERN] [--exclude-from FILENAME]
                      [--pattern PATTERN] [--patterns-from FILENAME] [-h]

List the files in an archive or search for a file across archives

list arguments:
  --repository REPOSITORY
                        Path of repository containing archive to list,
                        defaults to the configured repositories
  --archive ARCHIVE     Name of the archive to list (or "latest")
  --path PATH [PATH ...]
                        Paths or patterns to list from a single selected
                        archive (via "--archive"), defaults to listing the
                        entire archive
  --find PATH [PATH ...]
                        Partial paths or patterns to search for and list
                        across multiple archives
  --short               Output only path names
  --format FORMAT       Format for file listing
  --json                Output results as JSON
  -P PREFIX, --prefix PREFIX
                        Only list archive names starting with this prefix
  -a PATTERN, --match-archives PATTERN, --glob-archives PATTERN
                        Only list archive names matching this pattern
  --successful          Deprecated; no effect. Newer versions of Borg shows
                        successful (non-checkpoint) archives by default.
  --sort-by KEYS        Comma-separated list of sorting keys
  --first N             List first N archives after other filters are applied
  --last N              List last N archives after other filters are applied
  -e PATTERN, --exclude PATTERN
                        Exclude paths matching the pattern
  --exclude-from FILENAME
                        Exclude paths from exclude file, one per line
  --pattern PATTERN     Include or exclude paths matching a pattern
  --patterns-from FILENAME
                        Include or exclude paths matching patterns from
                        pattern file, one per line
  -h, --help            Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic rinfo [--repository REPOSITORY] [--json] [-h]

Show repository summary information such as disk space used

rinfo arguments:
  --repository REPOSITORY
                        Path of repository to show info for, defaults to the
                        configured repository if there is only one
  --json                Output results as JSON
  -h, --help            Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic info [--repository REPOSITORY] [--archive ARCHIVE] [--json]
                      [-P PREFIX] [-a PATTERN] [--sort-by KEYS] [--first N]
                      [--last N] [-h]

Show archive summary information such as disk space used

info arguments:
  --repository REPOSITORY
                        Path of repository containing archive to show info
                        for, defaults to the configured repository if there is
                        only one
  --archive ARCHIVE     Name of archive to show info for (or "latest")
  --json                Output results as JSON
  -P PREFIX, --prefix PREFIX
                        Only show info for archive names starting with this
                        prefix
  -a PATTERN, --match-archives PATTERN, --glob-archives PATTERN
                        Only show info for archive names matching this pattern
  --sort-by KEYS        Comma-separated list of sorting keys
  --first N             Show info for first N archives after other filters are
                        applied
  --last N              Show info for last N archives after other filters are
                        applied
  -h, --help            Show this help message and exit

--------------------------------------------------------------------------------

usage: borgmatic [-h] [-c [CONFIG_PATHS ...]] [--excludes EXCLUDES_FILENAME]
                 [-n] [-nc] [-v {-1,0,1,2}] [--syslog-verbosity {-1,0,1,2}]
                 [--log-file-verbosity {-1,0,1,2}]
                 [--monitoring-verbosity {-1,0,1,2}] [--log-file LOG_FILE]
                 [--override SECTION.OPTION=VALUE [SECTION.OPTION=VALUE ...]]
                 [--no-environment-interpolation] [--bash-completion]
                 [--version]
                 ...

Simple, configuration-driven backup software for servers and workstations. If
none of the action options are given, then borgmatic defaults to: prune,
compact, create, and check.

options:
  -h, --help            show this help message and exit

global arguments:
  -c [CONFIG_PATHS ...], --config [CONFIG_PATHS ...]
                        Configuration filenames or directories, defaults to:
                        /etc/borgmatic/config.yaml /etc/borgmatic.d
                        $HOME/.config/borgmatic/config.yaml
                        $HOME/.config/borgmatic.d
  --excludes EXCLUDES_FILENAME
                        Deprecated in favor of exclude_patterns within
                        configuration
  -n, --dry-run         Go through the motions, but do not actually write to
                        any repositories
  -nc, --no-color       Disable colored output
  -v {-1,0,1,2}, --verbosity {-1,0,1,2}
                        Display verbose progress to the console (from only
                        errors to very verbose: -1, 0, 1, or 2)
  --syslog-verbosity {-1,0,1,2}
                        Log verbose progress to syslog (from only errors to
                        very verbose: -1, 0, 1, or 2). Ignored when console is
                        interactive or --log-file is given
  --log-file-verbosity {-1,0,1,2}
                        Log verbose progress to log file (from only errors to
                        very verbose: -1, 0, 1, or 2). Only used when --log-
                        file is given
  --monitoring-verbosity {-1,0,1,2}
                        Log verbose progress to monitoring integrations that
                        support logging (from only errors to very verbose: -1,
                        0, 1, or 2)
  --log-file LOG_FILE   Write log messages to this file instead of syslog
  --override SECTION.OPTION=VALUE [SECTION.OPTION=VALUE ...]
                        One or more configuration file options to override
                        with specified values
  --no-environment-interpolation
                        Do not resolve environment variables in configuration
                        file
  --bash-completion     Show bash completion script and exit
  --version             Display installed version number of borgmatic and exit

actions:
                        Specify zero or more actions. Defaults to prune,
                        compact, create, and check. Use --help with action for
                        details:
    rcreate (init, -I)  Create a new, empty Borg repository
    transfer            Transfer archives from one repository to another,
                        optionally upgrading the transferred data (Borg 2.0+
                        only)
    prune (-p)          Prune archives according to the retention policy (with
                        Borg 1.2+, run compact afterwards to actually free
                        space)
    compact             Compact segments to free space (Borg 1.2+ only)
    create (-C)         Create an archive (actually perform a backup)
    check (-k)          Check archives for consistency
    extract (-x)        Extract files from a named archive to the current
                        directory
    export-tar          Export an archive to a tar-formatted file or stream
    mount (-m)          Mount files from a named archive as a FUSE filesystem
    umount (-u)         Unmount a FUSE filesystem that was mounted with
                        "borgmatic mount"
    restore (-r)        Restore database dumps from a named archive
    rlist               List repository
    list (-l)           List archive
    rinfo               Show repository summary information such as disk space
                        used
    info (-i)           Show archive summary information such as disk space
                        used
    break-lock          Break the repository and cache locks left behind by
                        Borg aborting
    borg                Run an arbitrary Borg command

--------------------------------------------------------------------------------

usage: borgmatic borg [--repository REPOSITORY] [--archive ARCHIVE]
                      [-- OPTION [OPTION ...]] [-h]

Run an arbitrary Borg command based on borgmatic's configuration

borg arguments:
  --repository REPOSITORY
                        Path of repository to pass to Borg, defaults to the
                        configured repositories
  --archive ARCHIVE     Name of archive to pass to Borg (or "latest")
  -- OPTION [OPTION ...]
                        Options to pass to Borg, command first ("create",
                        "list", etc). "--" is optional. To specify the
                        repository or the archive, you must use --repository
                        or --archive instead of providing them here.
  -h, --help            Show this help message and exit

Improve this documentation

Have an idea on how to make this documentation even better? Use our issue tracker to send your feedback!