-
How-to guides
- 📥 Set up backups
- 🔀 Make per-application backups
- 🔒 Provide your passwords
- ☁️ Make backups redundant
- 📏 Deal with very large backups
- 🔎 Inspect your backups
- 🚨 Monitor your backups
- 📤 Extract a backup
- 🗄️ Backup your databases
- 🧹 Add preparation and cleanup steps
- 💾 Backup to a removable drive/server
- 🔧 Run arbitrary Borg commands
- 📦 Upgrade borgmatic/Borg
- 🏗️ Develop on borgmatic
- Reference guides
borgmatic options
Here are all of the available borgmatic command-line flags for the most recent version of borgmatic, including the separate flags for each action (sub-command). Most of the flags listed here do not have equivalents in borgmatic's configuration file.
If you're using an older version of borgmatic, some of these flags may not be
present in that version and you should instead use borgmatic --help or
borgmatic [action name] --help (where [action name] is the name of an
action like list, create, etc.).
usage: borgmatic [-h] [-c CONFIG_PATHS] [-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 OPTION.SUBOPTION=VALUE]
[--no-environment-interpolation] [--bash-completion]
[--fish-completion] [--version]
...
Simple, configuration-driven backup software for servers and workstations. If
no actions 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 filename or directory, can specify flag
multiple times, defaults to:
/etc/borgmatic/config.yaml /etc/borgmatic.d
$HOME/.config/borgmatic/config.yaml
$HOME/.config/borgmatic.d
-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: -2
(disabled), -1 (errors only), 0 (responses to actions,
the default), 1 (info about steps borgmatic is
taking), or 2 (debug)
--syslog-verbosity {-2,-1,0,1,2}
Log verbose progress to syslog: -2 (disabled, the
default), -1 (errors only), 0 (responses to actions),
1 (info about steps borgmatic is taking), or 2 (debug)
--log-file-verbosity {-2,-1,0,1,2}
When --log-file is given, log verbose progress to
file: -2 (disabled), -1 (errors only), 0 (responses to
actions), 1 (info about steps borgmatic is taking, the
default), or 2 (debug)
--monitoring-verbosity {-2,-1,0,1,2}
When a monitoring integration supporting logging is
configured, log verbose progress to it: -2 (disabled),
-1 (errors only), responses to actions (0), 1 (info
about steps borgmatic is taking, the default), or 2
(debug)
--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 OPTION.SUBOPTION=VALUE
Configuration file option to override with specified
value, can specify flag multiple times
--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
config Perform configuration file related operations
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 data source (e.g. 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
key Perform repository key related operations
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]
[-a PATTERN] [--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)
-a PATTERN, --match-archives PATTERN, --glob-archives PATTERN
Only check archives with names matching this pattern
--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] [--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, --restore-path PATH
Path to extract from archive, can specify flag
multiple times, 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 config [-h] {bootstrap,generate,validate} ...
Perform configuration file related operations
config arguments:
-h, --help Show this help message and exit
config sub-actions:
{bootstrap,generate,validate}
bootstrap Extract the borgmatic configuration files from a named
archive
generate Generate a sample borgmatic configuration file
validate Validate borgmatic configuration files specified with
--config (see borgmatic --help)
--------------------------------------------------------------------------------
usage: borgmatic config bootstrap --repository REPOSITORY
[--borgmatic-source-directory BORGMATIC_SOURCE_DIRECTORY]
[--archive ARCHIVE] [--destination PATH]
[--strip-components NUMBER] [--progress]
[-h]
Extract the borgmatic configuration files from a named archive
config bootstrap arguments:
--repository REPOSITORY
Path of repository to extract config files from
--borgmatic-source-directory BORGMATIC_SOURCE_DIRECTORY
Path that stores the config files used to create an
archive and additional source files used for temporary
internal state like borgmatic database dumps. Defaults
to ~/.borgmatic
--archive ARCHIVE Name of archive to extract config files from, defaults
to "latest"
--destination PATH Directory to extract config files into, defaults to /
--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 config generate [-s SOURCE_FILENAME]
[-d DESTINATION_FILENAME] [--overwrite] [-h]
Generate a sample borgmatic configuration file
config generate arguments:
-s SOURCE_FILENAME, --source SOURCE_FILENAME
Optional configuration file to merge into the
generated configuration, useful for upgrading your
configuration
-d DESTINATION_FILENAME, --destination DESTINATION_FILENAME
Destination configuration file, default:
/etc/borgmatic/config.yaml
--overwrite Whether to overwrite any existing destination file,
defaults to false
-h, --help Show this help message and exit
--------------------------------------------------------------------------------
usage: borgmatic config validate [-s] [-h]
Validate borgmatic configuration files specified with --config (see borgmatic
--help)
config validate arguments:
-s, --show Show the validated configuration after all include merging has
occurred
-h, --help Show this help message and exit
--------------------------------------------------------------------------------
usage: borgmatic export-tar [--repository REPOSITORY] --archive ARCHIVE
[--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 to export from archive, can specify flag multiple
times, 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] [--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 to mount from archive, can specify multiple
times, 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
[--data-source NAME] [--schema NAME]
[--hostname HOSTNAME] [--port PORT]
[--username USERNAME] [--password PASSWORD]
[--restore-path RESTORE_PATH] [-h]
Restore data source (e.g. 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")
--data-source NAME, --database NAME
Name of data source (e.g. database) to restore from
archive, must be defined in borgmatic's configuration,
can specify flag multiple times, defaults to all data
sources in the archive
--schema NAME Name of schema to restore from the data source, can
specify flag multiple times, defaults to all schemas.
Schemas are only supported for PostgreSQL and MongoDB
databases
--hostname HOSTNAME Database hostname to restore to. Defaults to the
"restore_hostname" option in borgmatic's configuration
--port PORT Database port to restore to. Defaults to the
"restore_port" option in borgmatic's configuration
--username USERNAME Username with which to connect to the database.
Defaults to the "restore_username" option in
borgmatic's configuration
--password PASSWORD Password with which to connect to the restore
database. Defaults to the "restore_password" option in
borgmatic's configuration
--restore-path RESTORE_PATH
Path to restore SQLite database dumps to. Defaults to
the "restore_path" option 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] [--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] [--find PATH] [--short] [--format FORMAT]
[--json] [-P PREFIX] [-a PATTERN] [--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 or pattern to list from a single selected archive
(via "--archive"), can specify flag multiple times,
defaults to listing the entire archive
--find PATH Partial path or pattern to search for and list across
multiple archives, can specify flag multiple times
--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
--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!