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 [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 ...]]
                 [--version]
                 ...

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

optional arguments:
  -h, --help            show this help message and exit

global arguments:
  -c [CONFIG_PATHS [CONFIG_PATHS ...]], --config [CONFIG_PATHS [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
  --version             Display installed version number of borgmatic and exit

actions:
                        Specify zero or more actions. Defaults to prune,
                        create, and check. Use --help with action for details:
    init (--init, -I)   Initialize an empty Borg repository
    prune (--prune, -p)
                        Prune archives according to the retention policy
    create (--create, -C)
                        Create archives (actually perform backups)
    check (--check, -k)
                        Check archives for consistency
    extract (--extract, -x)
                        Extract files from a named archive to the current
                        directory
    export-tar (--export-tar)
                        Export an archive to a tar-formatted file or stream
    mount (--mount, -m)
                        Mount files from a named archive as a FUSE filesystem
    umount (--umount, -u)
                        Unmount a FUSE filesystem that was mounted with
                        "borgmatic mount"
    restore (--restore, -r)
                        Restore database dumps from a named archive
    list (--list, -l)   List archives
    info (--info, -i)   Display summary information on archives
    borg                Run an arbitrary Borg command

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

usage: borgmatic init -e ENCRYPTION_MODE [--append-only]
                      [--storage-quota STORAGE_QUOTA] [-h]

Initialize an empty Borg repository

init arguments:
  -e ENCRYPTION_MODE, --encryption ENCRYPTION_MODE
                        Borg repository encryption mode
  --append-only         Create an append-only repository
  --storage-quota STORAGE_QUOTA
                        Create a repository with a fixed storage quota
  -h, --help            Show this help message and exit

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

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

Prune archives according to the retention policy

prune arguments:
  --stats     Display statistics of archive
  --files     Show per-file details
  -h, --help  Show this help message and exit

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

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

Create archives (actually perform backups)

create arguments:
  --progress  Display progress for each file as it is backed up
  --stats     Display statistics of archive
  --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] [-h]

Check archives for consistency

check arguments:
  --progress    Display progress for each file as it is checked
  --repair      Attempt to repair any inconsistencies found (experimental and
                only for interactive use)
  --only CHECK  Run a particular consistency check (repository, archives,
                data, or extract) instead of configured checks; can specify
                flag multiple times
  -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] [--files]
                            [--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 --files)
  --tar-filter TAR_FILTER
                        Name of filter program to pipe data through
  --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 list [--repository REPOSITORY] [--archive ARCHIVE]
                      [--path PATH [PATH ...]] [--short] [--format FORMAT]
                      [--json] [-P PREFIX] [-a GLOB] [--successful]
                      [--sort-by KEYS] [--first N] [--last N] [-e PATTERN]
                      [--exclude-from FILENAME] [--pattern PATTERN]
                      [--patterns-from FILENAME] [-h]

List archives or the contents of an archive

list arguments:
  --repository REPOSITORY
                        Path of repository to list, defaults to the configured
                        repositories
  --archive ARCHIVE     Name of archive to list (or "latest")
  --path PATH [PATH ...]
                        Paths to list from archive, defaults to the entire
                        archive
  --short               Output only archive or 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 GLOB, --glob-archives GLOB
                        Only list archive names matching this glob
  --successful          Only list archive names of successful (non-checkpoint)
                        backups
  --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 info [--repository REPOSITORY] [--archive ARCHIVE] [--json]
                      [-P PREFIX] [-a GLOB] [--sort-by KEYS] [--first N]
                      [--last N] [-h]

Display summary information on archives

info arguments:
  --repository REPOSITORY
                        Path of repository 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 GLOB, --glob-archives GLOB
                        Only show info for archive names matching this glob
  --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 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!