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 [options] repository [ref-patterns...]

repository
    The remote repository to query. This can be the name of a remote configured in your local repository (e.g., origin) or a direct URL to a Git repository (e.g., https://github.com/git/git.git).

[ref-patterns...]
    Optional patterns to filter the references displayed. If provided, only references matching these patterns will be shown. For example, heads/main or tags/v1.0.

--heads, -h
    Show only the heads (branches) available on the remote.

--tags, -t
    Show only the tags available on the remote.

--all
    Show both heads and tags. This is equivalent to specifying both --heads and --tags.

--upload-pack=<path>
    Specify the path to the git-upload-pack command on the remote host. Useful when the remote Git daemon is not in the standard PATH.

--exit-code
    Exit with a non-zero status code if any of the specified ref-patterns were not found on the remote. This is useful for scripting to check for the existence of specific references.

--get-url
    Display the URL for the specified remote and exit. This option doesn't actually query the remote repository.

git ls-remote is a low-level Git command used to query a remote repository and display the references (like branches and tags) it makes available. Unlike git clone or git fetch, it does not download any objects; it merely lists the SHA-1 hashes and corresponding reference names on the remote. This command is particularly useful for scripting, inspecting the state of a remote repository without fetching its content, or verifying what branches and tags exist before interacting further. You can specify a remote by its name (if it's already configured in your local repository) or directly by its URL. Optional arguments allow you to filter the results, showing only heads (branches), only tags, or specific references that match a given pattern.

git ls-remote is a low-level command primarily for scripting and inspection. Its output format is raw SHA-1 hashes and reference names, which might be less user-friendly compared to higher-level commands like git branch -r. It only lists references and does not fetch any actual Git objects, requiring network access to the remote repository.

The output of git ls-remote typically consists of lines, each containing a SHA-1 hash followed by a tab character, and then the full reference name. For example:

a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0 (tab) refs/heads/main

For annotated tags, there might be a second line representing the object the tag points to, e.g.:

a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0 (tab) refs/tags/v1.0
b1c2d3e4f5g6h7i8j9k0l1m2n3o4p6q7r8s9t0u1 (tab) refs/tags/v1.0^{}

When specifying ref-patterns, you can use glob-style patterns to filter the references. For instance, heads/* would match all branches, and tags/v* would match all tags starting with 'v'. If no patterns are specified, all references are shown (unless --heads or --tags is used).

git ls-remote has been a fundamental part of Git since its early versions. It plays a crucial role in the Git network protocols, specifically during the 'reference advertisement' phase where a client discovers what references a remote repository has available before initiating operations like cloning or fetching. Its core functionality has remained consistent, serving as a stable and essential component for remote repository interaction and discovery.

git remote(1), git fetch(1), git branch(1), git tag(1), git show-ref(1)