git ls-remote: Usage, Options & Common CI Errors
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.0Options
| 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.
Related guides
git fetch: Usage, Options & Common CI Errorsgit fetch downloads remote objects and refs without touching your working tree. Reference for --depth, --unsh…
git remote: Usage, Options & Common CI Errorsgit remote manages the named connections to remote repositories. Reference for add, set-url, -v, remove, and…
git clone: Usage, Options & Common CI Errorsgit clone copies a remote repository into a new local directory. Reference for depth, branch, and submodule f…
git ls-files: Usage, Options & Common CI Errorsgit ls-files lists files Git knows about in the index. Reference for --others, --modified, --exclude-standard…