git-bundle
Package Git repository for transport
TLDR
Create a bundle file that contains all objects and references of a specific branch
Create a bundle file of all branches
Create a bundle file of the last 5 commits of the current branch
Create a bundle file of the latest 7 days
Verify that a bundle file is valid and can be applied to the current repository
Print to stdout the list of references contained in a bundle
Unbundle a specific branch from a bundle file into the current repository
Create a new repository from a bundle
SYNOPSIS
git bundle create <file> [<git-bundle-option>...] [<git-rev-list-option>...]
git bundle verify <file>
git bundle list-heads <file>
PARAMETERS
<file>
The path to the bundle file to be created, verified, or listed.
--all
Includes all heads (branches and tags) in the bundle, except those that would be excluded by specific options.
--branches[=<pattern>]
Includes all branches, or only branches matching the optional glob pattern, in the bundle.
--tags
Includes all tags in the bundle.
--mirror
Includes all refs (including remote-tracking branches, notes, etc.) and their current states, mimicking a mirror clone.
--stdin
Reads a list of revision arguments from standard input to specify what to bundle.
^<commit>
Excludes commits reachable from <commit> from the bundle. Essential for creating incremental bundles.
<commit>
Includes commits reachable from <commit> in the bundle. Can specify multiple commits or ranges.
--progress
Shows progress during bundle creation.
--quiet
Suppresses progress output during bundle creation.
DESCRIPTION
The git-bundle command creates a single, self-contained file that encapsulates an entire Git repository or a specific subset of its objects and references. This "bundle" file acts as a transportable repository, allowing for Git operations like cloning or fetching without direct network access to the original repository.
It's primarily used for:
- Transferring repositories between systems that lack a shared network.
- Creating portable backups of a repository's history.
- Distributing specific versions or branches of a project.
- Creating "incremental" bundles, which only contain new commits that are not present in a receiving repository, optimizing data transfer.
A bundle file can be "cloned" from or "fetched" from using standard Git commands, just like a remote repository. It includes all necessary Git objects (commits, trees, blobs, tags) and references (branches, tags) as specified during its creation. However, it does not include the working tree content or repository configuration, only the .git
directory's core data.
CAVEATS
A bundle file cannot be directly pushed to; it is read-only for client operations (clone/fetch).
Bundles only contain the Git object database and references, not the working tree files.
Once created, a bundle is a static snapshot; changes in the original repository are not reflected in existing bundles.
INCREMENTAL BUNDLES
One of the most powerful uses of git-bundle is creating incremental bundles. This involves specifying a commit or branch that the recipient already has, ensuring the bundle only contains objects not reachable from that known commit. For example, to create a bundle of new commits on main since a specific commit ABCDEF (known to exist on the receiver), you would use:
git bundle create my-update.bundle main --not ABCDEF
This significantly reduces the bundle size for updates.
CONSUMING A BUNDLE
To use a created bundle, you can treat it like a remote repository URL. The most common ways are:
git clone my-repo.bundle my-new-repo
...or if you have an existing repository and want to fetch from the bundle:
git fetch my-repo.bundle master
This allows the receiving repository to pull in the history and objects contained within the bundle file.
HISTORY
The git-bundle command was introduced early in Git's development (around Git 1.5.0, circa 2007) to address the need for transferring repositories in disconnected environments. It provided a robust alternative to simpler methods like git-archive
for maintaining full repository history and enabling operations like cloning or fetching from a single file. Over time, features like verify and list-heads were added to enhance its utility for managing and inspecting bundle files.
SEE ALSO
git-clone(1), git-fetch(1), git-archive(1), git-pack-objects(1)