.gitignore

Descripción general

En una copia de trabajo, Git ve cada archivo en uno de tres estados: rastreado (ya en el repositorio o en el área de preparación), no rastreado (nuevo y aún no preparado), o ignorado (excluido deliberadamente). Este capítulo explica cómo hacer que Git ignore archivos mediante un archivo .gitignore: la sintaxis de patrones, dónde pueden residir las reglas de ignorado (por directorio, por repositorio y de forma global), y cómo manejar los casos complicados: ignorar un archivo que ya está confirmado, forzar la confirmación de un archivo ignorado, guardar archivos ignorados en el stash y depurar por qué un archivo está ignorado.

Los archivos ignorados son aquellos que le has indicado a Git que omita. Nunca se preparan, nunca se confirman y nunca aparecen en git status como ruido sin rastrear. Los candidatos típicos son archivos que se generan a partir del código fuente en lugar de ser escritos a mano:

• Archivos creados en tiempo de ejecución: registros, archivos de bloqueo (*.log, *.lock).
• Metadatos del sistema operativo y del IDE: .DS_Store, Thumbs.db, .idea/, .vscode/.
• Salida compilada y dependencias: *.o, *.class, node_modules/, dist/.
• Secretos y configuración local: .env, archivos de credenciales.

La regla general es: si un archivo puede regenerarse desde el código fuente del repositorio, o es específico de tu máquina, ignóralo.

Patrones de Git ignore

Las reglas de ignorado residen en un archivo de texto plano llamado .gitignore. No existe un comando git ignore: debes crear y editar el archivo manualmente y confirmarlo como cualquier otro archivo. Cada línea no vacía es un patrón que se compara con las rutas de los archivos; un archivo se ignora cuando coincide con un patrón.

Algunas reglas aplican al formato del archivo en sí:

• Una línea en blanco no coincide con nada y se usa únicamente para mejorar la legibilidad.
• Una línea que comienza con # es un comentario. Para hacer coincidir un nombre de archivo que empiece literalmente por #, escápalo como \#.
• Los espacios al final de la línea se ignoran a menos que se escapen con una barra invertida (\).
• Los patrones se comparan en relación con la ubicación del archivo .gitignore.

Los patrones en sí se construyen a partir de estos símbolos:

Aquí se muestra un pequeño .gitignore que ilustra cómo se comporta debug?.log (el ? coincide con exactamente un carácter). Ignora debug0.log y debug1.log, pero no debug10.log, porque 10 son dos caracteres:

Patrones de .gitignore

debug?.log

# matches debug0.log, debug1.log, debug9.log
# does NOT match debug10.log (two characters)

Archivos .gitignore compartidos en el repositorio

Puedes definir varios archivos .gitignore en diferentes directorios del repositorio. Cada uno de los patrones se compara en relación con el directorio que contiene ese archivo. Sin embargo, la forma más sencilla es definir un único archivo .gitignore en la raíz del repositorio.

Como el archivo .gitignore se confirma en el repositorio, se versiona como cualquier otro archivo y se comparte con tu equipo cuando haces push. Solo debes incluir patrones en .gitignore que sean útiles para los demás usuarios del repositorio.

Reglas personales de Git ignore

Los patrones de ignorado personales para un repositorio específico pueden colocarse en el archivo especial .git/info/exclude. Su sintaxis es idéntica a la de .gitignore, pero como el directorio .git no forma parte del contenido del repositorio, estas reglas no están versionadas y no se comparten al hacer push o clone. Usa este archivo para copias de seguridad del editor, archivos temporales o cualquier cosa específica de tu flujo de trabajo personal que no deba imponerse al resto del equipo.

Reglas globales de Git ignore

Puedes definir la propiedad Git core.excludesFile para especificar patrones de ignorado globales de Git para todos los repositorios de tu sistema local. Este archivo lo creas tú mismo. Puedes colocar tu archivo global .gitignore en tu directorio de inicio para encontrarlo fácilmente. Una vez creado el archivo, configura su ubicación con el comando git config, así:

Reglas globales de gitignore

touch ~/.gitignore
git config --global core.excludesFile ~/.gitignore

Ignorar un archivo previamente confirmado

Añadir un patrón a .gitignore no hace que Git deje de rastrear un archivo que ya está confirmado: las reglas de ignorado solo se aplican a archivos no rastreados. Para dejar de rastrear dicho archivo, primero debes eliminarlo del índice de Git. Usa git rm con la opción --cached: esto prepara la eliminación del archivo del repositorio mientras mantiene la copia en tu disco como archivo ignorado. Luego confirma el cambio.

Archivos confirmados en .gitignore

echo debug.log >> .gitignore
git rm --cached debug.log
#rm 'debug.log'
git commit -m "Start ignoring debug.log"

Si también quieres eliminar el archivo de tu directorio de trabajo, omite --cached (git rm debug.log). Usa git status después para confirmar que el archivo ya no aparece como rastreado o no rastreado.

Confirmar un archivo ignorado

El archivo ignorado puede confirmarse en el repositorio combinando la opción -f (o --force) con git add. Sin embargo, elige esta opción cuando tengas un patrón general, como *.log, pero quieras confirmar un archivo específico:

Confirmar archivos ignorados

cat .gitignore
# *.log
git add -f debug.log
git commit -m "Force adding debug.log"

Si no, la forma más sencilla es definir una excepción a la regla general:

Confirmar archivos ignorados

echo '!debug.log' >> .gitignore

cat .gitignore
#*.log
#!debug.log

git add debug.log
git commit -m "Adding debug.log"

Guardar en stash un archivo ignorado

El comando git stash toma tus cambios sin confirmar (preparados y sin preparar), los guarda para más tarde y revierte tu copia de trabajo a un estado limpio. Por defecto, solo guarda los cambios en archivos rastreados: los archivos ignorados y no rastreados se dejan en su lugar. Dos opciones amplían ese alcance:

• git stash --include-untracked (o -u) también guarda los archivos no rastreados.
• git stash --all (o -a) guarda tanto los archivos no rastreados como los ignorados.

git stash --all

Depurar archivos .gitignore

Con patrones complejos, o reglas distribuidas en varios archivos .gitignore, puede ser difícil saber qué regla está ocultando un archivo. El comando git check-ignore con -v (o --verbose) informa sobre el patrón exacto responsable:

Verificar archivos ignorados con git check-ignore

git check-ignore -v debug.log
#.gitignore:3:*.log    debug.log

La salida tiene cuatro campos separados por dos puntos (y un espacio antes del nombre del archivo):

<file containing the pattern>:<line number of the pattern>:<pattern>    <file name>

Así, .gitignore:3:*.log debug.log significa: la regla *.log en la línea 3 de .gitignore es la que hace que debug.log sea ignorado. Si el comando no imprime nada, el archivo no está ignorado por ninguna regla.

Capítulos relacionados

• git rm — eliminar archivos del rastreo, clave para ignorar un archivo ya confirmado.
• git add — preparar archivos, incluyendo -f para forzar la adición de uno ignorado.
• git stash — guardar cambios; combinar con --all para incluir archivos ignorados.
• git config — configurar core.excludesFile para una lista de ignorados global.
• git clean — eliminar archivos no rastreados; combinar con -x para eliminar también los ignorados.

Práctica