How to run arbitrary Borg commands

Running Borg with borgmatic

Borg has several commands and options that borgmatic does not currently support. Sometimes though, as a borgmatic user, you may find yourself wanting to take advantage of these off-the-beaten-path Borg features. You could of course drop down to running Borg directly. But then you'd give up all the niceties of your borgmatic configuration. You could file a borgmatic ticket or even a pull request to add the feature. But what if you need it now?

That's where borgmatic's support for running "arbitrary" Borg commands comes in. Running these Borg commands with borgmatic can take advantage of the following, all based on your borgmatic configuration files or command-line arguments:

borg action

New in version 1.5.15 The way you run Borg with borgmatic is via the borg action. Here's a simple example:

borgmatic borg break-lock

This runs Borg's break-lock command once with each configured borgmatic repository, passing the repository path in as a Borg-supported environment variable named BORG_REPO. (The native borgmatic break-lock action should be preferred though for most uses.)

You can also specify Borg options for relevant commands. For instance:

borgmatic borg rlist --short

This runs Borg's rlist command once on each configured borgmatic repository.

What if you only want to run Borg on a single configured borgmatic repository when you've got several configured? Not a problem. The --repository argument lets you specify the repository to use, either by its path or its label:

borgmatic borg --repository repo.borg break-lock

And if you need to specify where the repository goes in the command because there are positional arguments after it:

borgmatic borg debug dump-manifest :: root

The :: is a Borg placeholder that means: Substitute the repository passed in by environment variable here.

Prior to version 1.8.0borgmatic attempted to inject the repository name directly into your Borg arguments in the right place (which didn't always work). So your command-line in these older versions didn't support the ::

Specifying an archive

For borg commands that expect an archive name, you have a few approaches. Here's one:

borgmatic borg --archive latest list '::$ARCHIVE'

The single quotes are necessary in order to pass in a literal $ARCHIVE string instead of trying to resolve it from borgmatic's shell where it's not yet set.

Or if you don't need borgmatic to resolve an archive name like latest, you can just do:

borgmatic borg list ::your-actual-archive-name

Prior to version 1.8.0borgmatic provided the archive name implicitly along with the repository, attempting to inject it into your Borg arguments in the right place (which didn't always work). So your command-line in these older versions of borgmatic looked more like:

borgmatic borg --archive latest list

With Borg version 2.x Either of these will list an archive:

borgmatic borg --archive latest list '$ARCHIVE'
borgmatic borg list your-actual-archive-name


borgmatic's borg action is not without limitations:

In general, this borgmatic borg feature should be considered an escape valveβ€”a feature of second resort. In the long run, it's preferable to wrap Borg commands with borgmatic actions that can support them fully.

Improve this documentation

Have an idea on how to make this documentation even better? Use our issue tracker to send your feedback!