- Reference guides
-
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
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!