Synopsis

git ls-files [-c] [-d] [-m] [-o] [-i] [--exclude-standard]

Description

The git ls-files command lists files known to Git's index (and optionally the working tree). It supports filters: cached/staged, deleted, modified, others (untracked), ignored, unmerged, and so on. It is faster and more precise than find for "show me all tracked files."

Dans l'usage quotidien, git ls-files 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-files --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-files 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-files aide à éviter les trois.

When to Use

Most users invoke porcelain like git status or git grep rather than ls-files. Reach for it in scripts that operate on tracked files (lint tools, formatters, sync scripts) where you want a clean, ignore-aware list.

Options courantes

Exemples

git ls-files
# Every tracked file

git ls-files -o --exclude-standard
# Untracked, non-ignored files

git ls-files -m
# Locally modified tracked files

git ls-files -s
# Show mode, SHA, and stage number for each entry

Erreurs fréquentes

Forgetting --exclude-standard when listing untracked files swamps you with ignored junk. Combining filters can be confusing — if you pass both -c and -o, the meaning depends on context.

Commandes liées

git status, git ls-tree, git update-index, git grep