borgmatic

Command-line reference

borgmatic options

Here are all of the available borgmatic command-line options, including the separate options for each action sub-command. Note that most of the flags listed here do not have equivalents in borgmatic's configuration file.

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

Simple, configuration-driven backup software for servers and workstations. If
none of the action options are given, then borgmatic defaults to: create,
prune, compact, 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 {-2,-1,0,1,2}, --verbosity {-2,-1,0,1,2}
                        Display verbose progress to the console (disabled,
                        errors only, default, some, or lots: -2, -1, 0, 1, or
                        2)
  --syslog-verbosity {-2,-1,0,1,2}
                        Log verbose progress to syslog (disabled, errors only,
                        default, some, or lots: -2, -1, 0, 1, or 2). Ignored
                        when console is interactive or --log-file is given
  --log-file-verbosity {-2,-1,0,1,2}
                        Log verbose progress to log file (disabled, errors
                        only, default, some, or lots: -2, -1, 0, 1, or 2).
                        Only used when --log-file is given
  --monitoring-verbosity {-2,-1,0,1,2}
                        Log verbose progress to monitoring integrations that
                        support logging (from disabled, errors only, default,
                        some, or lots: -2, -1, 0, 1, or 2)
  --log-file LOG_FILE   Write log messages to this file instead of syslog
  --log-file-format LOG_FILE_FORMAT
                        Log format string used for log messages written to the
                        log file
  --log-json            Write log messages and console output as one JSON
                        object per log line instead of formatted text
  --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
  --fish-completion     Show fish completion script and exit
  --version             Display installed version number of borgmatic and exit

actions:
                        Specify zero or more actions. Defaults to create,
                        prune, compact, 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+, borgmatic
                        1.5.23+ 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]
                         [--repository 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]
  --repository REPOSITORY
                        Path of the new repository to create (must be already
                        specified in a borgmatic configuration file), defaults
                        to the configured repository if there is only one
  --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] [--progress] [-a PATTERN]
                          [--sort-by KEYS] [--first N] [--last N]
                          [--oldest TIMESPAN] [--newest TIMESPAN]
                          [--older TIMESPAN] [--newer TIMESPAN] [-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 transferred data,
                        e.g. "From12To20" to upgrade data from Borg 1.2 to 2.0
                        format, defaults to no conversion
  --progress            Display progress as each archive is transferred
  -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
  --oldest TIMESPAN     Transfer archives within a specified time range
                        starting from the timestamp of the oldest archive
                        (e.g. 7d or 12m) [Borg 2.x+ only]
  --newest TIMESPAN     Transfer archives within a time range that ends at
                        timestamp of the newest archive and starts a specified
                        time range ago (e.g. 7d or 12m) [Borg 2.x+ only]
  --older TIMESPAN      Transfer archives that are older than the specified
                        time range (e.g. 7d or 12m) from the current time
                        [Borg 2.x+ only]
  --newer TIMESPAN      Transfer archives that are newer than the specified
                        time range (e.g. 7d or 12m) from the current time
                        [Borg 2.x+ only]
  -h, --help            Show this help message and exit

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

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

Create an archive (actually perform a backup)

create arguments:
  --repository REPOSITORY
                        Path of specific existing repository to backup to
                        (must be already specified in a borgmatic
                        configuration file)
  --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 prune [--repository REPOSITORY] [--stats] [--list]
                       [--oldest TIMESPAN] [--newest TIMESPAN]
                       [--older TIMESPAN] [--newer TIMESPAN] [-h]

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

prune arguments:
  --repository REPOSITORY
                        Path of specific existing repository to prune (must be
                        already specified in a borgmatic configuration file)
  --stats               Display statistics of archive
  --list                List archives kept/pruned
  --oldest TIMESPAN     Prune archives within a specified time range starting
                        from the timestamp of the oldest archive (e.g. 7d or
                        12m) [Borg 2.x+ only]
  --newest TIMESPAN     Prune archives within a time range that ends at
                        timestamp of the newest archive and starts a specified
                        time range ago (e.g. 7d or 12m) [Borg 2.x+ only]
  --older TIMESPAN      Prune archives that are older than the specified time
                        range (e.g. 7d or 12m) from the current time [Borg
                        2.x+ only]
  --newer TIMESPAN      Prune archives that are newer than the specified time
                        range (e.g. 7d or 12m) from the current time [Borg
                        2.x+ only]
  -h, --help            Show this help message and exit

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

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

Compact segments to free space [Borg 1.2+, borgmatic 1.5.23+ only]

compact arguments:
  --repository REPOSITORY
                        Path of specific existing repository to compact (must
                        be already specified in a borgmatic configuration
                        file)
  --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 check [--repository REPOSITORY] [--progress] [--repair]
                       [--only CHECK] [--force] [-h]

Check archives for consistency

check arguments:
  --repository REPOSITORY
                        Path of specific existing repository to check (must be
                        already specified in a borgmatic configuration file)
  --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 or "all" to strip all leading path
                        components. 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] [--first N] [--last N]
                       [--oldest TIMESPAN] [--newest TIMESPAN]
                       [--older TIMESPAN] [--newer TIMESPAN]
                       [--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
  --first N             Mount first N archives after other filters are applied
  --last N              Mount last N archives after other filters are applied
  --oldest TIMESPAN     Mount archives within a specified time range starting
                        from the timestamp of the oldest archive (e.g. 7d or
                        12m) [Borg 2.x+ only]
  --newest TIMESPAN     Mount archives within a time range that ends at
                        timestamp of the newest archive and starts a specified
                        time range ago (e.g. 7d or 12m) [Borg 2.x+ only]
  --older TIMESPAN      Mount archives that are older than the specified time
                        range (e.g. 7d or 12m) from the current time [Borg
                        2.x+ only]
  --newer TIMESPAN      Mount archives that are newer than the specified time
                        range (e.g. 7d or 12m) from the current time [Borg
                        2.x+ only]
  --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 ...]]
                         [--schema 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
  --schema NAME [NAME ...]
                        Names of schemas to restore from the database,
                        defaults to all schemas. Schemas are only supported
                        for PostgreSQL and MongoDB databases
  -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] [--oldest TIMESPAN]
                       [--newest TIMESPAN] [--older TIMESPAN]
                       [--newer TIMESPAN] [-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
                        Deprecated. 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
  --oldest TIMESPAN     List archives within a specified time range starting
                        from the timestamp of the oldest archive (e.g. 7d or
                        12m) [Borg 2.x+ only]
  --newest TIMESPAN     List archives within a time range that ends at
                        timestamp of the newest archive and starts a specified
                        time range ago (e.g. 7d or 12m) [Borg 2.x+ only]
  --older TIMESPAN      List archives that are older than the specified time
                        range (e.g. 7d or 12m) from the current time [Borg
                        2.x+ only]
  --newer TIMESPAN      List archives that are newer than the specified time
                        range (e.g. 7d or 12m) from the current time [Borg
                        2.x+ only]
  -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
                        Deprecated. 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] [--oldest TIMESPAN] [--newest TIMESPAN]
                      [--older TIMESPAN] [--newer TIMESPAN] [-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
                        Deprecated. 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
  --oldest TIMESPAN     Show info for archives within a specified time range
                        starting from the timestamp of the oldest archive
                        (e.g. 7d or 12m) [Borg 2.x+ only]
  --newest TIMESPAN     Show info for archives within a time range that ends
                        at timestamp of the newest archive and starts a
                        specified time range ago (e.g. 7d or 12m) [Borg 2.x+
                        only]
  --older TIMESPAN      Show info for archives that are older than the
                        specified time range (e.g. 7d or 12m) from the current
                        time [Borg 2.x+ only]
  --newer TIMESPAN      Show info for archives that are newer than the
                        specified time range (e.g. 7d or 12m) from the current
                        time [Borg 2.x+ only]
  -h, --help            Show this help message and exit

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

usage: borgmatic break-lock [--repository REPOSITORY] [-h]

Break Borg repository and cache locks left behind by Borg aborting

break-lock arguments:
  --repository REPOSITORY
                        Path of repository to break the lock for, defaults to
                        the configured repository if there is only one
  -h, --help            Show this help message and exit

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

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!