Synopsis
git ls-remote [--heads] [--tags] [<repository> [<refs>...]]Description
The git ls-remote command queries a remote (without cloning or fetching) and prints the SHA-1 of each ref alongside the ref name. It is invaluable for scripting, CI pipelines, and quick inspection — for example, finding the latest tag on a remote or checking whether a branch exists. Because it does not download objects, it's lightweight and fast even against very large repositories.
You can pass a URL directly without configuring a remote first: git ls-remote https://github.com/user/repo.git. This makes it ideal for one-off inspection or build scripts that resolve a "latest" version.
In day-to-day use, git ls-remote integrates closely with shell aliases, editor plugins, and continuous integration. Power users often add aliases that combine flags they always pass, or wrap the command in scripts that enforce team conventions. Output formatting can be customized via Git config — pretty formats, color schemes, and pager behavior are all tunable. When something goes wrong, the first diagnostic step is usually to re-run the command with GIT_TRACE=1 in the environment, which reveals the underlying plumbing calls. For unusual situations, the --help output (git ls-remote --help) opens the full manual page with details on every option, including those rarely used in casual workflows but essential for debugging or scripting at scale.
Understanding how git ls-remote interacts with the rest of Git's data model — the object database, the index, refs, and the working tree — pays dividends. Each command operates on some subset of these pieces, and knowing which it touches helps predict outcomes and recover from mistakes. Reading the official Git documentation alongside hands-on practice in a throwaway repository is the fastest way to internalize the nuances. Most production issues with Git stem from one of three causes: surprising default behavior, partial network operations, or rewriting history that was already shared. A working mental model of git ls-remote's side effects helps avoid all three.
Common Options
| Option | Description |
|---|---|
--heads / -h | Limit output to branch refs. |
--tags / -t | Limit output to tag refs. |
--refs | Filter out the dereferenced peel of annotated tags. |
--symref | Show what symbolic refs (like HEAD) point to. |
--exit-code | Exit with non-zero if no matching refs found. |
--sort=<key> | Sort results by version, refname, etc. |
Examples
git ls-remote --heads origin
# List all branches on origin with their SHAs
git ls-remote --tags --refs origin
# List all tags (skipping ^{} dereferences)
git ls-remote https://github.com/git/git.git HEAD
# Show what HEAD on a public repo points to
git ls-remote --sort=-v:refname --tags origin 'v*' | head -1
# Find the highest semver tagCommon Mistakes
Parsing the output without --refs shows annotated tags twice (once as the tag object, once as name^{} for the underlying commit). Use --refs to suppress the peeled lines. Authentication can fail silently against private repos without a credential helper — test interactively first.
Related Commands
git remote, git fetch, git tag, git for-each-ref