Git es una herramienta enormemente configurable: nombre y correo del autor, editor de texto, comportamiento al integrar cambios, colores de la salida, atajos, credenciales y varios cientos de opciones más. Todo eso se gestiona con un único comando, git config, y se almacena en ficheros de texto plano con un formato sencillo.

Esta lección trata el mecanismo: dónde vive la configuración, qué niveles existen, quién gana cuando dos niveles dicen cosas distintas, cómo leer, escribir y borrar valores, y cómo mantener perfiles separados para el trabajo y los proyectos personales. Deliberadamente no vamos a listar todavía qué valores conviene fijar la primera vez: eso es el contenido de la siguiente lección, Configuración Inicial. Aquí aprendemos a manejar el mando; en la siguiente, qué botones pulsar.

Ana necesita esto ahora mismo: su portátil es el mismo que usa para el trabajo en su empresa y para gestor-tareas, y quiere que cada proyecto lleve el correo adecuado sin tener que acordarse cada vez.

1. Qué es git config
2. Los tres niveles de configuración
3. Precedencia: quién gana
4. Leer valores
5. Escribir valores
6. Borrar valores
7. El fichero .gitconfig por dentro
8. Edición directa con --edit
9. Configuración condicional con includeIf
10. Casos especiales: valores múltiples y tipos

git config es el comando que lee y escribe la configuración de Git. Su forma básica es:

Un ejemplo concreto, sin entrar aún en qué significa el valor:

Desglose de cada parte:

• git config → el comando.
• --global → el nivel: en qué fichero se escribe. Si se omite, se usa el nivel local.
• core.editor → la clave, formada por una sección (core) y un nombre (editor), separados por un punto.
• "nano" → el valor. Se entrecomilla siempre que contenga espacios o caracteres especiales.

Es importante entender que git config no valida las claves. Si escribes core.editorr con dos erres, Git lo aceptará sin protestar y la opción simplemente no tendrá ningún efecto. Es la causa número uno de configuraciones que "no funcionan".

Nota sobre versiones. Desde Git 2.46 existe una sintaxis alternativa más explícita: git config get, git config set, git config unset y git config list. Es equivalente a la clásica y algo más legible. En este curso usaremos la sintaxis clásica con opciones (--get, --unset, --list) porque funciona en todas las versiones y es la que encontrarás en la documentación existente.

Git lee la configuración de varios ficheros, organizados en niveles de alcance creciente a decreciente. Los tres principales son:

Existen además dos niveles menos habituales que conviene conocer:

El nivel de comando es muy útil para pruebas puntuales, porque no deja rastro:

Fíjate en que -c va antes del subcomando, no después: es una opción de git, no de commit.

La regla general: empieza siempre por --global. Reserva --local para las excepciones reales de un proyecto concreto.

Cuando varios niveles definen la misma clave, gana el más específico. El orden, de menor a mayor prioridad:

Un ejemplo concreto con el portátil de Ana:

Resultado: dentro del repositorio gestor-tareas, Git usará [email protected]. En cualquier otro repositorio del portátil de Ana, [email protected].

Esta es exactamente la herramienta que Ana necesitaba: la configuración global cubre el caso mayoritario (su trabajo) y la local resuelve la excepción (su proyecto personal). En el apartado 9 veremos cómo automatizarlo para no tener que acordarse en cada repositorio nuevo.

Devuelve el valor que Git usaría ahora mismo, ya resuelta la precedencia. También funciona sin --get, que es la forma abreviada más habitual:

Si la clave no está definida, el comando no imprime nada y devuelve un código de salida distinto de cero. Para dar un valor por defecto cuando no existe:

Combinando --get con el nivel se consulta un fichero específico, ignorando los demás:

Esto es fundamental para depurar: si el valor efectivo no es el que esperabas, consultar nivel por nivel revela de dónde sale.

Imprime todas las claves activas, una por línea, en formato clave=valor:

Y ahora el comando más útil de toda la lección:

Añade delante de cada línea el fichero del que procede:

Observa la última aparición de user.email: cuando una clave aparece varias veces, la última línea es la que gana, porque los ficheros se procesan de menos a más específico. Aquí el valor efectivo es [email protected].

Una variante aún más informativa:

Añade también el nombre del nivel (system, global, local), lo que evita tener que deducirlo a partir de la ruta.

Este último es muy práctico cuando buscas algo y no recuerdas el nombre exacto:

La forma básica ya la conocemos:

Puntos a tener en cuenta:

• Si la clave existe, se sobrescribe. No hay confirmación ni aviso.
• Las comillas son necesarias cuando el valor contiene espacios. git config --global user.name Ana Ferrer fallaría, porque Git interpretaría Ferrer como un argumento extra.
• Las claves no distinguen mayúsculas en la sección y el nombre (init.defaultBranch e init.defaultbranch son la misma clave), pero los valores sí.
• Si no indicas nivel, se usa --local, lo que requiere estar dentro de un repositorio. Fuera de uno, Git dará el error fatal: not in a git directory.

Este último punto merece un ejemplo, porque es un tropiezo clásico:

Acostúmbrate a indicar siempre el nivel de forma explícita. Ahorra confusiones difíciles de diagnosticar.

Requiere privilegios de administrador, porque el fichero está fuera de tu carpeta personal:

En Windows hay que abrir Git Bash o PowerShell como administrador.

Para eliminar una clave se usa --unset:

Si la clave aparece varias veces en el mismo fichero (algo posible para ciertas claves, como veremos en el apartado 10), --unset fallará con el mensaje warning: <clave> has multiple values. En ese caso se usa --unset-all:

Para eliminar una sección entera:

Un matiz importante: borrar una clave de un nivel no la deja "sin valor", sino que deja que gane el nivel inferior. Si Ana borra user.email del .git/config de gestor-tareas, el correo pasará a ser el de su ~/.gitconfig, no ninguno.

Y una advertencia: --unset sin nivel explícito opera sobre el fichero local. Si querías limpiar el global y olvidas --global, borrarás algo que no era.

Todos los ficheros de configuración de Git usan el mismo formato: INI, texto plano legible y editable a mano. Este podría ser el ~/.gitconfig de Ana:

Reglas del formato:

• Las secciones van entre corchetes: [user], [core]. Corresponden a la parte anterior al punto en la clave.
• Las claves se escriben con nombre = valor, indentadas con un tabulador por convención (Git escribe tabulador; los espacios también funcionan).
• Los comentarios empiezan por # o ;.
• Los valores con espacios no necesitan comillas dentro del fichero, salvo que quieras conservar espacios al principio o al final.

La correspondencia entre el comando y el fichero es directa:

Algunas secciones admiten un nivel más, entre comillas. Se ven sobre todo en remotos y ramas:

En la línea de comandos, la subsección va en medio: remote.origin.url, branch.main.remote. Estas entradas las escribe Git automáticamente al añadir un remoto o al configurar el seguimiento de una rama, cosas del módulo 4. Rara vez las escribirás a mano, pero saber leerlas ayuda mucho a diagnosticar problemas.

Importante: a diferencia de las claves, las subsecciones sí distinguen mayúsculas. [remote "Origin"] y [remote "origin"] son dos remotos distintos.

Para cambios de varias líneas, editar el fichero directamente es mucho más cómodo que encadenar comandos:

Abre ~/.gitconfig en el editor configurado en core.editor (o en el que indique la variable de entorno EDITOR). Al guardar y cerrar, los cambios son inmediatos: Git lee la configuración en cada ejecución, no la cachea.

Las tres variantes:

También puedes abrir el fichero con cualquier editor, sin pasar por Git:

Es igual de válido. La ventaja de --edit es que no necesitas recordar la ruta, que varía entre sistemas.

Precaución: si escribes un fichero de configuración con un error de sintaxis (un corchete sin cerrar, por ejemplo), Git protestará en todos los comandos que ejecutes a partir de ese momento:

La solución es volver a abrir el fichero y corregir la línea indicada. Es reversible y no daña ningún repositorio, pero resulta desconcertante la primera vez.

Llegamos a la funcionalidad más elegante del sistema de configuración, y la que resuelve el problema de Ana de forma definitiva.

Ana usa el mismo portátil para dos contextos:

• Proyectos de su empresa, que deben firmarse con [email protected].
• Proyectos personales como gestor-tareas, que deben ir con [email protected].

Puede resolverlo con configuración local repositorio por repositorio, pero eso significa acordarse cada vez que clona o crea uno. Tarde o temprano se olvidará y hará confirmaciones con el correo equivocado, algo que solo se arregla reescribiendo el historial.

Git permite incluir otro fichero de configuración solo si se cumple una condición. La condición más útil es la ruta del repositorio.

Ana organiza sus carpetas así:

Y edita su ~/.gitconfig:

Y crea el fichero ~/.gitconfig-personal:

Cómo funciona, paso a paso:

1. Git lee ~/.gitconfig de arriba abajo y establece user.email = [email protected].
2. Al llegar a includeIf, comprueba si el repositorio actual está dentro de ~/personal/.
3. Si lo está, lee ~/.gitconfig-personal en ese punto, y su user.email sobrescribe el anterior.
4. Si no lo está, la línea se ignora y el correo de empresa se mantiene.

Resultado: Ana nunca más tiene que acordarse. Basta con guardar cada proyecto en la carpeta correcta.

Comprobación:

Reglas de la ruta en gitdir:

• Debe terminar en / para que se aplique a todo lo que hay dentro, recursivamente. Sin la barra final solo coincidiría con esa carpeta exacta, y como Git compara contra la ruta del directorio .git, prácticamente nunca funcionaría como esperas. Es el error más frecuente al usar includeIf.
• Admite ~ para la carpeta personal.
• Admite comodines: gitdir:~/clientes/*/ coincide con cualquier subcarpeta de primer nivel.

La última condición, hasconfig:remote.*.url, es especialmente potente porque no depende de cómo organices las carpetas:

Así, aunque Ana clone un repositorio de la empresa en el escritorio por prisa, el correo correcto se aplicará igualmente.

Existe también la versión sin condición, útil para partir una configuración larga en piezas reutilizables:

Un patrón habitual en equipos: mantener un fichero de alias y colores compartido en un repositorio, y que cada persona lo incluya desde su ~/.gitconfig sin renunciar a su identidad propia.

La mayoría de claves tienen un solo valor, pero algunas admiten varios. Para añadir sin sobrescribir se usa --add:

En el fichero quedan dos líneas en la misma sección:

Para leerlas todas hace falta --get-all, porque --get devolvería solo la última:

Git interpreta los valores según el tipo que espera la clave. Puedes forzar la interpretación al leer:

Los booleanos son flexibles al escribir. Estas seis líneas son equivalentes:

Y una clave booleana escrita sin valor se interpreta como true:

Es válido, aunque poco legible. Es mejor escribir el valor de forma explícita.

• Olvidar --global y escribir en el repositorio sin querer. Es el error más frecuente. Sin nivel explícito, git config escribe en .git/config, así que tu preferencia se aplica a un solo proyecto y te preguntarás por qué no funciona en los demás. Acostúmbrate a poner el nivel siempre.
• Escribir mal el nombre de una clave. Git no valida nada: core.editorr o pull.rebasse se guardan sin protesta y no hacen nada. Si una opción no surte efecto, verifícala con git config --get <clave> y compárala con la documentación (git help config).
• No entrecomillar valores con espacios. git config --global user.name Ana Ferrer da error o guarda solo Ana. Usa comillas siempre que haya espacios.
• Olvidar la barra final en includeIf "gitdir:...". Sin la / final, la condición casi nunca se cumple y el fichero incluido se ignora en silencio, sin ningún aviso. Es un fallo especialmente difícil de detectar.
• Editar .git/config con un error de sintaxis. Deja Git inservible en ese repositorio hasta que se corrige la línea. No es grave ni destructivo, pero asusta. El mensaje indica el fichero y la línea exactos.
• Confundir los niveles al diagnosticar. Cuando un valor no es el que esperas, no adivines: ejecuta git config --list --show-origin --show-scope y localiza de qué fichero sale.
• Consejo: guarda tu ~/.gitconfig en un repositorio propio. Es un fichero de texto pequeño que representa horas de ajustes. Muchos profesionales lo mantienen versionado junto a sus otros ficheros de configuración personal.
• Consejo: usa git config --list --show-origin en cada máquina nueva. Es lo primero que conviene mirar al empezar en un equipo desconocido, y también al depurar comportamientos raros en un ordenador de empresa, donde el nivel de sistema puede traer sorpresas.

En el portátil de Bruno, los ficheros de configuración contienen esto:

/etc/gitconfig:

~/.gitconfig:

~/personal/gestor-tareas/.git/config:

Responde, estando dentro del repositorio gestor-tareas:

1. ¿Qué valor tiene user.email?
2. ¿Y user.name?
3. ¿Y core.editor?
4. ¿Y core.autocrlf?
5. ¿Qué comando ejecutarías para averiguar de qué fichero sale cada uno sin abrirlos?
6. Si Bruno ejecuta git config --unset user.email dentro de gestor-tareas, ¿cuál será el nuevo valor efectivo?

Carla trabaja con tres contextos en el mismo portátil:

• Proyectos de su empresa, en ~/trabajo/, con el correo [email protected].
• Proyectos de un cliente externo, en ~/clientes/acme/, con el correo [email protected].
• Proyectos personales, en ~/codigo/, con el correo [email protected].

Su nombre es siempre "Carla Vidal" y su editor siempre nano.

Escribe el contenido completo de su ~/.gitconfig y de los ficheros auxiliares que necesite. Después indica qué comando usaría para comprobar, desde dentro de ~/clientes/acme/panel-ventas, que el correo aplicado es el correcto.

Ana se queja de que ha configurado su editor favorito pero Git sigue abriendo Vim cada vez que le pide escribir un mensaje. Esto es lo que ejecutó:

1. Identifica dos errores distintos en ese comando.
2. Escribe el comando correcto.
3. Escribe los comandos para limpiar la clave equivocada que quedó guardada.
4. Escribe el comando que le habría permitido detectar el problema por sí misma.

Solución al Ejercicio 1

1. user.email = [email protected]. El nivel local es el más específico de los tres presentes y gana sobre el global y el de sistema.

2. user.name = Bruno Salas. Solo está definido en el global; nada lo sobrescribe.

3. core.editor = vim. Solo está en el global.

4. core.autocrlf = input. Solo está en el nivel de sistema, y ningún nivel superior lo redefine, así que se aplica.

5. El comando de diagnóstico:

Mostrará cada clave precedida de su nivel y de la ruta del fichero. Para una sola clave:

6. El nuevo valor efectivo sería [email protected]. Borrar la clave del nivel local no la deja vacía: simplemente deja que gane el siguiente nivel, que es el global. El del sistema quedaría de nuevo tapado por el global.

Solución al Ejercicio 2

~/.gitconfig:

~/.gitconfig-empresa:

~/.gitconfig-acme:

Decisiones que conviene justificar:

• El correo personal va en el fichero principal como valor por defecto, porque cualquier repositorio fuera de las dos carpetas específicas debe quedar con el personal, que es la opción menos comprometida en caso de olvido.
• El nombre y el editor van una sola vez en el fichero principal, ya que no cambian entre contextos.
• Todas las rutas terminan en /, condición imprescindible para que la coincidencia sea recursiva.
• Los includeIf van al final del fichero: se procesan en orden, y lo incluido después sobrescribe lo anterior.

Comprobación desde ~/clientes/acme/panel-ventas:

Solución al Ejercicio 3

1. Los dos errores:

   • La clave está mal escrita: core.editorr con dos erres. Git la acepta sin validar y la guarda como una clave sin significado, así que no tiene ningún efecto.
   • Falta el nivel --global: al omitirlo, el valor se habría escrito solo en .git/config de gestor-tareas, es decir, únicamente para ese repositorio. Incluso con la clave bien escrita, el editor seguiría siendo Vim en todos los demás proyectos de Ana.

2. Comando correcto:

3. Limpiar la clave equivocada (está en el nivel local, porque así se escribió):

4. El comando de diagnóstico que habría revelado el problema:

No habría devuelto nada, señal de que la clave correcta no estaba definida en ningún nivel. Y con:

habría visto la línea file:.git/config core.editorr=nano, donde saltan a la vista tanto la errata como el nivel equivocado.

Ya dominas el mecanismo de configuración de Git. Todo pasa por git config, que lee y escribe ficheros de texto en formato INI repartidos en tres niveles: sistema (toda la máquina), global (tu usuario) y local (un repositorio), a los que se suman el nivel de worktree y la opción -c para una sola ejecución. Cuando varios niveles definen la misma clave, gana el más específico, y el comando git config --list --show-origin --show-scope es la herramienta definitiva para saber de dónde sale cada valor.

Has visto cómo leer (--get, --get-all, --list, --get-regexp), escribir (con y sin --add), borrar (--unset, --unset-all, --remove-section) y editar los ficheros directamente con --edit. Y has conocido includeIf, la pieza que permite mantener perfiles separados —personal, empresa, cliente— sin tener que acordarse de nada en cada repositorio nuevo, gracias a condiciones sobre la ruta (gitdir:), la rama (onbranch:) o la URL del remoto (hasconfig:).

Sabes manejar el mando; falta decidir qué botones pulsar. En la última lección del módulo, Configuración Inicial, aplicaremos todo esto al portátil de Ana para dejarlo listo: su identidad, el nombre de la rama por defecto, el editor, el tratamiento de los finales de línea, el comportamiento al integrar cambios, el almacén de credenciales y el color de la salida. Al terminar, Ana tendrá por fin todo preparado para crear el repositorio de gestor-tareas en el módulo 2.