Borg wrapper for basic commands

[jake-47]

Thank you @ThomasWaldmann and team for your labour of love.

I've written a bash wrapper that makes borg simple for running my own backups: one config file saying what to back up and to which USB drives, and a small set of commands over it (init, extract, list, check, pass-change, rename). Each repo is written to every one of its drives, so any single drive restores on its own. It's grown well past what I originally intended, and before I lean on it any further I'd value a look from people who actually know Borg's internals.

I'm not a developer. I used Opus 4.6 through Opus 5 to build it. I've read and tested what I'm running, and every entry point works as intended.

What I'm most worried about is the class of mistake a beginner wouldn't know to worry about: whether I'm handling repo locking correctly, whether my error paths can leave a repo in a bad state, whether I'm depending on any Borg behaviour that isn't guaranteed across versions, whether there's anything malicious in the script, and whether the restore script holds up under real recovery conditions rather than the happy path I tested. Even a short "you're doing X wrong, that's a known footgun" would be wonderful. I can then ask Claude to fix it.

Here's the script: https://jake-47.github.io/docwright/borg-simple.html

Here's what it can accomplish: https://jake-47.github.io/docwright/leveling-up-1.html#why-not-just-type-borg-commands

[ThomasWaldmann]

Hi Jake,

I don't like coding in bash (nor reviewing 3000 lines long bash scripts), so guess somebody else has to look at that.

From my experience, claude (esp. opus and fable) is quite good at coding (including shell scripts), so it might well be that it does what you asked for.

Locking: as long as you don't use break-lock and --bypass-lock, all should be fine. If you use these, you have to be careful what you do and when you do it.

borg 1.x won't see big changes, so guess there won't be a compatibility problem.

borg 2 (still in beta) is rather different though, you likely will need a new script for that.

Cheers, Thomas

[jake-47]

Thank you for the tip Thomas. I don't mean to burden you with reviewing the script. I understand.

But in case anyone's interested, there's also a core, bare-bones version of the script that's 174 lines, and it does two things, backup and extract: https://jake-47.github.io/docwright/borg-simple-core.html

Also here's an Opus 5 summary of the main, longer script for someone who knows borg well:

It's a single-file bash wrapper, not a reimplementation. Everything is shelled out, and the entire borg surface it touches is: --version, init --encryption=repokey, create --json, create --dry-run --list, check --archives-only --last 1, check, prune, compact, list --short, extract, and key change-passphrase. No ssh or remote repos, no mount, no server side, no borg 2.

The model is one repo per dataset, replicated to several USB drives, a full independent repo directory per drive, so any one drive restores on its own. Drives are labels mounting under MOUNT_BASE/<label>. Config is a bash file sourced with directive functions (repo_name, backup_data, backup_drives, keep, exclude, include_only, include_only_in, restore_to, compression, archive). Bare invocation backs up every repo to every one of its drives.

Passphrases live in one file, plaintext or GPG, backend detected from the file's own bytes rather than its name. The long-running process never holds a passphrase value: each borg call gets a BORG_PASSCOMMAND that re-invokes the script itself as a hidden child which decrypts, evals, prints one repo's passphrase and exits. A second hidden child prints only the repo names that have entries, so the parent can decide what to skip without ever seeing a value. Running under bash -x is refused at entry.

The parts that are about borg's behaviour rather than about bash are these:

Every source goes in as <parent>/./<basename> so it lands at the archive root under its own name, but the matcher still sees the leading-slash-stripped absolute path. So a pattern written against the stored name matches nothing, and an allowlist that matches nothing archives the folder whole and exits 0. That silent-in-the-dangerous-direction failure is why the script runs create --dry-run --list before every filtered create and refuses unless the pattern set both drops something and keeps something. It asks borg instead of reasoning about the globs, and the dry run doesn't unlock the key, so the cost is one metadata walk and no hardware token touch.

The version gate is 1.4 or newer and below 2.0. 1.4 for the /./ handling the archive layout depends on, and the 2.0 ceiling because create --json renames deduplicated_size and unique_csize, prune wants an archive glob, and repo::archive changes.

create rc=1 is treated as success, since live dotfiles change mid-run, but it's paired with an nfiles == 0 test on the JSON, because an empty archive is structurally valid and would otherwise verify clean and then trigger a prune. Verification runs before retention, and prune plus compact are skipped entirely if the new archive fails check or comes out empty. compact runs on every backup rather than on a schedule.

Reads against a repo directory the user can't write use --bypass-lock, and it distinguishes unwritable from unreadable first, because bypass-lock does nothing for the second. BORG_SHOW_SYSINFO=no is set on list calls so the last stderr line is the actual error rather than the tail of the environment dump.

When several drives hold a repo and extract has to choose one, the ranking sorts on the first ten characters of the archive name, the date from {now}, descending, with config order as the tiebreak. {now} is evaluated once per create and the drives are walked in config order, so the drive written last in a run always carries the later full name, and sorting the whole name would rank write order instead of currency.

If someone wants to read one function, it's _archive_one_drive: pattern assembly, the dry-run assertion, create, verify, prune, compact, all in one place.

Again, none of this is a review request. Grateful for Borg. Cheers.