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

> git ls-remote lists refs on a remote without cloning. Reference for --heads, --tags, --exit-code, and the auth and not-found errors CI scripts hit.

Source: https://latchkey.dev/learn/command-reference/git-ls-remote  
Updated: 2026-06-25

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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

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

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 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt