How to Use Git Bundle for Offline Repository Sharing

Use git bundle create to package a repository or part of it into a single file. Then share this file and use git clone or git fetch with the bundle file to restore or update a repository without network access.

Syntax

The git bundle command has two main forms: creating and using bundles.

• git bundle create <file> <refs>: Creates a bundle file containing commits and objects from the specified refs (branches or tags).
• git clone <file> <directory>: Clones a repository from a bundle file.
• git fetch <file> <refs>: Fetches updates from a bundle into an existing repository.

bash

git bundle create <file> <refs>
git clone <file> <directory>
git fetch <file> <refs>

Example

This example shows how to create a bundle from the main branch, share it, and clone from it on another machine without internet.

bash

git bundle create repo.bundle main
# Share repo.bundle file via USB or email

# On another machine:
git clone repo.bundle myrepo
cd myrepo
git log --oneline

Output

e3a1b2c Initial commit
f4d5e6f Added README
9a8b7c6 Updated main branch

Common Pitfalls

Common mistakes include:

• Not specifying the correct refs when creating the bundle, resulting in missing commits.
• Trying to clone from a bundle without the required refs included.
• Using git fetch without specifying refs, which can cause errors.

Always verify the refs included with git bundle list-heads <file> before sharing.

bash

git bundle create repo.bundle
# Wrong: no refs specified, bundle is empty

# Right:
git bundle create repo.bundle main

Quick Reference

Command	Description
git bundle create	Create a bundle file with specified refs
git bundle list-heads	List refs inside a bundle file
git clone	Clone a repo from a bundle file
git fetch	Fetch updates from a bundle into a repo

Key Takeaways

Use git bundle to package and share repositories offline as a single file.

Always specify the correct refs when creating a bundle to include needed commits.

Use git clone or git fetch with the bundle file to restore or update repositories.

Check bundle contents with git bundle list-heads before sharing.

Bundles are useful for backups, offline transfers, or restricted network environments.