.gitattributes

Qué hace .gitattributes

Un archivo .gitattributes le indica a Git cómo tratar archivos específicos según su ruta. Mientras que .gitignore decide si Git rastrea un archivo, .gitattributes decide cómo Git maneja los archivos que sí rastrea: cómo normalizar los finales de línea, cómo hacer diff de ellos, cómo fusionarlos y qué hacer al momento de exportar. Reside en tu repositorio y se confirma (commit), de modo que todos los colaboradores obtienen el mismo comportamiento, independientemente de su configuración personal de Git.

Esta página cubre el formato del archivo, los atributos más comunes (normalización de finales de línea, marcar binarios, controladores personalizados de diff/merge y export-ignore), dónde busca Git el archivo y cómo se resuelven las reglas en conflicto.

Formato del archivo

Cada línea empareja un patrón de archivo con uno o más atributos:

# pattern        attributes
*.txt            text
*.png            binary
*.sh             text eol=lf

Los patrones siguen las mismas reglas glob que .gitignore: * coincide con cualquier cosa excepto /, ** coincide entre directorios, un / inicial ancla al directorio del archivo .gitattributes, y las líneas que comienzan con # son comentarios. Cada atributo tras el patrón adopta una de cuatro formas:

• Activar — text enciende el atributo.
• Desactivar — -text lo apaga (el guion inicial).
• Valor — eol=lf establece un valor específico.
• Sin especificar — !text borra cualquier configuración anterior, dejando el valor predeterminado de Git.

Dónde busca Git el archivo

La mayoría de los proyectos mantiene un único .gitattributes en la raíz del repositorio. Sin embargo, Git comprueba varias ubicaciones, y una regla en un directorio más profundo anula a otra más arriba:

• Un .gitattributes en cualquier directorio se aplica a los archivos en ese directorio y los que están por debajo.
• $GIT_DIR/info/attributes contiene reglas que no se confirman (locales a tu clon).
• core.attributesFile (normalmente ~/.config/git/attributes) establece valores predeterminados por usuario.

Cuando dos reglas podrían coincidir con el mismo archivo, gana la ruta más específica; y dentro de un mismo archivo, gana la última línea coincidente. Puedes inspeccionar el resultado para cualquier ruta con git check-attr:

git check-attr -a README.md
# README.md: text: auto

Normalización de finales de línea

El uso más común de .gitattributes es acabar con el caos de "cada línea modificada" que ocurre cuando desarrolladores de Windows y Unix comparten un repositorio. Marcar archivos como text permite a Git normalizar los finales de línea a LF en el repositorio y convertirlos al hacer checkout:

* text=auto
*.sh text eol=lf
*.bat text eol=crlf

text=auto deja que Git decida qué archivos son texto y los almacena con LF en el repositorio; los ajustes explícitos de eol fuerzan un final específico al hacer checkout para los archivos que lo requieran (los scripts de shell deben quedarse en LF, los archivos batch de Windows deben quedarse en CRLF). Como las reglas están confirmadas, esto es más fiable que depender del ajuste core.autocrlf de cada desarrollador, que varía de máquina en máquina.

Si añades * text=auto a un repositorio existente, los archivos ya confirmados con CRLF no se renormalizarán automáticamente. Ejecuta una limpieza puntual para que el siguiente commit los corrija:

git add --renormalize .
git commit -m "Normalize line endings"

Marcar archivos como binarios

Indicarle a Git que un archivo es binario evita que intente mostrar un diff textual o fusionarlo línea por línea:

*.pdf binary
*.png binary

El atributo binary es una macro incorporada que se expande a -text -diff, lo cual desactiva la conversión de finales de línea y el diff textual. Esto evita que Git corrompa un archivo con reescrituras de finales de línea y evita que git diff vuelque bytes ilegibles en el terminal.

Para binarios grandes como vídeos, conjuntos de datos o archivos de diseño, marcarlos como binarios no es suficiente: igualmente engordan el historial del repositorio. Almacénalos con Git LFS en su lugar, que también se configura mediante .gitattributes.

Comportamiento personalizado de diff y merge

.gitattributes puede enrutar ciertos archivos a través de controladores personalizados de diff o merge, pero un controlador personalizado debe definirse primero en tu configuración de Git — el atributo solo lo referencia por nombre.

Un caso habitual es un archivo de bloqueo generado: durante un conflicto de fusión quieres conservar íntegramente la versión de tu rama en lugar de fusionar línea por línea. Registra un controlador ours una vez y luego apunta la ruta hacia él:

git config merge.ours.driver true

# .gitattributes
package-lock.json merge=ours

Establecer driver a true significa "la fusión siempre tiene éxito y el resultado es la versión de la rama actual." (Este atributo merge=ours por archivo es independiente de la estrategia de fusión -s ours, que se aplica a toda una fusión.)

Un controlador de diff personalizado funciona de la misma manera y es útil para formatos no textuales. Git también incluye controladores de diff integrados que producen encabezados de fragmento significativos para lenguajes comunes, de modo que un diff muestra qué función cambió:

*.c diff=cpp
*.py diff=python

Consulta git diff para ver cómo estos controladores dan forma a la salida.

Export-ignore

Cuando alguien descarga un archivo de versión mediante git archive, a menudo querrás omitir archivos de desarrollo. El atributo export-ignore hace exactamente eso:

/tests       export-ignore
/.github     export-ignore
.gitattributes export-ignore

Esto mantiene fuera del tarball que genera git archive los conjuntos de pruebas, la configuración de CI y los archivos de editor, de modo que los consumidores descarguen solo lo que necesitan. Un atributo relacionado, export-subst, expande marcadores de posición como $Format:%H$ dentro de los archivos exportados para que un archivo pueda registrar el commit desde el que se construyó.

Atributos comunes

Cuándo usarlo

Recurre a .gitattributes siempre que el comportamiento de Git por archivo deba ser el mismo para todos en el equipo en lugar de dejarlo a la configuración local. Los beneficios cotidianos son normalizar los finales de línea en un equipo mixto Windows/Unix, silenciar diffs inútiles en binarios y recortar los archivos de versión. Los beneficios avanzados — controladores personalizados de merge/diff y Git LFS — resuelven puntos de dolor específicos cuando un proyecto los encuentra. Empieza con * text=auto y añade reglas conforme surjan problemas concretos.

Práctica