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.
Using this in CI
CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.
- uses: actions/checkout@v4
with:
fetch-depth: 0 # history, tags, and git describe all need this
- run: |
git rev-parse --is-shallow-repository # expect false
git rev-parse --abbrev-ref HEAD # prints HEAD when detached