Borgmatic Configuration: Update Occasionally

PSA: If you regularly update borgmatic (e.g., because the Docker image is set to auto-update), you should also occasionally update the configuration file to keep it up to date. From time to time, the config file learns new options or old ones are deprecated.

Borgmatic provides the command borgmatic config generate for this purpose.

his process is described in the documentation under the section “Upgrading your configuration“. Here’s how I approach it:

borgmatic config generate -s config.yaml -d config-new.yaml

# At this point, review the changes.
# Local adjustments need to be re-enabled.

# Validate the configuration:
borgmatic config validate -c config-new.yaml

# Activate the new config and
# back up the old config just in case (important: it must not end with ".yaml"):
mv config.yaml config.yaml_old
mv config-new.yaml config.yaml

# Test the backup:
borgmatic -c config.yaml create -v1

Since Borgmatic comments out local customizations, it’s a good idea to compare the old and new configurations side by side in a merge tool.

After the successful backup (don’t forget to check the logs to catch any warnings), you can safely delete the old config file.