Introducción

El index, también llamado área de staging o caché, es una de las características distintivas de Git. Es un archivo binario en .git/index que contiene el árbol que pretendes commitear a continuación. Entender el index elimina la mayor parte del misterio de la salida de git status.

Por qué existe

El index te permite componer un commit deliberadamente en lugar de volcar todos los cambios a la vez. Puedes editar diez archivos pero commitear solo los tres que arreglan un bug, dejando el resto staged para un commit posterior. Este desacoplamiento permite un historial limpio y atómico.

Inspeccionando el index

Dos comandos comparan las tres áreas:

git diff             # árbol de trabajo vs index
git diff --staged    # index vs HEAD
git diff HEAD        # árbol de trabajo vs HEAD

El comando de plumbing git ls-files --stage muestra el contenido crudo del index, incluidos los hashes SHA-1:

git ls-files --stage

Stageando cambios

git add file.txt          # añadir o actualizar
git add .                 # añadir todo desde cwd hacia abajo
git add -u                # actualizar solo archivos rastreados
git add -p                # interactivo, hunk por hunk
git add -N new.txt        # intent-to-add (rastrear vacío)

Quitando del staging

Si stageaste algo por error, sácalo sin perder la edición:

# Moderno (Git 2.23+)
git restore --staged file.txt

# Sintaxis antigua, aún funciona
git reset HEAD file.txt

El index en conflictos

Durante un conflicto de merge, el index gana tres entradas por ruta conflictiva: el stage 1 es el ancestro común, el stage 2 es "ours", el stage 3 es "theirs". git ls-files -u los muestra:

git ls-files -u

Resolver el conflicto significa escribir una versión final y hacerle git add, colapsando de vuelta a una sola entrada de stage 0.

El formato del archivo index

El index es un formato binario documentado en el código fuente de Git en Documentation/gitformat-index.txt. Comienza con una cabecera de 12 bytes (firma DIRC, versión, conteo de entradas) seguida de entradas ordenadas. Varias extensiones opcionales añaden caché: TREE cachea hashes de subárboles para un write-tree rápido, y UNTR cachea listas de archivos no rastreados para un git status rápido. Git moderno también soporta un sparse index que omite entradas fuera del cono que tienes checkeado:

git sparse-checkout init --cone
git config core.sparseCheckoutCone true
git update-index --test-untracked-cache

Errores comunes

Creer que git add es definitivo. No lo es: puedes stagear, editar de nuevo y stagear otra vez. El index es solo el borrador del próximo commit. Otra confusión clásica: editar un archivo staged, luego commitear, y quedarse perplejo de que las nuevas ediciones no estén incluidas. git add captura una instantánea en el momento que lo ejecutas; las ediciones posteriores viven solo en el árbol de trabajo. Ejecuta git diff (sin flags) para ver lo que está staged-pero-luego-modificado. Por último, nunca elimines .git/index manualmente; recompila con git read-tree HEAD si llega a corromperse.