Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Remotes and Collaboration

git bundle command

Reference for git bundle: create, verify, list-heads and unbundle. Ship commits, branches and tags as one file and use it like a remote with clone and fetch.

git bundle packs Git objects and references into one file that can be copied by any means: USB stick, email attachment, file share. The file acts like a read-only remote repository. You can clone from it, fetch from it and pull from it, with no server and no network.

A bundle is a header (a list of references and optional prerequisites) followed by a normal packfile. A bundle with prerequisites is incremental: it holds only new objects and can be used only by repositories that already have the prerequisite commits.

Terminal
git bundle create <file> <git-rev-list-args>
git bundle verify <file>
git bundle list-heads <file> [<refname>...]
git bundle unbundle <file> [<refname>...]

Try it

Bash Create, inspect and clone

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash An incremental bundle with a prerequisite

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Subcommand Description
create [options] <file> <rev-list-args> Writes a bundle containing everything the arguments select. At least one named reference is required: an empty selection fails.
verify <file> Checks the header and that all prerequisites exist in the current repository. Exits 0 if the bundle can be used.
list-heads <file> [<ref>...] Prints the commit ID and reference name of each reference in the bundle.
unbundle <file> [<ref>...] Unpacks the objects into the object database and prints the references. It does not create or move any ref. Mostly used by scripts.
create option Description
--all, --branches, --tags Include all refs, all branches or all tags.
<since>..<ref>, ^<commit> <ref> Revision ranges. Excluded commits become prerequisites.
--since=<date> Include commits newer than the date (prerequisite handling applies).
--version=(2|3) Bundle format. Version 3 adds capabilities such as the object format and filters.
--progress, --quiet Control the progress display.

Errors: Refusing to create empty bundle. when the range selects nothing; error: Repository lacks these prerequisite commits: when verifying an incremental bundle in the wrong repository.

Usage notes

  • A name is needed. git bundle create x.bundle HEAD~3..HEAD writes a bundle whose only ref is HEAD, but cloning from it cannot decide on a branch. Name a branch or tag so the receiver can fetch it by name.
  • Use it like a remote. git clone x.bundle dir, git fetch x.bundle <refspec>, git pull x.bundle <branch> and git remote add origin x.bundle all work. Refs are read-only; you cannot push to a bundle.
  • Keep track of what you sent. A tag such as sent on the last bundled commit makes the next incremental bundle sent..main.
  • Bundles are not encrypted or signed. Anyone with the file can read all history in it. Verify out-of-band, or sign tags.
  • Shallow and filtered repositories cannot always be bundled; version 3 bundles record the filter used.
  • Size. The file is a packfile, so it is compressed with deltas; it is usually much smaller than the working tree zip of the same data.
  • Use cases: air-gapped networks, backups of a repository in one file, seeding a clone for a slow connection (git clone from the bundle, then fetch the rest from the real remote), and bug reports.