Git Reference ยท Objects, Refs and Internals
Wire protocol v2
Reference for Git's wire protocol version 2: pkt-line framing, capability advertisement, the ls-refs and fetch commands, and how to trace a real exchange.
When git fetch or git clone talks to another repository, the two sides speak the Git transfer protocol. Version 2, the default for years, replaced the older chatty design in which the server opened by listing every ref it had. In v2 the client asks for what it needs: first the server's capabilities, then a command such as ls-refs (list the refs I care about) or fetch (send me these objects).
The same protocol is used over several transports: SSH, the smart HTTP(S) protocol, the git:// daemon and local paths. Everything is carried as pkt-lines, short length-prefixed records, so the framing is the same everywhere.
GIT_TRACE_PACKET=1 git ls-remote ../server # see every pkt-line git -c protocol.version=2 fetch origin # ask for v2 explicitly git -c protocol.version=0 fetch origin # fall back to v0
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.
Framing: pkt-lines
A pkt-line is a four-digit hexadecimal length followed by the payload. The length counts the four digits themselves, so 0014command=ls-refs\n is 20 bytes (0x14). The largest packet is 65520 bytes. Text payloads usually end with a newline.
| Packet | Meaning |
|---|---|
0000 |
flush-pkt: end of a message or stream. |
0001 |
delim-pkt (v2 only): separates the arguments of a command from its capability list. |
0002 |
response-end-pkt (v2 only): ends a response on a stateless transport such as HTTP. |
The conversation
- The server advertises first:
version 2, then a list of capabilities (agent=...,ls-refs,fetch=shallow wait-for-done filter,server-option,object-format=sha1,object-info, and so on), ended by a flush-pkt. - The client sends a command:
command=<name>, capability lines such asagent=...andobject-format=sha1, a delim-pkt, the command arguments, and a flush-pkt. - The server answers, then waits for the next command. A client may send several commands on one connection (stateful transports) or one per HTTP request.
ls-refs
Arguments include peel (add the peeled value of annotated tags), symrefs (show where symbolic refs point), ref-prefix <prefix> (list only refs starting with it), and unborn. Because the client sends prefixes such as refs/heads/ and refs/tags/, a server with a million refs sends only what is useful. The reply lists <id> <refname> plus attributes like symref-target: and peeled:.
fetch
The client sends want <id> lines for objects it wants and have <id> lines for objects it has, plus options: thin-pack, ofs-delta, shallow, deepen <n>, filter <spec> for partial clones, want-ref <name>, include-tag, sideband-all. The server replies in sections separated by delim-pkts: acknowledgments (which haves it recognizes and whether it is ready), shallow-info, wanted-refs, and packfile, which carries the pack on sideband channels (1 = pack data, 2 = progress messages, 3 = fatal error).
Other commands
object-info returns object sizes without sending objects, and bundle-uri lets a server point clients at pre-built bundles to download first. Pushes still use the older receive-pack exchange and are not part of v2.
Usage notes
- Selection. The client sends
Git-Protocol: version=2(HTTP header) or setsGIT_PROTOCOL=version=2(SSH, local). Servers that do not understand it answer in v0, and the client falls back automatically. - Config.
protocol.versionaccepts 0, 1 or 2; the default is 2. - Debugging.
GIT_TRACE_PACKET=1prints pkt-lines;GIT_TRACE_CURL=1shows HTTP traffic;GIT_TRACE2=1shows timings. - Local paths. For a plain path
gitrunsupload-packas a child process and speaks the same protocol over pipes. - Security. The
filetransport is restricted when it arrives via submodules:protocol.file.allowdefaults touser, which is why the example passes-c protocol.file.allow=always. - Wire versus storage. The pack sent in the
packfilesection follows the pack format described in Packfile format.