GITFORMAT-BUNDLE(5)

🎀 gitformat-bundle — the bundle file format, bestie 🎀

okay so this is from the gitformat-bundle(5) manual page and honestly? it's giving "underrated icon". let's get into it 💅

---

✨ NAME ✨

gitformat-bundle — literally the bundle file format. that's it. that's the whole name. slay.

---

🌸 SYNOPSIS 🌸

*.bundle
*.bdl

those are the file extensions, periodt. if you see a file ending in either of these, it's a bundle, no cap 🫶

---

💖 DESCRIPTION 💖

so the Git bundle format is a format that represents both refs and Git objects — like, both things, in one file, iconic behavior honestly ✨

a bundle is a header in a format similar to git-show-ref(1), followed by a pack in *.pack format. so it's basically a lil header sandwich with a pack in the middle 🥪

the format is created and read by the git-bundle(1) command, and it's supported by e.g. git-fetch(1) and git-clone(1) — so your faves all know how to handle it 💜

---

🦋 FORMAT 🦋

we're gonna use ABNF notation to define the Git bundle format, bestie. see gitprotocol-common(5) for the details — that's where the grammar lore lives 📚

a v2 bundle looks like this:

bundle    = signature *prerequisite *reference LF pack
signature = "# v2 git bundle" LF

prerequisite = "-" obj-id SP comment LF
comment      = *CHAR
reference    = obj-id SP refname LF

pack         = ... ; packfile

and a v3 bundle looks like this — notice the extra *capability in there, she upgraded 👑

bundle    = signature *capability *prerequisite *reference LF pack
signature = "# v3 git bundle" LF

capability   = "@" key ["=" value] LF
prerequisite = "-" obj-id SP comment LF
comment      = *CHAR
reference    = obj-id SP refname LF
key          = 1*(ALPHA / DIGIT / "-")
value        = *(%01-09 / %0b-FF)

pack         = ... ; packfile

---

🌈 SEMANTICS 🌈

a Git bundle consists of several parts, and we're gonna go through every single one because we don't skip sections in this house 🏠✨

• "Capabilities" — these are only in the v3 format, and they indicate functionality that the bundle requires to be read properly. v3 girlies only 💅
• "Prerequisites" — these list the objects that are NOT included in the bundle and the reader of the bundle MUST already have, in order to use the data in the bundle. like, you gotta already own these or the whole thing falls apart, no cap. the objects stored in the bundle may refer to prerequisite objects and anything reachable from them (e.g. a tree object in the bundle can reference a blob that is reachable from a prerequisite) and/or expressed as a delta against prerequisite objects. fancy 🔥
• "References" — these record the tips of the history graph — iow, what the reader of the bundle CAN git fetch from it. that's the good stuff 🍓
• "Pack" — this is the pack data stream git fetch would send, if you fetch from a repository that has the references recorded in the "References" above into a repository that has references pointing at the objects listed in "Prerequisites" above. literally just the pack, doing pack things 📦

in the bundle format, there can be a comment following a prerequisite obj-id. it's a comment and it has no specific meaning. the writer of the bundle MAY put any string here — go wild, write your whole diary in there if you want 🙈 — and the reader of the bundle MUST ignore the comment. so like, don't read it. just vibe past it.

🧚 Note on shallow clones and Git bundles

okay this one's important so pay attention 😭 — note that the prerequisites do not represent a shallow-clone boundary. the semantics of the prerequisites and the shallow-clone boundaries are different, and the Git bundle v2 format cannot represent a shallow clone repository. like it literally can't, don't ask her to, she won't 💀

---

👑 CAPABILITIES 👑

because there is no opportunity for negotiation, unknown capabilities cause git bundle to abort. no negotiation, no discussion, no "hear me out" — she just leaves the chat 😤

• object-format — specifies the hash algorithm in use, and can take the same values as the extensions.objectFormat configuration value. hash algorithm representation ✨
• filter — specifies an object filter as in the --filter option in git-rev-list(1). the resulting pack-file must be marked as a .promisor pack-file after it is unbundled. don't forget the .promisor or it's not the moment 🫶

---

⭐ GIT ⭐

part of the git(1) suite — one of the family, one of the girls 💜

---

and that's the whole page, bestie!! 💖✨ ngl this one ate. keep it in your back pocket, iykyk 🎀

with love from the Git 2.56.0 girlies, dated 2026-09-27 🌸 — go forth and bundle responsibly 💅🦋