git bundle: Usage, Options & Common CI Errors
git bundle packs commits and refs into a single file you can move offline.
Bundles let you transfer history through air-gapped systems, caches, or artifact stores where a normal git remote is unavailable. The file behaves like a remote you can clone or fetch from.
What it does
git bundle writes the objects and refs reachable from a given range into one binary file. That file can later be verified, cloned, or fetched from as if it were a remote repository.
Common usage
git bundle create repo.bundle --all
git bundle create recent.bundle main~10..main
git bundle verify repo.bundle
git clone repo.bundle restored-repoOptions
| Subcommand | What it does |
|---|---|
| create <file> <refs> | Write a bundle for the given refs/range |
| verify <file> | Check the bundle is valid and applicable |
| list-heads <file> | List the refs the bundle contains |
| --all | Bundle every ref |
Common errors in CI
error: Repository lacks these prerequisite commits - the bundle was created as an incremental range whose base is missing in the target repo. Create a full bundle (--all) for a clean target, or ensure the prerequisite commits exist before fetching. "fatal: <file> does not look like a v2 or v3 bundle file" means a corrupt or truncated artifact.