git ls-remote Command: Query Remote Refs in CI

By Daniel Zoghalchali·Latchkey

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.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

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.

Frequently asked questions

git ls-remote Command: Query Remote Refs in CI?