bup-split(1)

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

✨ bup-split(1) ✨

okay bestie, this is bup-split(1) from the General Commands Manual section — the one you pull up when you're like "I have files and I want them living in a bup backup set, chunk by chunk, no cap." 💅 Let's get into it.

🌸 NAME 🌸

bup-split — save individual files to bup backup sets

🦋 SYNOPSIS 🦋

bup split [-t] [-c] [-n name] COMMON_OPTIONS

bup split -b COMMON_OPTIONS

bup split –copy COMMON_OPTIONS

bup split –noop [-t|-b] COMMON_OPTIONS

COMMON_OPTIONS
       [-r host:path] [-v] [-q] [-d seconds-since-epoch] [--bench]
       [--max-pack-size=bytes] [-#] [--bwlimit=bytes]
       [--max-pack-objects=n] [--fanout=count] [--keep-boundaries]
       [--git-ids | filenames...]

💖 DESCRIPTION 💖

So here's the whole vibe: bup split takes the contents of all the files you hand it (or, if you don't give it any filenames at all, it just reads from stdin), splits that content into chunks of around 8k using a rolling checksum algorithm, and saves those chunks into a bup repository. And here's the iconic part — chunks that were already stored before do not get stored again. It's giving deduplicated. Periodt. 🎀

And the way the rolling checksum works? It makes chunks super stable across changes to a given file — like, adding bytes, deleting bytes, changing bytes, all of it. The chunks lowkey hang on through the drama. 🦋

For example: say you use bup split to back up an XML dump of a database, and that XML file changes just a lil bit from one run to the next. Nearly all of the data will still be deduplicated, and the size of each backup after the first one will typically be quite small. Obsessed. ✨

Another technique (iykyk): pipe the output of the tar(1) or cpio(1) programs into bup split. When individual files inside the tarball change slightly, or get added, or get removed, bup still processes the rest of the tarball efficiently. (Just a heads up though — bup save is usually a more efficient way to accomplish this.)

And when you want your data back? That's bup-join(1), bestie. 🫶

👑 MODES 👑

These options pick the main character behavior of the command, and -n is the most likely choice you'll be making.

  • -n, --name=name — after creating the dataset, it creates a git branch named name so you can access it by that name. And if name already exists? The new dataset is treated as a descendant of the old one. (So yes, you can keep creating new datasets with the same name over and over, then later look at the history of that dataset to see how it changed over time. Growth arc. 🌱) The original data also stays available as a top-level file named data in the VFS, reachable via bup fuse, bup ftp, etc.
  • -t, --tree — outputs the git tree id of the resulting dataset.
  • -c, --commit — outputs the git commit id of the resulting dataset.
  • -b, --blobs — outputs a series of git blob ids that correspond to the chunks in the dataset. Incompatible with -n, -t, and -c.
  • --noop — reads the data and splits it into blocks based on the bupsplit rolling checksum algorithm, but doesn't store anything in the repo. Can be combined with -b or -t to compute (but not store) the git blobs or tree ids for the dataset. Mostly useful for benchmarking and validating the bupsplit algorithm. Incompatible with -n and -c.
  • --copy — like --noop, but it also writes the data to stdout. Handy if you're benchmarking the speed of read+bupsplit+write on large amounts of data. Incompatible with -n, -t, -c, and -b.

🌈 OPTIONS 🌈

  • -r, --remote=[user@]host:[path], --remote=URL — splits the data to the specified remote repository, by default over SSH. See bup(1) REMOTE OPTIONS for more. 💌
  • -d, --date=seconds-since-epoch — specify the date inscribed in the commit (seconds since 1970-01-01). Time travel but make it epoch. ⏰
  • -q, --quiet — disable progress messages. Shhh. 🤫
  • -v, --verbose — increase verbosity (you can use it more than once, go off).
  • --git-ids — stdin is a list of git object ids instead of raw data. bup split will read the contents of each named git object (if it exists in the bup repository) and split it. This might be useful for converting a git repository with large binary files over to use bup-style hashsplitting instead. Probably most useful when combined with --keep-boundaries. 🔥
  • --keep-boundaries — so, if you give multiple filenames on the command line, they're normally concatenated together as if the content all came from a single file. Meaning: the set of blobs/trees produced is identical to what it would have been if there'd been a single input file. But if you use --keep-boundaries, each file gets split separately. You still only get a single tree or commit or series of blobs — but each blob comes from only one of the files, and the end of one of the input files always ends a blob. 🎯
  • --bench — prints benchmark timings to stderr.
  • --max-pack-size=bytes — never create git packfiles larger than the given number of bytes. Default is 1 billion bytes. Usually there is no reason to change this.
  • --max-pack-objects=numobjs — never create git packfiles with more than the given number of objects. Default is 200 thousand objects. Usually there is no reason to change this.
  • --fanout=numobjs — when splitting very large files, tries to keep the number of elements in trees to an average of numobjs.
  • --bwlimit=bytes/sec — don't transmit more than bytes/sec bytes per second to the server. This is the one that keeps your backups from sucking up all your network bandwidth. 🫶 Use a suffix like k, M, or G to specify multiples of 1024, 1024*1024, 1024*1024*1024 respectively.
  • -#, --compress=# — set the compression level to # (a value from 0-9, where 9 is the highest and 0 is no compression). Defaults to a configured pack.compression or core.compression, or 1 (fast, loose compression).

🎀 EXAMPLES 🎀

$ tar -cf - /etc | bup split -r myserver: -n mybackup-tar
tar: Removing leading /' from member names
Indexing objects: 100% (196/196), done.

$ bup join -r myserver: mybackup-tar | tar -tf - | wc -l
1961

🧚 SEE ALSO 🧚

bup-join(1), bup-index(1), bup-save(1), bup-on(1), ssh_config(5)

💜 BUP 💜

Part of the bup(1) suite.

🍓 AUTHORS 🍓

Avery Pennarun apenwarr@gmail.com

and that's the whole page bestie, you ate 💅✨ this was Bup 0.34, dated 2026-09-01 — bup-split(1), signing off 🫶🌸

📦 where this page comes from