Introducción

El index es un archivo binario en .git/index que refleja un objeto tree: una lista ordenada de paths con mode, hash e información stat. Es el área de staging para el próximo commit y un caché que permite a Git saltarse el rehasheo de archivos sin cambios.

Inspeccionándolo

git ls-files --stage
# 100644 a1b2c3...  0  README.md
# 100644 e4f5g6...  0  src/main.c

El stage 0 significa "sin conflicto". Durante un merge, los paths conflictivos obtienen los stages 1 (base), 2 (ours), 3 (theirs).

Qué te aporta el caché de stat

El index también almacena ctime, mtime, size e inode para cada path. git status compara estos con el árbol de trabajo antes de hashear; si coinciden, se asume que el archivo no ha cambiado. Por eso git status es rápido en árboles enormes.

git update-index --refresh
git update-index --really-refresh

Modificando el index

git add file.txt                  # stagear desde árbol de trabajo
git rm --cached file.txt          # quitar del index, mantener en disco
git restore --staged file.txt     # quitar del staging
git update-index --chmod=+x bin/run   # cambiar bit de ejecutable

Assume unchanged y skip-worktree

Dos flags le dicen a Git que ignore ciertos paths:

git update-index --assume-unchanged config.local
git update-index --skip-worktree config.local

• assume-unchanged: una pista de rendimiento; Git aún puede notar cambios.
• skip-worktree: más fuerte; pensado para archivos que el usuario mantiene modificados localmente.

Ninguno reemplaza a .gitignore; ambos son hacks locales del workspace, no compartibles.

Leyendo y escribiendo trees

git write-tree                # snapshot del index como objeto tree
git read-tree HEAD            # resetear index a un tree
git read-tree --reset -u HEAD # también actualizar árbol de trabajo

Estos comandos plumbing son la base de commit, checkout y merge.

Conflictos en el index

Durante un merge, el index se vuelve la fuente de verdad para lo que está sin resolver:

git ls-files -u
# 100644 a1...  1  src/main.c
# 100644 b2...  2  src/main.c
# 100644 c3...  3  src/main.c

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

Sparse checkout y el sparse index

Sparse checkout popula el árbol de trabajo con solo un subconjunto del tree del repositorio, útil en monorepos. Con cone mode más el sparse index, el index mismo se reduce al cono activo, haciendo las operaciones en repos enormes rápidas:

git sparse-checkout init --cone
git sparse-checkout set src/myteam docs
git sparse-checkout list
git sparse-checkout disable

El sparse index marca las entradas omitidas con un bit especial para que Git pueda expandirlas perezosamente solo cuando los comandos lo necesiten. Esta característica requiere Git 2.32 o más reciente para funcionalidad completa.

Errores comunes

Creer que el index es solo "lo que está staged". También es un caché y un rastreador de conflictos. Eliminar .git/index cuando estás atascado; reconstruye con git read-tree HEAD, pero pierdes cualquier staging no commiteado. Usar --assume-unchanged como sustituto de .gitignore; el próximo clon no lo respetará. Finalmente, esperar que el index rastree directorios vacíos; no puede. Usa un archivo placeholder (.gitkeep) si necesitas commitear una carpeta vacía.