Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Remotes and Collaboration

git ls-remote command

Reference for git ls-remote: list the branches, tags and other refs of a remote repository and their commit IDs without cloning it. Options --heads, --tags, --symref.

git ls-remote asks a repository, usually a remote one, for its list of refs and prints each as <object id> and <ref name>. Nothing is downloaded or stored locally, so it is a cheap way to check which branches and tags exist, whether a branch moved, or what a tag points to, before cloning or fetching.

It works on a configured remote name, a URL, or a local path. Inside a repository, with no argument, it contacts the upstream remote of the current branch (or origin).

Terminal
git ls-remote [--heads] [--tags] [--refs] [--symref] [--exit-code] [<repository> [<pattern>...]]

Try it

Bash Branches, tags and HEAD of a repository

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Patterns, --symref and --exit-code

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Output lines look like <40-hex-id><TAB><refname>. For an annotated tag, a second line ends with ^{} and shows the commit the tag points at ("peeled" value).

Option / argument Description
<repository> Remote name, URL or path. Omitted: the upstream or origin.
<pattern>... Show only refs matching one of these shell-style patterns, tested against the end of the ref name: main, feature/*, refs/tags/v1.*.
-b, --branches (--heads) Only refs/heads/*. --heads is the older spelling; recent versions prefer --branches.
-t, --tags Only refs/tags/*.
--refs Skip HEAD and peeled ^{} entries.
--symref Also show symbolic refs, such as ref: refs/heads/main<TAB>HEAD.
--exit-code Exit with status 2 when no matching ref is found (otherwise the status is 0).
--get-url Print the URL after insteadOf rewriting and do not contact the server.
--sort=<key> Sort by refname, version:refname and so on.
-q, --quiet Do not print the From <url> line on standard error.
-o <opt>, --server-option=<opt> Pass a protocol v2 option to the server.
--upload-pack=<exec> Path of git-upload-pack on the remote, for unusual setups.

Usage notes

  • Because the server answers a ref listing, ls-remote needs read access but does not transfer any objects. It still authenticates, so it can be used to test credentials.
  • Patterns match from the end of the name: git ls-remote origin v1.0 matches refs/tags/v1.0 and also refs/heads/v1.0. Spell out refs/... when it matters.
  • The listing is not sorted by recency, only by name. To find the newest tag use --sort=-version:refname.
  • When --tags and --heads are both given, you get both sets; with neither, you get everything including hidden refs such as pull request refs on some hosts (refs/pull/*).
  • Scripts often compare the commit ID of a remote branch with a local one to decide whether a fetch is needed.
  • With --exit-code, 0 means "found at least one", 2 means "nothing matched", and other statuses are real errors such as a failed connection.
  • You can run ls-remote against a local directory, as in the examples, which makes demos and tests possible without a network.