A teammate without access to the same server still needs a repository's history. A bundle packages Git objects and references into a file that can be copied through an ordinary file-transfer channel. It is useful for offline handoffs and recovery drills, but it is not an image of every file in a working directory. The important questions are which references you included, whether prerequisites exist at the destination and what external data is missing. This guide creates and restores a small complete bundle before contrasting it with an incremental one.
Choose which history the bundle contains
git bundle create accepts revision arguments much like history-selection commands. A reference such as main includes the objects reachable from that reference. --all includes the repository's available references, which is useful when you intend to transfer the referenced history broadly. It does not mean every unreachable object, reflog entry, working-tree edit or machine-specific configuration has become part of the artifact. Inspect the repository and state the selection you made in the recovery instructions.
A bundle records named heads that recipients can inspect with git bundle list-heads. Those names identify starting points for importing history; they are not a snapshot of your editor session or local credentials. Save uncommitted work through an appropriate separate process before assuming it is protected. If the repository depends on generated files, databases, secrets or server settings, inventory them separately. A precise backup description is more useful than a label saying full backup without defining what full includes.
Verify prerequisites and restore behavior
git bundle verify checks the bundle format and prerequisite availability relative to the current repository. A complete bundle of the selected reachable history can be used to create a new clone. An incremental bundle can intentionally exclude history already present at the recipient, and then cannot stand alone. Verification should run where the intended base objects exist. Reading a bundle file successfully is not enough to establish that the destination can resolve all required history.
After verification, perform the operation you intend to support. For recovery, clone into a new directory, inspect the expected branch and commit, and run a representative project check. For an incremental handoff, fetch the new tip into the existing repository and compare it with the documented base. Keep object identifiers in a small handoff record so the receiver knows what success looks like. A restore drill turns an assumption about backup completeness into evidence about an actual repository state.
Use incremental bundles with a known base
A range such as main~1..main can produce a compact package for the newest commit while excluding the parent history. The excluded parent becomes a prerequisite. That is useful when the recipient already has the previous bundle and you want to avoid transferring all historical objects again. Choose a stable base identifier rather than relying on a branch name whose meaning may move before the recipient reads the instructions. Preserve the earlier artifact as part of the dependency chain.
Incremental backup chains introduce management work. If an old base artifact is missing or corrupt, later bundles may not restore independently. Periodic complete bundles can simplify recovery, but the schedule should follow the repository's needs and tested restore procedure. Avoid describing incremental bundles as self-contained merely because their files have all been copied. List the prerequisite objects, verify them at the destination and retain the metadata needed to reconstruct the chain in the correct order.
Account for data outside ordinary Git objects
Git LFS stores pointers in ordinary Git history while asset content lives in a separate object store. A bundle can contain those pointer blobs without containing the complete assets they reference. Submodule entries similarly identify commits in other repositories rather than packaging the whole submodule repository automatically. Recover those stores and repositories through their own verified transfer process. A restored checkout that contains a pointer or an unavailable submodule is evidence of incomplete project recovery.
Treat the bundle file as an artifact that must itself be stored and transported reliably. Use a checksum from a trusted channel to detect accidental changes, and use the relevant authentication or signing process when the sender's identity matters. Bundle verification checks Git structure and prerequisites; it is not an independent endorsement of the sender. Keep recovery files outside the repository you are backing up to avoid creating confusing self-references or accidentally committing large archives.
Sources and prerequisites
Start with remotes, history and tags. Read the official bundle reference for revision selection, prerequisite handling and supported import operations.
Git Bundle Files for Offline Transfer and Recovery Summary
- A bundle transfers selected Git history, not all local machine state.
- Incremental bundles require documented base objects.
- Verify prerequisites and rehearse a restore, including external project data.
Git Bundle Files for Offline Transfer and Recovery Examples
Each example shows the code, the output it produces and what each part does.
Create a complete bundle and restore it locally
Run this Bash sequence in a fresh directory. The bundle lives outside the source repository, and the restored clone uses only the local file. The final lines show the expected branch and tracked content after the restore.
Bundle creation and verification print progress and reference information before the final lines. The clone restores the selected Git history, not source's local configuration or untracked files. Inspecting actual content demonstrates more than simply checking that complete.bundle exists.
mkdir bundle-lab
cd bundle-lab
git init -b main source
git -C source config user.name Learner
git -C source config user.email learner@example.test
printf 'version one\n' > source/notes.txt
git -C source add notes.txt
git -C source commit -m 'Initial notes'
git -C source bundle create ../complete.bundle --all
git -C source bundle verify ../complete.bundle
git clone complete.bundle restored
git -C restored branch --show-current
cat restored/notes.txtmain
version oneGit Bundle Files for Offline Transfer and Recovery in Real Projects
Restore new commits from an incremental bundle
Continue in bundle-lab. Make one new commit, create an incremental bundle and verify it against restored, which already contains the prerequisite. Fetch the new main into a separate remote-tracking reference, then fast-forward the local branch.
printf 'version two\n' > source/notes.txt
git -C source add notes.txt
git -C source commit -m 'Update notes'
git -C source bundle create ../incremental.bundle main~1..main
git -C restored bundle verify ../incremental.bundle
git -C restored fetch ../incremental.bundle main:refs/remotes/offline/main
git -C restored merge --ff-only refs/remotes/offline/main
cat restored/notes.txt
git -C restored log -1 --format='%s'version two
Update notesThe receiver can verify and import this incremental bundle because it already has the initial commit. Try verification from a new empty disposable repository to see the missing prerequisite reported, but keep that experiment separate from the restored repository. The documented base determines whether the same file is usable at another destination.
Git Bundle Files for Offline Transfer and Recovery FAQ
Does git bundle create --all include my uncommitted edits?
No. The selection concerns Git references and reachable objects, not an image of the current working directory. Stage and commit appropriate work or save it through a separate process before creating a recovery artifact. Also inventory untracked files and machine-specific configuration. A repository with the correct branch history can still lack important local work if the backup plan never captured that work in the first place.
Why does an incremental bundle fail in an empty repository?
It deliberately excludes history that the recipient is expected to possess already. The bundle advertises prerequisite commits, and an empty repository does not have them. Restore the complete base or earlier chain first, then verify and import the increment. Avoid attempting to fix the problem by ignoring verification output: the missing objects are a real dependency of the transferred history, not merely an optional warning.
Can a bundle recover all my Git LFS files?
A normal bundle contains the Git objects selected by its revision arguments. For LFS-managed files, those objects include pointers, while the full asset bytes live in LFS storage. Preserve and verify the required LFS objects separately. During a restore drill, check that the assets can actually be materialized rather than stopping after branch recovery. The same general inventory principle applies to submodule repositories and other external project data.
How should I confirm that a bundle is a useful backup?
Verify its structure and prerequisites, then restore into a separate directory and inspect the expected references, commit identifiers and tracked content. Run a representative build or test if project dependencies are available. Document any external assets and configuration needed to finish recovery. Repeat the drill when the backup procedure changes; an existing artifact file alone does not establish that your current recovery instructions are complete.
Git Bundle Files for Offline Transfer and Recovery Exercises
Answer each one and check it instantly. If you get stuck, open the hint before the answer.
Why can restored import the incremental.bundle in the worked task?
Git Bundle Files for Offline Transfer and Recovery Quiz
2 questions to check what you learned.
Which information should a reliable offline handoff record include?
- Selected references, expected identifiers and prerequisite history
- Only the bundle filename
- Only the developer's editor theme
What does a successful Git bundle restore still leave you checking separately?
- Whether Git has any commits at all
- External assets such as LFS content and submodule repositories
- Whether the bundle can contain named references