git-bundle

Create a bundle file that contains all objects and references of a specific branch

$ git bundle create [path/to/file.bundle] [branch_name]

$ git bundle create [path/to/file.bundle] --all

$ git bundle create [path/to/file.bundle] -5 [HEAD]

$ git bundle create [path/to/file.bundle] --since 7.days [HEAD]

$ git bundle verify [path/to/file.bundle]

$ git bundle unbundle [path/to/file.bundle]

$ git pull [path/to/file.bundle] [branch_name]

$ git clone [path/to/file.bundle]

git bundle create <file> [<git-bundle-option>...] [<git-rev-list-option>...]
git bundle verify <file>
git bundle list-heads <file>

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

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.

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.

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.

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.

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.

git-clone(1), git-fetch(1), git-archive(1), git-pack-objects(1)