Borg / Borgmatic command builder

Restore — the part everyone forgets

Extract vs Mount

Extract pulls files back to disk — fastest when you know the exact path. Mount exposes the archive (or the whole repo) as a browsable folder via FUSE, so you can hunt for what you need in a file manager, copy it out, then borg umount.

The extract gotcha

borg extract has no output-directory flag — it always writes into your current directory. This builder generates the mkdir -p … && cd … line so you don't dump a restore over your live files. (Borgmatic mode avoids this with --destination.)

Leading slash

Paths inside an archive are stored relative — home/joe/file, not /home/joe/file. The builder strips the leading slash for you.

Prune & compact

borg prune applies your --keep-* rules and removes old archives — but it only deletes references. Space is reclaimed only when you run borg compact afterwards. Always dry-run prune first, and use --glob-archives to scope it when several machines share one repo (otherwise prune compares unrelated archives).

Encryption & the passphrase

repokey stores the (encrypted) key inside the repo — the safe default for most people. keyfile keeps the key on the client only, so you must back it up offsite. Either way: a lost passphrase means permanently lost data — Borg has no recovery path. For cron, supply it via BORG_PASSCOMMAND (pulled from a secret store) rather than a plaintext BORG_PASSPHRASE.

Remote repositories (SSH)

A Borg repo can live on another server reached over SSH — the same commands work, you just point them at an ssh://user@host:port/path URL instead of a local path (a path without a leading slash is taken relative to the SSH login's home, written /./path). The remote server needs borg installed too. For unattended/cron runs, set BORG_RSH to choose the SSH key (e.g. ssh -i /root/.ssh/borg_key) and supply the passphrase via BORG_PASSCOMMAND — both under "Remote & unattended" above. Tip: an append-only SSH key on the server lets a client add backups but not delete them (ransomware protection); pruning then has to be done later with a full-access key.

Version note

These commands target Borg 1.2 / 1.4 (current stable in 2026), which uses the repo::archive syntax. Borg 2.0 is still beta and changes that to -r REPO … archive — don't mix the two.