Restoring Files with Borg

Reviewed in August 2023

FUSE can be slow for a large number of files and it can’t restore metadata. For this reason, Borg includes a second command for fast bulk-restoring – borg extract.

Note: You should be comfortable using the command line. If you prefer a graphical, client, look into our Vorta Tutorial instead. These instructions should work on macOS and popular Linux flavors, like Debian, Ubuntu, as well as Red Hat, Fedora and CentOS.

Borg is currently transitioning to the more standards-conform ssh:// URL format. You may still see the older, deprecated SCP-style format (xxx@xxx.repo.borgbase.com:repo) in some places. The BorgBase control panel will give you the new format by default.

Prerequisites

You should already have Borg installed and know how to use the command line. If you didn’t install Borg yet, have a look at this previous guide.

Step 1 - Listing the Archives

To use it, you will need to know the precise path and archive name to restore. The borg list command can be helpful for this.

Assuming we got the archive name and path from the previous step, a possible borg extract command could be

$ borg extract \
    --dry-run --list \
    ssh://w66xh7lj@w66xh7lj.repo.borgbase.com/./repo::nyx2-test-repo-2019-02-16T12:04:06 \
    /Users/manu/Documents/financial

Due to the --dry-run and --list arguments this will print a list of files to be restored, but won’t actually restore any files. To actually restore files, remove --dry-run.

The last part of the command gives the path you’re looking to restore. If you pass no paths, then all the data will be restored. If you would like to extract a particular directory without its full path, you would add --strip-components n, with n being the number of directories you would like to be stripped.

Step 2 - Extracting the Archives

Borg will restore your files to the current working directory. So be sure you are in the right place before running the command for real. To restore all the data from a specific snapshot to the current directory:

$ borg extract \
    --list \
    ssh://w66xh7lj@w66xh7lj.repo.borgbase.com/./repo::nyx2-test-repo-2019-02-16T12:04:06

For more information on extracting, check out the official Borg documentation.