# git bundle: Usage, Options & Common CI Errors

> git bundle packs refs and objects into one file for offline transport. Reference for create, verify, clone, and the missing-prerequisite ref error.

Source: https://latchkey.dev/learn/command-reference/git-bundle  
Updated: 2026-06-25

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

```Terminal
git bundle create repo.bundle --all
git bundle create recent.bundle main~10..main
git bundle verify repo.bundle
git clone repo.bundle restored-repo
```

## Options

| 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.

```.github/workflows/ci.yml
- 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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git bundle: Usage, Options & Common CI Errors?

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 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt