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.
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
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.
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..HEADwrites a bundle whose only ref isHEAD, 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>andgit remote add origin x.bundleall work. Refs are read-only; you cannot push to a bundle. - Keep track of what you sent. A tag such as
senton the last bundled commit makes the next incremental bundlesent..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 clonefrom the bundle, then fetch the rest from the real remote), and bug reports.
Related
- git archive, git clone, git fetch, git remote
- Lessons: Bundle and archive, Remotes