git-ls-remote

Show all references in the default remote repository

$ git ls-remote

$ git ls-remote --heads

$ git ls-remote [[-t|--tags]]

$ git ls-remote [repository_url]

$ git ls-remote [repository_name] "[pattern]"

git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>] [-q | --quiet] [--exit-code] [--symref] [--sort=<key>] [--format=<format>] [-n | --notes] [<repository> [<ref ...>]]

--heads
    Limit to refs/heads (branches only)

--tags
    Limit to refs/tags (tags only)

--refs
    List all references (default when querying specific refs)

--upload-pack=<exec>
    Specify path to git-upload-pack on remote

-q, --quiet
    Suppress capabilities output

--exit-code
    Exit code 0 if refs found, 1 otherwise; ignores output

--symref
    Include symbolic refs like HEAD with targets

--sort=<key>
    Sort output by refname, version:refname, or v:refname

--format=<format>
    Format output (e.g., %(refname), %(objectname))

-n, --notes
    List refs/notes/* references

<repository>
    Remote URL or nickname (stdin if omitted)

<ref> ...
    Specific refs or patterns to match

The git ls-remote command is a lightweight Git plumbing tool that retrieves and displays references (such as branches, tags, and notes) from a remote repository without downloading any objects or updating the local repository.

It communicates directly with the remote server using the git-upload-pack protocol, outputting each reference as a line with the commit SHA-1 hash followed by the refname (e.g., refs/heads/main).

This makes it ideal for scripts checking remote branch existence, verifying tags, or integrating with CI/CD pipelines. By default, it lists all references unless filtered by options like --heads or --tags. It supports specifying a single repository URL or multiple refs to query.

Unlike git fetch, it avoids local changes and network overhead for object transfer, providing fast metadata-only access.

Does not support reflogs or local-only refs; output uses SHA-1 (migrating to SHA-256); fails if remote lacks upload-pack support.

git ls-remote origin lists all remote refs.
git ls-remote --heads --tags origin shows branches/tags only.
git ls-remote origin main checks specific branch SHA.

Each line: <SHA-1> <refname> (e.g., 1a2b3c... refs/heads/main).
Capabilities printed first unless --quiet.

Introduced in Git 0.99 (2005) as basic plumbing; evolved with sorting/formatting in Git 1.7+ (2010) and notes support in Git 1.6.6 (2009); remains stable for scripting.

git remote(1), git fetch(1), git show-ref(1), git rev-parse(1)