Synopsis
git ls-remote [--heads] [--tags] [<repository> [<refs>...]]Description
The git ls-remote command queries a remote (without cloning or fetching) and prints the SHA-1 of each ref alongside the ref name. It is invaluable for scripting, CI pipelines, and quick inspection — for example, finding the latest tag on a remote or checking whether a branch exists. Because it does not download objects, it's lightweight and fast even against very large repositories.
You can pass a URL directly without configuring a remote first: git ls-remote https://github.com/user/repo.git. This makes it ideal for one-off inspection or build scripts that resolve a "latest" version.
Dans l'usage quotidien, git ls-remote s'intègre étroitement avec les alias de shell, les plugins d'éditeur et l'intégration continue. Les utilisateurs avancés ajoutent souvent des alias combinant les flags qu'ils passent toujours, ou enveloppent la commande dans des scripts qui appliquent les conventions d'équipe. Le formatage de la sortie peut être personnalisé via la configuration Git — pretty formats, schémas de couleurs et comportement du pager sont tous ajustables. Quand quelque chose tourne mal, la première étape de diagnostic est généralement de relancer la commande avec GIT_TRACE=1 dans l'environnement, ce qui révèle les appels de plomberie sous-jacents. Pour les situations inhabituelles, la sortie --help (git ls-remote --help) ouvre la page de manuel complète avec les détails de chaque option, y compris celles rarement utilisées dans les workflows ordinaires mais essentielles pour le débogage ou le scripting à grande échelle.
Comprendre comment git ls-remote interagit avec le reste du modèle de données de Git — la base d'objets, l'index, les refs et l'arborescence de travail — est rentable. Chaque commande opère sur un sous-ensemble de ces pièces, et savoir laquelle elle touche aide à prédire les résultats et récupérer après les erreurs. Lire la documentation officielle de Git en parallèle de la pratique sur un dépôt jetable est la façon la plus rapide d'intérioriser les subtilités. La plupart des problèmes de production avec Git proviennent de l'une de trois causes : comportement par défaut surprenant, opérations réseau partielles, ou réécriture d'historique déjà partagé. Un modèle mental fonctionnel des effets de bord de git ls-remote aide à éviter les trois.
Options courantes
| Option | Description |
|---|---|
--heads / -h | Limiter la sortie aux refs de branches. |
--tags / -t | Limiter la sortie aux refs de tags. |
--refs | Filtrer le déréférencement (peel) des tags annotés. |
--symref | Afficher vers quoi pointent les refs symboliques (comme HEAD). |
--exit-code | Sortir avec un code non nul si aucune ref correspondante. |
--sort=<key> | Trier les résultats par version, refname, etc. |
Exemples
git ls-remote --heads origin
# Lister toutes les branches sur origin avec leurs SHAs
git ls-remote --tags --refs origin
# Lister tous les tags (en sautant les déréférencements ^{})
git ls-remote https://github.com/git/git.git HEAD
# Afficher vers quoi pointe HEAD sur un dépôt public
git ls-remote --sort=-v:refname --tags origin 'v*' | head -1
# Trouver le tag semver le plus élevéErreurs fréquentes
Parsing the output without --refs shows annotated tags twice (once as the tag object, once as name^{} for the underlying commit). Use --refs to suppress the peeled lines. Authentication can fail silently against private repos without a credential helper — test interactively first.
Commandes liées
git remote, git fetch, git tag, git for-each-ref