Appearance
Git Transport Protocol: Wire Protocol, Negotiation, and Packfile Transfer
Every git fetch, git push, and git clone is a conversation between two Git processes over a transport layer. The client and server negotiate what objects the client needs, then the server sends a packfile. Understanding this conversation is the difference between guessing why a clone is slow and knowing exactly which phase to optimize.
This guide covers the wire protocol (v1 and v2), the ref advertisement, negotiation phases, packfile transfer, and the protocol extensions that enable partial clone, shallow, and filter operations. It assumes you know what a packfile is and how Git stores objects.
The conversation in four phases
Every fetch or clone follows the same sequence:
Client Server
| |
|--- ref advertisement request ----->|
|<--- refs + capabilities -----------|
|--- want/have negotiation --------->|
|<--- packfile (objects + deltas) ---|
|--- done -------------------------->|Phase 1: Ref advertisement
The client connects and asks for the server's refs. The server responds with every ref (branch, tag, HEAD) and its SHA, plus a list of capabilities the server supports.
HTTP protocol v1 (the old default):
GET /repo.git/info/refs?service=git-upload-pack HTTP/1.1
Response:
001e# service=git-upload-pack
0000
009b6a5f1b... HEAD\0multi_ack thin-pack side-band side-band-64k ofs-delta
003f6a5f1b... refs/heads/main
003fb2c3d4... refs/heads/feature/x
0040c5d6e7... refs/tags/v1.0.0
0000Each line starts with a 4-digit hex length (including the length itself). 0000 terminates the list. The first line after the header contains the capabilities, separated by spaces after the SHA.
HTTP protocol v2 (Git 2.18+, enabled with protocol.version=2):
GET /repo.git/git-upload-pack HTTP/1.1
Git-Protocol: version=2
Response:
version 2
agent=git/2.43.0
ls-refs
fetch
server-option
0000Protocol v2 uses separate commands (ls-refs, fetch) instead of one endpoint. The client sends capabilities in the request header, and the server lists only the commands it supports. Then the client calls ls-refs to get the ref list:
POST /repo.git/git-upload-pack HTTP/1.1
Git-Protocol: version=2
Command: ls-refs
0001
0000
Response:
6a5f1b... HEAD symref-target:refs/heads/main
6a5f1b... refs/heads/main
b2c3d4... refs/heads/feature/x
c5d6e7... refs/tags/v1.0.0
0000Phase 2: Negotiation (want/have)
The client tells the server which commits it wants and which it already has. The server uses this to determine the minimal set of objects to send.
Protocol v1 negotiation:
POST /repo.git/git-upload-pack HTTP/1.1
0032want 6a5f1b... multi_ack_detailed
0032want b2c3d4...
0032have a1b2c3d...
0032have e5f6a7b...
0000The server responds with ACK or NAK for each have line. The client continues sending have lines until the server sends ACK common or the client decides the negotiation is done.
Protocol v2 negotiation:
Protocol v2 sends the negotiation as a single fetch command with arguments:
Command: fetch
0001
want b2c3d4...
have a1b2c3d...
have e5f6a7b...
done
0000The done tells the server to stop negotiating and send the packfile. The server can also send a shallow-info section if the client requested a shallow fetch.
Phase 3: Packfile transfer
The server packs the negotiated objects into a packfile and streams it back. The packfile uses the same format as on disk: a header, then objects in SHA-sorted order (or delta order), then a trailer with the packfile SHA-1.
The side-band capability wraps the packfile in a multiplexed channel:
| Band | Content | Use |
|---|---|---|
| 1 | Packfile data | The actual object stream |
| 2 | Progress messages | "Counting objects: 42% (42/100)" |
| 3 | Error messages | Fatal errors from the server |
The client reads band 1 for objects, displays band 2 to the user, and aborts on band 3.
Protocol v1 vs v2: what changed
| Aspect | v1 | v2 |
|---|---|---|
| Ref advertisement | Full list, no filtering | ls-refs command with prefix filter |
| Capability negotiation | Embedded in ref advertisement | Separate capability list |
| Negotiation | Multi-round have/ACK | Single round with done |
| Filter support | None | Native filter argument |
| Server options | None | server-option capability |
| Packet format | Length-prefixed pkt-line | Same pkt-line format |
Protocol v2 reduces round trips. A clone that takes 3-4 HTTP requests in v1 completes in 2 in v2. For repos with thousands of refs, the ls-refs prefix filter saves transferring the entire ref list.
Enable v2 globally:
bash
git config --global protocol.version 2Or per-command:
bash
git -c protocol.version=2 fetch originCapability flags and what they enable
Capabilities are strings sent in the ref advertisement (v1) or the capability list (v2). Each one unlocks a protocol feature:
| Capability | Protocol | What it enables |
|---|---|---|
multi_ack | v1 | Server can ACK multiple have lines |
multi_ack_detailed | v1 | Server sends detailed ACK (common, ready, etc.) |
thin-pack | both | Server omits base objects the client already has |
side-band / side-band-64k | both | Multiplexed output (data, progress, error) |
ofs-delta | both | Delta references use offset, not SHA |
shallow | both | Shallow clone support |
deepen-since | both | Shallow by timestamp |
deepen-not | both | Shallow by ref exclusion |
filter | v2 | Partial clone filter (blob:none, tree:0, etc.) |
ref-in-want | v2 | Client can request a specific ref by name |
server-option | v2 | Arbitrary key=value options to the server |
atomic | push | All-or-nothing push |
push-options | push | Arbitrary push options (passed to hooks) |
report-status-v2 | push | Detailed per-ref push status |
A client and server negotiate the intersection of their capabilities. If the server does not advertise filter, the client cannot request a partial clone, even if it supports it locally.
Partial clone on the wire
Partial clone uses the filter capability in protocol v2. The client sends a filter spec in the fetch command:
Command: fetch
0001
want 6a5f1b...
have a1b2c3d...
filter blob:none
0000The server responds with a packfile that omits all blob objects matching the filter. The tree objects remain, but Git replaces missing blobs with a promisor marker. When the client later needs a blob, it makes a follow-up request:
Command: fetch
0001
want <missing-blob-sha>
have <known-base-sha>
0000This on-demand fetch is the "promisor" pattern — the server promised the object exists, and the client can request it when needed. The protocol is identical to a normal fetch; only the scope differs.
Shallow clone protocol
Shallow clones use the shallow capability. The client sends the depth (or timestamp/ref exclusion) in the request:
Command: fetch
0001
want 6a5f1b...
shallow 6a5f1b...
deepen 5
0000The server responds with a packfile that stops at the shallow boundary. It sends a shallow-info section listing the shallow boundary commits so the client can mark them.
For --depth=5, the server truncates history at 5 generations back. The client stores these boundary commits in .git/shallow. Subsequent fetches with --deepen=N extend the boundary.
The negotiation algorithm in detail
The negotiation phase is where most performance problems live. Git uses a greedy algorithm:
- Client sends
havelines for every local ref tip and reflog entry. - Server responds with
ACK(I have that commit) orNAK(I do not). - Client sends more
havelines from the commits parent chain. - Server sends
ACK commonwhen it finds enough shared history. - Client sends
done.
In protocol v1, this is multi-round. The client sends a batch of 32 have lines, waits for ACKs, then sends the next batch. A clone with no shared history (first fetch of a repo) sends zero have lines and skips straight to done.
In protocol v2, the client can send all have lines in one batch with done to skip multi-round negotiation. This is what git fetch --negotiate controls.
The key insight: if the server has to walk 100,000 commits before finding a common ancestor, that is 100,000 commit-graph lookups on the server side. fetch.negotiationAlgorithm=noop skips the walk entirely and sends the packfile immediately. Useful when you know the client has no shared history (fresh checkout of a different branch).
bash
# In CI: no shared history with the server, skip negotiation
git -c fetch.negotiationAlgorithm=noop fetch origin mainPush protocol
Push reverses the flow: the client sends the packfile first, then the server applies it and reports status.
Client Server
| |
|--- packfile (new objects) -------->|
|--- push report ------------------->|
|<--- status report -----------------|Push negotiation
The client sends push lines for each ref to update:
Command: push
0001
old-sha new-sha refs/heads/main
0000
packfile...The server checks each ref update against its hooks and refspec rules. If the update is a fast-forward (the old SHA is an ancestor of the new SHA), it applies. If not, the server rejects with an error.
Atomic pushes
With atomic capability, the client sends:
Command: push
0001
atomic
old-sha new-sha refs/heads/main
old-sha new-sha refs/heads/feature
0000The server stages all ref updates and applies them only if all succeed. If any single update fails, none are applied. Without atomic, each update is applied independently and some may succeed while others fail.
Debugging the protocol
Trace the wire
bash
# Full protocol dump (every packet sent and received)
export GIT_TRACE_PACKET=1
git fetch origin
# Just the packfile negotiation
export GIT_TRACE_PACK_ACCESS=1
git clone https://example.com/repo.git
# Connection-level trace
export GIT_CURL_VERBOSE=1
git fetch originOutput from GIT_TRACE_PACKET=1:
12:34:56.789123 pkt-line.c:80 packet: git< 001e# service=git-upload-pack
12:34:56.789456 pkt-line.c:80 packet: git< 0000
12:34:56.789789 pkt-line.c:80 packet: git< 009b6a5f1b HEAD\0multi_ack thin-pack side-band
12:34:56.790123 pkt-line.c:80 packet: git> 0032want 6a5f1b multi_ack_detailed
12:34:56.790456 pkt-line.c:80 packet: git< 0032ACK 6a5f1b commonMeasure phase timing
bash
# Time the full fetch
time git fetch origin
# Time just the negotiation (after ref advertisement)
GIT_TRACE_PERFORMANCE=1 git fetch origin 2>&1 | grep -E "trace: (negotiate|prepare)"Count round trips
bash
# Enable protocol tracing and count pkt-line reads
GIT_TRACE_PACKET=1 git fetch origin 2>&1 | grep -c "packet: git>"A high count means the negotiation is doing many round trips. Consider protocol v2 or fetch.negotiationAlgorithm=noop for CI.
Performance characteristics
| Phase | Cost factor | Optimization |
|---|---|---|
| Ref advertisement | O(refs) | Protocol v2 with prefix filter |
| Negotiation | O(commits walked) | Commit-graph, --negotiate, noop algorithm |
| Packfile generation | O(objects to send) | Bitmaps, multi-pack-index |
| Packfile transfer | O(bytes) | Thin-pack, ofs-delta, compression |
| Packfile index | O(objects) | Receive from a prepared .idx |
The negotiation phase dominates on repos with deep history and little shared ancestry. The packfile transfer dominates on initial clones of repos with large blobs.
Protocol version negotiation
The client requests a protocol version via:
- SSH:
GIT_PROTOCOLenvironment variable set toversion=2 - HTTP:
Git-Protocol: version=2header - Git transport: First line of the connection is
git-upload-pack \0host=...\0version=2
The server responds with the highest version it supports, or falls back to v1 if it does not understand the request.
Check which version your remote supports:
bash
# With GIT_TRACE_PACKET, the version negotiation appears in the first lines
GIT_TRACE_PACKET=1 git ls-remote origin 2>&1 | head -5If you see version 2 in the response, v2 is active. If you see only hex-encoded pkt-lines without version, the connection is v1.
Edge cases
| Situation | Protocol behavior | Impact |
|---|---|---|
Server does not advertise filter | Client cannot request partial clone | Fall back to full clone |
Client sends have for non-existent SHA | Server sends NAK | Wasted round trip. Clean up reflog. |
| Large ref advertisement (10k+ refs) | v1 sends all; v2 filters by prefix | v2 saves ~50 KB per ls-remote call |
| Server-side hook rejects push | Server sends error message, status ng | Client shows the hook output |
| Network drops mid-packfile | Client has partial packfile, objects are missing | git fsck shows broken links. Re-fetch. |
Clone with --filter=blob:none then git checkout | Promisor fetches blob for every file | First checkout after partial clone is slow |
Key commands reference
| Command / Variable | What it does |
|---|---|
git config --global protocol.version 2 | Enable protocol v2 |
git -c fetch.negotiationAlgorithm=noop fetch | Skip negotiation (CI pattern) |
GIT_TRACE_PACKET=1 git fetch | Dump every protocol packet |
GIT_CURL_VERBOSE=1 git fetch | HTTP-level trace |
GIT_TRACE_PERFORMANCE=1 git fetch | Time each phase |
git ls-remote --refs origin | List refs with protocol v2 prefix filter |
git config --global http.postBuffer 524288000 | Increase POST buffer for large pushes |
Related guides
- Partial Clone & Promisor Mechanics — filter protocol in practice
- Clone Optimization — reducing clone time
- Bundle & Shallow Clones — offline and depth-limited clones
- Multi-Pack Index & Bitmaps — packfile serving performance
- Git Plumbing for CI — scripting protocol interactions