format-bundle Git Command Guide

The git format-bundle command is used to package a range of commits into one or more binary files, known as a “bundle”. This is useful for transferring Git objects between repositories when there is no direct network connection, a workflow often referred to as “sneaker-net”.

git format-bundle Syntax:

git format-bundle [options] <git-rev-list-args>

The command generates a bundle file from a list of revisions.

Options:

Option	Description
<git-rev-list-args>	A revision range or a list of commits to include in the bundle (e.g., master..feature or HEAD~5..HEAD).
-o <file> / --output <file>	Instead of creating a file based on the branch name, write to the specified file. If <file> is -, write to standard output.
--all	Bundle all refs in refs/heads/. This can be combined with --remotes and --tags to bundle all refs.
--since=<date>	Bundle commits more recent than a specific date.
--until=<date>	Bundle commits older than a specific date.
-<n> / --max-count=<n>	Limit the number of commits to include in the bundle.
--progress	Show a progress meter on the standard error stream.
-h / --help	Display the help message for the command.

Parameters:

Parameter	Description
<revision-range>	(Required) Specifies the commits to be included in the bundle. For example, origin/master..HEAD bundles all commits that are in the current branch but not in origin/master.

Caution

A bundle file is not human-readable like the output of git format-patch. It is a binary file containing compressed Git objects. To use it, you must use git clone, git fetch, or git pull directly from the bundle file, or use git bundle unbundle to extract the objects into your repository.

git format-bundle Command Samples:

1. Create a bundle of all commits on the current branch that are not on main

This command will create a file named <branch-name>.bundle.

git format-bundle main..HEAD

2. Create a bundle for the last 5 commits

This creates a bundle file containing the last five commits from the current branch.

git format-bundle -5 HEAD

3. Create a bundle and name the output file

This bundles the commits from the feature-branch and saves them to feature.bundle.

git format-bundle main..feature-branch --output feature.bundle

4. Bundle an entire repository

This command creates a bundle file containing all objects from all branches, which can be used to clone a repository offline.

git format-bundle --all --output repo.bundle

Tip

Bundles are self-contained and portable. You can send a bundle file via email, USB stick, or any other means to another developer. They can then fetch the commits from the bundle into their own repository as if they were fetching from a remote.

FAQ 1: What is the difference between git format-bundle and git format-patch?

git format-patch creates a series of human-readable patch files (.patch), one for each commit, which are applied using git am. git format-bundle creates a single binary file (.bundle) that contains all the Git objects (commits, trees, blobs). Bundles are used with git fetch or git pull and are generally more efficient for transferring a large number of commits.

FAQ 2: How do I use a bundle file?

You can treat a bundle file like a remote repository. To view its contents: git bundle verify my-bundle.bundle To see which branches it contains: git ls-remote my-bundle.bundle To fetch from it: git fetch my-bundle.bundle feature-branch:new-local-branch To clone from it: git clone my-repo.bundle my-new-repo-dir

Applications of the format-bundle command

1. Offline Workflows: Transferring commits between two computers that are not connected to the same network (e.g., in a high-security environment).
2. Archiving: Creating a single-file backup of a branch or an entire repository at a specific point in time.
3. Code Submission: Submitting changes for review in environments where direct pushing to a repository is not allowed. The bundle can be emailed to a project maintainer.
4. Improving Performance: Bundling many commits can be faster than fetching them individually over a slow or high-latency network connection.
5. Initial Repository Seeding: Quickly setting up a new repository clone by transferring a bundle file via a fast local network or USB drive, and then fetching only the latest changes over the internet.