git fetch-pack

What 'fetch' invokes to negotiate and receive packs.

🎯 What & why

git fetch-pack is the client half of object exchange — it talks to a remote upload-pack, negotiates which objects you have versus what you want, and writes the resulting pack into your object store.

🧠 Mental model

Picture a 'have/want' conversation: client lists wants (refs to fetch), then offers haves (commits it already owns); the server walks back until it finds common ancestors and ships only the missing closure as a thin or thick pack.

🛠️ Synopsis

git fetch-pack [--all] [--quiet|-q] [--keep|-k] [--thin]
               [--include-tag] [--upload-pack=<git-upload-pack>]
               [--depth=<n>] [--shallow-since=<date>]
               [--shallow-exclude=<ref>] [--deepen-relative]
               [--no-progress] [--check-self-contained-and-connected]
               [--cloning] [-v] <repository> [<refs>...]

🎚️ Switches & options

Flag	What it does
`--all`	Fetch every ref the remote advertises
`--quiet`	Suppress non-error output to stderr
`--keep`	Keep the downloaded pack rather than letting it be exploded into loose objects
`--thin`	Request a thin pack — smaller wire size, fattened locally
`--include-tag`	Pull annotated tags that point at fetched commits
`--upload-pack=<path>`	Override the path to git-upload-pack on the remote (for non-standard installs)
`--depth=<n>`	Create a shallow history truncated to n commits per branch
`--no-progress`	Do not emit progress meters — useful in scripts
`--check-self-contained-and-connected`	Verify the received pack is fully connected before installing
`--cloning`	Internal flag set when called from git clone — relaxes some checks

💡 Use cases

Diagnose what 'git fetch' is actually negotiating with the server
Fetch a single ref over a custom transport (e.g. through a pipe to a non-standard upload-pack)
Verify a remote can produce a self-contained pack for a given ref
Build lower-level tooling that needs raw access to the negotiation

🧪 Examples

Fetch a single branch from a local daemon

git fetch-pack --no-progress git://127.0.0.1/repo.git refs/heads/main

Shallow fetch of depth 1

git fetch-pack --depth=1 git@github.com:user/repo.git refs/heads/main

Use a custom upload-pack binary

git fetch-pack --upload-pack=/opt/custom/git-upload-pack ssh://host/repo refs/heads/*

Verbose negotiation trace

GIT_TRACE_PACKET=1 git fetch-pack -v --all git://127.0.0.1/repo.git

🎓 Recommendations

Use 'git fetch' for everyday work; reach for fetch-pack only when you need to script the wire protocol
Combine with GIT_TRACE_PACKET=1 to see the actual have/want lines flying back and forth
When debugging slow fetches, --no-progress plus tracing reveals whether time is spent in negotiation or transfer

🪤 Common pitfalls

Calling fetch-pack does not update remote-tracking refs — only 'git fetch' does that bookkeeping
Shallow options can leave a repo that other commands (rebase, blame across history) cannot satisfy
Without --keep, the pack may be exploded into loose objects, which is slower for large fetches

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.