git ls-remote Command: Query Remote Refs in CI

git ls-remote shows the refs a remote advertises, without downloading any objects.

ls-remote answers questions like "what is the latest tag" or "does this branch exist" without a clone. That makes it ideal for cheap pre-flight checks in CI.

Common flags

--heads - list only branch refs
--tags - list only tag refs
--refs - strip dereferenced tag entries (the ^{} lines)
--sort=-version:refname - sort refs by version
<url> <pattern> - restrict to refs matching a pattern
-q / --quiet - suppress the "From URL" header

Example

shell

# Resolve a branch SHA on the remote without cloning
git ls-remote https://github.com/owner/repo.git refs/heads/main | cut -f1
# Find the newest release tag remotely
git ls-remote --tags --refs --sort=-version:refname \
  https://github.com/owner/repo.git 'v*' | head -n1

In CI

Use ls-remote to detect new upstream releases or verify a ref exists before spending time on a full clone. It transfers no objects, so it is a fast, low-cost gate at the start of a pipeline.

Key takeaways

git ls-remote inspects remote refs without cloning, making it a cheap CI pre-check.
Use --refs to drop the noisy dereferenced ^{} tag lines.
Resolve a remote branch SHA with a refs/heads pattern and cut -f1.