.gitattributes: finales de línea, diff drivers, merge drivers y export-ignore

Qué es

.gitattributes asocia patrones de ruta con atributos, usando la misma sintaxis de patrones que .gitignore, y se versiona junto con el código. Los atributos más usados, según describe la documentación:

• text / text=auto / -text: indica si Git convierte los finales de línea al hacer check-in (a LF en el repositorio). Con text=auto, Git decide archivo por archivo si es texto.
• eol=lf / eol=crlf: el final de línea en el directorio de trabajo al hacer checkout; definir eol también activa text.
• binary: una macro integrada equivalente a -diff -merge -text.
• diff=<driver>: selecciona un diff driver configurado en [diff "<driver>"], por ejemplo xfuncname para elegir la línea del encabezado de hunk, o textconv para convertir un formato binario en texto y poder verlo.
• merge=<driver>: text (three-way merge normal), binary (conserva nuestra versión y deja el conflicto sin resolver), union (toma líneas de ambas versiones, sin garantizar el orden) o un driver personalizado definido en .git/config.
• export-ignore: la ruta se excluye de git archive; export-subst expande los marcadores $Format:...$ en los archivos exportados.

Por qué importa

Sin una política versionada, la configuración core.autocrlf de cada desarrollador decide el resultado, y los finales de línea mezclados convierten correcciones de una sola línea en diffs de archivos enteros. Los diff y merge drivers hacen que los archivos generados o estructurados sean revisables y reducen los falsos conflictos. export-ignore mantiene las pruebas y la configuración de CI fuera de los tarballs de las versiones publicadas.

Cómo aplicarlo

• Empieza con * text=auto y después fija las excepciones: *.sh text eol=lf, *.bat text eol=crlf, *.png binary.
• Tras añadir o cambiar reglas de finales de línea, ejecuta git add --renormalize . desde un árbol limpio y haz un commit solo con la normalización, como muestra el ejemplo de la documentación.
• Asigna merge=union a lock files o changelogs solo si el orden de las líneas realmente no importa; la documentación advierte de que hay que verificar el resultado.
• Activa los patrones de encabezado de hunk integrados que menciona la documentación (*.py diff=python, *.tex diff=tex) para que las revisiones muestren la función contenedora, y define un driver con xfuncname solo para lenguajes que no tengan uno.
• Marca tests/ export-ignore y .github/ export-ignore cuando git archive genere tus versiones del código fuente.

Trampas

Git consulta primero $GIT_DIR/info/attributes y después los archivos .gitattributes desde el directorio de la ruta hasta el nivel superior; un clon aplica las reglas nuevas solo cuando ya tiene el commit que las añade, y los archivos ya extraídos conservan sus finales de línea anteriores hasta que se renormalizan. Las macros como binary solo pueden definirse en archivos de atributos del nivel superior. La salida de textconv es unidireccional y no se puede aplicar como parche. Los drivers personalizados residen en la configuración de cada usuario, así que el atributo por sí solo no hace nada en una máquina que no tenga el driver.