git bundle

Sneakernet your repo across an air gap.

🎯 What & why

Pack history into a single file you can transport offline. Bundles are valid Git remotes — you can clone, fetch, and pull from them.

🧠 Mental model

A bundle is a packfile with a small header listing the refs and their tip SHAs. git fetch <bundle.file> treats it identically to a network fetch — same negotiation logic, same object resolution.

🛠️ Synopsis

git bundle create [-q | --quiet | --progress]
                  [--version=<version>] <file> <git-rev-list-args>
git bundle verify [-q | --quiet] <file>
git bundle list-heads <file> [<refname>...]
git bundle unbundle [--progress] <file> [<refname>...]

🎚️ Switches & options

Flag	What it does
`create <file> <revspecs>`	Make a bundle of the specified commits/refs.
`verify <file>`	Sanity-check a bundle.
`list-heads <file>`	List refs in a bundle.

📦 Subcommands

create <file> <git-rev-list-args> — Pack the specified history into <file>.

$ git bundle create proj.bundle --all

verify <file> — Sanity-check a bundle: list its refs and required prerequisites.

$ git bundle verify proj.bundle

list-heads <file> [<refname>...] — List the refs included in a bundle.

$ git bundle list-heads proj.bundle

unbundle <file> [<refname>...] — Unpack the bundle into the current repo's object DB.

$ git bundle unbundle proj.bundle

💡 Use cases

Sneakernet history across an air gap.
Sharing a feature branch with someone who can't reach the remote.
Backing up a slice of history to cold storage.

🧪 Examples

Bundle the entire repo.

$ git bundle create proj.bundle --all

Bundle a slice (commits since v1.2).

$ git bundle create incr.bundle v1.2..main

Use a bundle as a remote.

$ git clone proj.bundle proj/

🎓 Recommendations

For incremental backups, bundle since the last known-good ref. For full, use --all.
verify before relying on a bundle — corrupted ones are unhelpful.

🪤 Common pitfalls

Bundle files include only what's specified. --all picks up every ref including stash; trim if not wanted.
Restoring from a bundle requires the prerequisite commits if you bundled a slice.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.