mirror of
https://github.com/borgmatic-collective/borgmatic.git
synced 2026-07-29 04:43:02 +02:00
146 lines
5.3 KiB
Markdown
146 lines
5.3 KiB
Markdown
---
|
|
title: 🔄 Overrides
|
|
eleventyNavigation:
|
|
key: 🔄 Overrides
|
|
parent: 💻 Command-line
|
|
---
|
|
In more complex multi-application setups, you may want to override particular
|
|
borgmatic configuration file options at the time you run borgmatic. For
|
|
instance, you could reuse a common configuration file for multiple
|
|
applications, but then set the repository for each application at runtime. Or
|
|
you might want to try a variant of an option for testing purposes without
|
|
actually touching your configuration file.
|
|
|
|
<span class="minilink minilink-addedin">New in version 2.0.0</span>
|
|
Whatever the reason, you can override borgmatic configuration options at the
|
|
command-line, as there's a command-line flag corresponding to every
|
|
configuration option (with its underscores converted to dashes).
|
|
|
|
For instance, to override the `compression` configuration option, use the
|
|
corresponding `--compression` flag on the command-line:
|
|
|
|
```bash
|
|
borgmatic create --compression zstd
|
|
```
|
|
|
|
What this does is load your given configuration files and for each one, disregard
|
|
the configured value for the `compression` option and use the value given on the
|
|
command-line instead—but just for the duration of the borgmatic run.
|
|
|
|
You can override nested configuration options too by separating such option
|
|
names with a period. For instance:
|
|
|
|
```bash
|
|
borgmatic create --bootstrap.store-config-files false
|
|
```
|
|
|
|
You can even set complex option data structures by using inline YAML syntax. For
|
|
example, set the `repositories` option with a YAML list of key/value pairs:
|
|
|
|
```bash
|
|
borgmatic create --repositories "[{path: /mnt/backup, label: local}]"
|
|
```
|
|
|
|
If your override value contains characters like colons or spaces, then you'll
|
|
need to use quotes for it to parse correctly.
|
|
|
|
You can also set individual nested options within existing list elements:
|
|
|
|
```bash
|
|
borgmatic create --repositories[0].path /mnt/backup
|
|
```
|
|
|
|
This updates the `path` option for the first repository in `repositories`.
|
|
Change the `[0]` index as needed to address different list elements. And note
|
|
that this only works for elements already set in configuration; you can't append
|
|
new list elements from the command-line.
|
|
|
|
See the [command-line reference
|
|
documentation](https://torsion.org/borgmatic/reference/command-line/) for
|
|
the full set of available arguments, including examples of each for the complex
|
|
values.
|
|
|
|
There are a handful of configuration options that don't have corresponding
|
|
command-line flags at the global scope, but instead have flags within individual
|
|
borgmatic actions. For instance, the `list_details` option can be overridden by
|
|
the `--list` flag that's only present on particular actions. Similarly with
|
|
`progress` and `--progress`, `statistics` and `--stats`, and `match_archives`
|
|
and `--match-archives`.
|
|
|
|
Also note that if you want to pass a command-line flag itself as a value to one
|
|
of these override flags, that may not work. For instance, specifying
|
|
`--extra-borg-options.create --no-cache-sync` results in an error, because
|
|
`--no-cache-sync` gets interpreted as a borgmatic option (which in this case
|
|
doesn't exist) rather than a Borg option.
|
|
|
|
An alternate to command-line overrides is passing in your values via
|
|
[environment
|
|
variables](https://torsion.org/borgmatic/reference/configuration/environment-variables/).
|
|
|
|
|
|
### Deprecated overrides
|
|
|
|
<span class="minilink minilink-addedin">Prior to version 2.0.0</span>
|
|
Configuration overrides were performed with an `--override` flag. You can still
|
|
use `--override` with borgmatic 2.0.0+, but it's deprecated in favor of the new
|
|
command-line flags described above.
|
|
|
|
Here's an example of `--override`:
|
|
|
|
```bash
|
|
borgmatic create --override remote_path=/usr/local/bin/borg1
|
|
```
|
|
|
|
What this does is load your given configuration files and for each one, disregard
|
|
the configured value for the `remote_path` option and use the value given on the
|
|
command-line instead—but just for the duration of the borgmatic run.
|
|
|
|
You can even override nested values or multiple values at once. For instance:
|
|
|
|
```bash
|
|
borgmatic create --override parent_option.option1=value1 --override parent_option.option2=value2
|
|
```
|
|
|
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Don't
|
|
forget to specify the section that an option is in. That looks like a prefix
|
|
on the option name, e.g. `location.repositories`.
|
|
|
|
Note that each value is parsed as an actual YAML string, so you can set list
|
|
values by using brackets. For instance:
|
|
|
|
```bash
|
|
borgmatic create --override repositories=[test1.borg,test2.borg]
|
|
```
|
|
|
|
Or a single list element:
|
|
|
|
```bash
|
|
borgmatic create --override repositories=[/root/test.borg]
|
|
```
|
|
|
|
Or a single list element that is a key/value pair:
|
|
|
|
```bash
|
|
borgmatic create --override repositories="[{path: test.borg, label: test}]"
|
|
```
|
|
|
|
If your override value contains characters like colons or spaces, then you'll
|
|
need to use quotes for it to parse correctly.
|
|
|
|
Another example:
|
|
|
|
```bash
|
|
borgmatic create --override repositories="['user@server:test.borg']"
|
|
```
|
|
|
|
There is not currently a way to override a single element of a list without
|
|
replacing the whole list.
|
|
|
|
Using the `[ ]` list syntax is required when overriding an option of the list
|
|
type (like `location.repositories`). See the [configuration
|
|
reference](https://torsion.org/borgmatic/reference/configuration/) for
|
|
which options are list types. (YAML list values look like `- this` with an
|
|
indentation and a leading dash.)
|
|
|
|
|