git ls-remote: Usage, Options & Common CI Errors

By Daniel Zoghalchali·Latchkey

git ls-remote shows the refs and their SHAs on a remote - no clone required.

ls-remote is the cheap way to check if a tag exists or what SHA a branch points to before doing real work.

What it does

git ls-remote queries a remote repository and prints its references (branches, tags) and the object names they point to, without downloading objects.

Common usage

Terminal

git ls-remote --heads origin
git ls-remote --tags origin
git ls-remote origin main
# fail if a tag is missing:
git ls-remote --exit-code --tags origin v1.2.0

Options

Flag	What it does
--heads	List branch refs only
--tags	List tag refs only
--exit-code	Exit non-zero if no matching refs
--refs	Filter out peeled/dereferenced tag entries
-q / --quiet	Suppress non-ref output

Common errors in CI

fatal: could not read Username for 'https://…' or 'Authentication failed' - a private remote needs credentials even just to list refs. Provide a token in the URL. An empty result with --exit-code returns 2, which scripts can use to branch on existence.

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

Frequently asked questions

git ls-remote: Usage, Options & Common CI Errors?