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

> git ls-remote lists refs on a remote without cloning. Reference for --tags, --heads, and resolving a branch SHA cheaply in CI gating steps.

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

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

> `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 Command: Query Remote Refs in CI?

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.

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

---

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