Introducción

Un archivo .gitignore lista patrones que Git debe tratar como no rastreados y nunca ofrecer para añadir. Mantiene fuera de tu repositorio los artefactos de build, secretos, metadatos del SO y archivos temporales del editor.

Sintaxis de patrones

• name: coincide con archivos o directorios llamados name a cualquier profundidad.
• /name: coincide solo en la raíz del repositorio.
• name/: coincide solo con directorios.
• *.log: glob; coincide con cualquier archivo .log.
• **/build: coincide con build a cualquier profundidad.
• !important.log: re-incluye una ruta previamente ignorada.
• # al inicio de una línea es un comentario.

Un ejemplo realista

# .gitignore
# Salida de build
/dist/
/build/
*.o
*.pyc

# Dependencias
/node_modules/
/vendor/

# Editores
.idea/
.vscode/
*.swp

# SO
.DS_Store
Thumbs.db

# Secretos
.env
*.pem

Múltiples archivos .gitignore

Puedes colocar un .gitignore en cualquier nivel. Los patrones son relativos al directorio del archivo, y los archivos más profundos sobrescriben a los más superficiales. También hay un archivo de ignore global para tus preferencias personales:

git config --global core.excludesFile ~/.gitignore_global

Úsalo para archivos de swap del editor y basura del SO, no para rutas específicas del proyecto.

Rastreando archivos ya rastreados

Añadir una ruta a .gitignore no la elimina del repositorio. Deja de rastrear un archivo manteniéndolo en disco:

git rm --cached secrets.env
git commit -m "Stop tracking secrets.env"

Depurando ignores

¿Por qué Git está ignorando (o no) una ruta? Pregunta:

git check-ignore -v path/to/file

La salida nombra el archivo y la línea que coincidió.

Orden de evaluación

Git evalúa las reglas de ignore desde varias fuentes, en este orden: argumentos de la línea de comandos, luego archivos .gitignore por directorio (los más profundos primero), luego $GIT_DIR/info/exclude y finalmente el global core.excludesFile. Las reglas posteriores (más específicas) sobrescriben a las anteriores, y una negación (!pattern) solo re-incluye una ruta si su directorio padre no está él mismo excluido. Esta última regla atrapa a muchos usuarios:

# Mal: no se puede des-ignorar un archivo en un directorio ignorado
/build/
!/build/keep.log

# Bien: ignorar contenidos pero conservar el directorio
/build/*
!/build/keep.log

Excludes por repo y globales

Dos mecanismos extra de ignore complementan a .gitignore. El archivo no rastreado por repo .git/info/exclude aplica solo a tu clon (bueno para archivos de IDE que no quieres commitear a .gitignore para todo el equipo). El global core.excludesFile aplica a todos tus repos:

echo ".idea/" >> .git/info/exclude
git config --global core.excludesFile ~/.gitignore_global
echo ".DS_Store" >> ~/.gitignore_global

Usa estos para preferencias personales; reserva el .gitignore commiteado para reglas a nivel de equipo.

Errores comunes

Añadir secrets.env a .gitignore después de que ya se haya commiteado y asumir que el secreto está fuera. Sigue estando en el historial; rota el secreto y considera usar git filter-repo para limpiarlo. Otra trampa: ignorar un directorio con build cuando querías decir /build, suprimiendo accidentalmente un archivo llamado build en lo profundo del árbol. Finalmente, commitear el propio .gitignore es esencial; sin él, cada colaborador debe inventar sus propias reglas de ignore. .gitignore pertenece dentro del repositorio, no fuera.