Skip to content

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
0000

Each 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
0000

Protocol 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
0000

Phase 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...
0000

The 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
0000

The 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:

BandContentUse
1Packfile dataThe actual object stream
2Progress messages"Counting objects: 42% (42/100)"
3Error messagesFatal 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 ​

Aspectv1v2
Ref advertisementFull list, no filteringls-refs command with prefix filter
Capability negotiationEmbedded in ref advertisementSeparate capability list
NegotiationMulti-round have/ACKSingle round with done
Filter supportNoneNative filter argument
Server optionsNoneserver-option capability
Packet formatLength-prefixed pkt-lineSame 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 2

Or per-command:

bash
git -c protocol.version=2 fetch origin

Capability 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:

CapabilityProtocolWhat it enables
multi_ackv1Server can ACK multiple have lines
multi_ack_detailedv1Server sends detailed ACK (common, ready, etc.)
thin-packbothServer omits base objects the client already has
side-band / side-band-64kbothMultiplexed output (data, progress, error)
ofs-deltabothDelta references use offset, not SHA
shallowbothShallow clone support
deepen-sincebothShallow by timestamp
deepen-notbothShallow by ref exclusion
filterv2Partial clone filter (blob:none, tree:0, etc.)
ref-in-wantv2Client can request a specific ref by name
server-optionv2Arbitrary key=value options to the server
atomicpushAll-or-nothing push
push-optionspushArbitrary push options (passed to hooks)
report-status-v2pushDetailed 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
0000

The 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>
0000

This 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
0000

The 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:

  1. Client sends have lines for every local ref tip and reflog entry.
  2. Server responds with ACK (I have that commit) or NAK (I do not).
  3. Client sends more have lines from the commits parent chain.
  4. Server sends ACK common when it finds enough shared history.
  5. 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 main

Push 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
0000

The 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 origin

Output 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 common

Measure 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 ​

PhaseCost factorOptimization
Ref advertisementO(refs)Protocol v2 with prefix filter
NegotiationO(commits walked)Commit-graph, --negotiate, noop algorithm
Packfile generationO(objects to send)Bitmaps, multi-pack-index
Packfile transferO(bytes)Thin-pack, ofs-delta, compression
Packfile indexO(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_PROTOCOL environment variable set to version=2
  • HTTP: Git-Protocol: version=2 header
  • 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 -5

If 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 ​

SituationProtocol behaviorImpact
Server does not advertise filterClient cannot request partial cloneFall back to full clone
Client sends have for non-existent SHAServer sends NAKWasted round trip. Clean up reflog.
Large ref advertisement (10k+ refs)v1 sends all; v2 filters by prefixv2 saves ~50 KB per ls-remote call
Server-side hook rejects pushServer sends error message, status ngClient shows the hook output
Network drops mid-packfileClient has partial packfile, objects are missinggit fsck shows broken links. Re-fetch.
Clone with --filter=blob:none then git checkoutPromisor fetches blob for every fileFirst checkout after partial clone is slow

Key commands reference ​

Command / VariableWhat it does
git config --global protocol.version 2Enable protocol v2
git -c fetch.negotiationAlgorithm=noop fetchSkip negotiation (CI pattern)
GIT_TRACE_PACKET=1 git fetchDump every protocol packet
GIT_CURL_VERBOSE=1 git fetchHTTP-level trace
GIT_TRACE_PERFORMANCE=1 git fetchTime each phase
git ls-remote --refs originList refs with protocol v2 prefix filter
git config --global http.postBuffer 524288000Increase POST buffer for large pushes

Git Master — Git Reference for Every Skill Level