git ls-remote

Curl for Git remotes.

🎯 What & why

git ls-remote queries a remote's refs over the wire without fetching any objects. Like curl for Git: cheap, scriptable, and works without a working tree.

🧠 Mental model

It is a ref-discovery RPC. The remote streams back its branch and tag list with SHAs; you can filter, sort, and even resolve symbolic refs like HEAD.

🛠️ Synopsis

git ls-remote [-h] [-t] [--exit-code] [--get-url] [--symref] [--sort=<key>] <remote> [<patterns>...]

🎚️ Switches & options

Flag	What it does
`<remote>`	Remote name or URL (e.g., origin, https://github.com/foo/bar)
`<patterns>...`	Glob patterns to filter refs server-side
`-h, --heads`	Only show branch refs (refs/heads/*)
`-t, --tags`	Only show tag refs (refs/tags/*)
`--exit-code`	Exit 2 if no matching refs found — useful in scripts
`--get-url`	Print the resolved URL instead of querying; honors insteadOf
`--symref`	Show what HEAD (or other symrefs) points to
`--sort=<key>`	Sort output by key (e.g., -v:refname for newest tags first)

💡 Use cases

Check whether a tag exists upstream before bothering to fetch
Discover the default branch of an arbitrary repo via --symref HEAD
Build release automation that polls for new tags without cloning
Resolve what URL a remote name actually maps to with --get-url

🧪 Examples

List everything on origin

git ls-remote origin

Only branches matching a pattern

git ls-remote -h origin 'refs/heads/release/*'

Find the default branch

git ls-remote --symref origin HEAD

Newest tags first

git ls-remote -t --sort=-v:refname origin

🎓 Recommendations

Use --exit-code in CI scripts so 'no matching refs' becomes a real failure rather than silent success
Prefer ls-remote over fetch when you only need to know IF a ref exists — it is dramatically cheaper

🪤 Common pitfalls

Without -h or -t you get every ref including refs/pull/* on some hosts — filter explicitly
Network and auth still apply; an unreachable or private remote will fail just like fetch

🔗 Related modules

📝 Quiz

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