- Developers who already know basic commit and branch actions
- Readers who want to understand command boundaries and risk
Command Reference
git-bundle Tutorial
Package Git history into a single transferable file for offline or restricted-network exchange when direct fetch/push is unavailable.
- A basic mental model of worktree, index, and commits
- Comfort reading `git status` and a small commit graph
- Using local cleanup commands on already shared history
- Continuing to rewrite before confirming a recovery path
The short version
git bundle creates a transportable file that can act as a history source for clone or fetch.
Best-fit scenarios
- air-gapped or restricted network environments
- one-time branch/history handoff
- archival snapshot delivery
Typical commands
git bundle create repo.bundle main feature/hotfix
git bundle verify repo.bundle
git clone repo.bundle repo-from-bundle
Common workflow
- sender creates and verifies bundle
- bundle is transferred via file channel
- receiver clones or fetches from bundle
Key boundaries
- bundle content is only what selected refs include
- receiver may fail if prerequisite objects are missing for incremental bundles
git bundle verify catches missing prerequisites early, before expensive multi-step transfer loops.
Common mistakes
Mistake 1: defaulting to --all unnecessarily
Over-bundling increases file size and may leak unrelated refs.
Mistake 2: distributing without validation
Receiver-side failures are costlier to debug later.
Mistake 3: using bundle as continuous sync replacement
git bundle packages repository history into a single file that can be transferred offline. Unlike git archive, it includes the full Git history and objects, making it suitable for scenarios where the recipient needs a complete repository but cannot access the network.
Bundle is better for batch snapshots than high-frequency bidirectional collaboration.
Good follow-up reads
git-fetchgit-request-pullcross repository integration workflow
- Transfer repository history across an air-gapped network by creating a bundle file on one machine and fetching from it on another.
- Create a backup of repository history as a single portable file that can be restored with
git cloneorgit fetch. - Share a subset of history (e.g., specific branches or a commit range) without setting up a remote server.
Diagram view
Refs to include (branches, tags)Commit range (optional)
Single .bundle fileComplete Git history and objects
The receiving side still needs to know which refs and prerequisite objects are required to use the bundle.
Special cases and boundaries
- Bundles work well for offline history transfer, but the receiving side still needs to know which refs and prerequisite objects are required.
- Use
git bundle verify <file>to check whether a bundle is complete and can be applied to the current repository. - A bundle created with
--allincludes all refs, but you can limit the scope to specific branches or commit ranges for smaller files. - The receiving repository must already contain any prerequisite commits referenced by the bundle; otherwise, you need to transfer those first.