bup(1)

📦
version 0.34 · 10 versions
, in fedora 44, nixpkgs unstable

💖 bup(1) — the main character of backup tools 💖

okay bestie, so you wanna know about bup?? sit down, hydrate, because this one's lowkey iconic. this is the manual for bup(1) — the General Commands Manual page, no less. and before you ask: yes, we're doing this entire thing. every flag. every command. no skipping. periodt. ✨

🌸 NAME 🌸

bup — the backup program that runs on rolling checksums and git file formats. that's it, that's the whole vibe check. 🎀

🦋 SYNOPSIS 🦋

bup [global options...]  <command> [options...]

👑 DESCRIPTION 👑

okay so <pink>bup</pink> is a program for making backups of your files using the git file format. fr fr. it's giving "what if git but for your whole life."

but here's the thing that makes it not just git(1) itself: bup is optimized for handling huge data sets, including individual very large files — think virtual machine images. yes bestie, the big big files. 🫶

and the best part?? once a backup set is created, you can still access it using git tools. slay. 💅

subcommands each get their own separate man page btw — like, bup-init(1) covers bup init. we love a franchise. 🌈

✨ GLOBAL OPTIONS ✨

these ones work no matter what command you're running. main character energy.

  • --version — prints bup's version number. exactly equivalent to running bup version. simple, clean, no notes.
  • -d, --bup-dir=BUP_DIR — tells bup to use the given BUP_DIR parameter as the bup repository location. and not to read it from the $BUP_DIR environment variable. and not to fall back on the default ~/.bup location either. like, you're overruling the whole chain here. 💀

🔥 PRIMARY COMMANDS 🔥

the core four-ish. the ones you'll actually be living in.

  • bup-init(1) — Initialize a bup repository. the "hello world" of not losing your stuff.
  • bup-index(1) — Create or display the index of files to back up.
  • bup-save(1) — Save files into a backup set. 📢 note: run bup index first. we said what we said.
  • bup-restore(1) — Extract files from a backup set. this is the "okay phew" command.
  • bup-fsck(1) — Check backup sets for damage and add recovery information. multitasking icon.
  • bup-on(1) — Index/save/split/get/... on a remote machine. look at all those slashes, so versatile.
  • bup-help(1) — Print detailed help for the given command. when in doubt, bestie. 🎀

🧚 INSPECTION COMMANDS 🧚

for looking respectfully. 👀

  • bup-ls(1) — Browse the files in your backup sets.
  • bup-fuse(1) — Mount your backup sets as a filesystem. literally making your backups a whole vibe you can walk around in.
  • bup-web(1) — Launch a web server to examine backup sets.
  • bup-ftp(1) — Browse backup sets using an ftp-like client.

💅 MANIPULATION COMMANDS 💅

shaping, trimming, moving. the makeover montage. ✨

  • bup-gc(1) — Remove unreferenced, unneeded data. cleanup szn.
  • bup-get(1) — Transfer/transform items between/within repositories.
  • bup-prune-older(1) — Remove older saves. letting go is self care.
  • bup-rm(1) — Remove references to archive content.

🍓 IMPORT COMMANDS 🍓

coming from somewhere else? we got you. bringing your ex's backups to the group chat.

🌟 OTHER COMMANDS 🌟

the misc drawer, but make it chic.

🔮 ESOTERIC COMMANDS 🔮

no because WHY are these so real. iykyk.

  • bup-bloom(1) — Generates, regenerates, updates bloom filters.
  • bup-damage(1) — Deliberately destroy data. 💀 yes bestie, this one is exactly what it sounds like. tread carefully, this is not a drill.
  • bup-margin(1) — Determine how close your bup repository is to armageddon. ARMAGEDDON. that's the actual word in the manual. screaming.
  • bup-memtest(1) — Test bup memory usage statistics.
  • bup-meta(1) — Create or extract a metadata archive.
  • bup-midx(1) — Index objects to speed up future backups.
  • bup-random(1) — Generate a stream of random output.
  • bup-tick(1) — Wait for up to one second. that's the whole job. iconic honestly. ⭐

🌐 REMOTE OPTIONS 🌐

some options — currently just --remote — let you specify a remote path. you can write it either as a URL (peep REPOSITORY URLS below 👇) or as a [*user*@]*host*:[*path*].

for either format, when there's no path given, the default path on the server gets used — that's BUP_DIR if it's set in the remote environment, otherwise ~/.bup — and SSH settings for the connection can come from a custom host in your ~/.ssh/config file (see ssh_config(5)).

the argument counts as a URL if it starts with a syntactically valid URL scheme prefix that contains an "authority" — meaning it begins with SCHEME:// the way ssh://... does — and that scheme has to be either ssh or bup. anything else gets rejected. no exceptions, bestie. 🚫

now for the [*user*@]*host*:[*path*] syntax: if there's an @ symbol, then everything before the rightmost @ counts as the user. so -r x@y@z means user x@y and host z. and the host must always be followed by a colon, and anything after the first colon is the path. yes, rightmost for the user but first for the path. it's giving unhinged but it's the rules. 🙈

for fully general purposes, prefer URLs to [*user*@]*host*:[*path*], so there's no potential ambiguity. like, consider the (unlikely) case where ssh://x/y gets generated for a host named ssh and path //x/y — that would be interpreted as a URL with host x and path /y. messy. avoid. 💜

🌈 REPOSITORY URLS 🌈

bup supports these URL schemes (i.e. scheme:) for pointing at a repository. quick note before we dive in: the term "authority" below just means the URL section after the scheme:// and before the path — for example, the user@host:port part of an SSH URL.

as an exception to the standard, a scheme may be "path-oriented", which means there's no separate query or fragment. anything after the (optional) authority is taken as the "path", and the constituent bytes are not decoded (so no percent decoding). this lets URLs given on the command line work naturally. so ssh://host/x?z has a path of /x?z. yes, the ?z is part of the path. it's fine. breathe.

and since URLs with an authority can't represent relative paths, path-oriented schemes interpret a leading /./ as a relative path. so ssh://host/./x, file:///./x, and file:/./x all indicate the path x. 🌸

  • ssh: — a path-oriented scheme (see above) that specifies access to a repository via a bup-server(1) launched on a host via SSH. its syntax and semantics match a typical ssh: URL, including support for a user and port (e.g. ssh://user@host:2222/some/repo), and the user and host can be percent encoded.
  • bup: — a path-oriented scheme (see above) specifying a direct network connection to an existing bup-server(1). otherwise identical to ssh:, except that it does not support a user. this connection has no authentication or encryption of its own, so it's unlikely you'll want to use it — prefer file: or :ssh:.
⚠️ bestie, listen: no auth, no encryption. that's a hard pass for most situations. we're just telling you what the manual says. 💀
  • file: — a path-oriented scheme (see above) that specifies a repository's filesystem path. its syntax and semantics match a typical file: URL, except that it only allows an empty authority (i.e. no user, no host, none of that).

in most cases you'll probably want to include the empty authority so you don't have to think too hard about the contents of the path. i.e. use file://PATH or ssh://user@hostPATH when the PATH begins with a slash, and file:///./PATH or ssh://user@host/./PATH when it doesn't.

it is possible to omit the authority, but only if the path does not begin with two slashes. for example, file:/ and file:some/where are fine, but file://some/where is not — because some will get read as the authority. watch out for that one. 🙈

🎀 ENVIRONMENT 🎀

  • BUP_ASSUME_GIT_VERSION_IS_FINE — if set to true, yes, or 1, assume the version of git in the path is acceptable. consenting to chaos, but make it explicit. ✨

🔗 SEE ALSO 🔗

the README file from the bup distribution, git(1), and http://bup.github.io

💖 AUTHORS 💖

Avery Pennarun apenwarr@gmail.com

okay that's the whole page, bestie, you ate that. 💅 no cap, you now know bup better than half the people running it.

and a lil sign-off for the record: Bup 0.34, dated 2026-09-01. that's the version, that's the date, we're closing the group chat. 🦋✨💖

📦 where this page comes from