Sinopsis
git ls-tree [-r] [-d] [-l] [--name-only] <tree-ish> [<path>...]Descripción
El comando git ls-tree lista los contenidos de un objeto tree: archivos, modos, tipos y SHAs. A diferencia de git ls-files (que muestra el index), opera sobre cualquier tree en cualquier commit.
Usado por scripts que necesitan navegar la estructura de directorios en una revisión específica. Combinado con -r, recurse en subtrees.
En el uso diario, este comando se integra estrechamente con alias de shell, plugins de editor e integración continua. Los usuarios avanzados a menudo añaden alias que combinan los flags que siempre pasan. El formato de salida puede personalizarse vía configuración de Git. Cuando algo sale mal, ejecuta el comando con GIT_TRACE=1 para revelar las llamadas plumbing subyacentes.
Entender cómo este comando interactúa con el resto del modelo de datos de Git rinde dividendos. Cada comando opera sobre algún subconjunto de las piezas (objetos, index, refs, árbol de trabajo), y saber cuáles toca ayuda a predecir resultados y a recuperarse de errores.
Cuándo usar
Most developers reach for git show <rev>:<path> or git ls-files instead. ls-tree shines in scripts that need exact mode/type/SHA information, or when traversing a tree of any commit (not just HEAD's index).
Opciones comunes
| Opción | Descripción |
|---|---|
-r | Recurse into subtrees. |
-d | Show only directories (trees). |
-l | Include the size of blob entries. |
--name-only | Show only file names. |
-z | NUL-terminate output for safe parsing. |
--full-tree | Don't restrict by current directory. |
Ejemplos
git ls-tree HEAD
# Top-level entries of HEAD's tree
git ls-tree -r HEAD --name-only
# All file paths at HEAD
git ls-tree -r -l v1.0 src/
# Sizes and SHAs for every file under src/ at v1.0
git ls-tree HEAD -- 'docs/*.md'
# Just markdown files in docs/Errores comunes
Mixing up working-directory-relative versus repo-root-relative paths. Use --full-tree for unambiguous root-relative output. Without -r, only one level is shown — easy to miss nested files.
Comandos relacionados
git ls-files, git show, git cat-file, git diff-tree