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).
git ls-remote [--heads] [--tags] [--refs] [--symref] [--exit-code] [<repository> [<pattern>...]]
Try it
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.
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-remoteneeds 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.0matchesrefs/tags/v1.0and alsorefs/heads/v1.0. Spell outrefs/...when it matters. - The listing is not sorted by recency, only by name. To find the newest tag use
--sort=-version:refname. - When
--tagsand--headsare 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-remoteagainst a local directory, as in the examples, which makes demos and tests possible without a network.