En la lección anterior aprendimos a decidir con precisión qué entra en cada confirmación. Pero hay una pregunta previa que git status no responde: ¿qué he cambiado exactamente?

git status te dice qué ficheros han cambiado y en qué zona están. No te dice qué líneas. Y esa diferencia es enorme: confirmar sin haber leído tus propios cambios es la forma más común de meter en el historial un console.log de depuración, una contraseña de pruebas, un bloque de código comentado o un cambio que creías haber deshecho.

git diff es la herramienta que responde a esa pregunta. En esta lección veremos sus tres formas fundamentales —y por qué producen resultados distintos según qué zonas comparen—, aprenderemos a leer el formato unified diff línea a línea (un formato que aparece en Git, en las revisiones de código, en los parches y en media informática), y recorreremos las opciones que hacen legible una salida difícil.

Al terminar deberías haber adquirido un hábito: git diff --staged justo antes de cada git commit.

1. Las tres formas de git diff y qué compara cada una
2. git diff: directorio de trabajo contra área de preparación
3. git diff --staged: área de preparación contra el último commit
4. git diff HEAD: todo lo que ha cambiado
5. Leer el formato unified diff paso a paso
6. Comparar confirmaciones concretas
7. Limitar la comparación a ficheros o rutas
8. Opciones que hacen legible la salida
9. git difftool: comparar con una herramienta visual
10. El hábito de revisar antes de confirmar

Todo el aparente misterio de git diff se disuelve con una idea: siempre compara dos de las tres zonas, y la forma que uses determina cuáles.

En forma de tabla:

Dos consecuencias que conviene interiorizar desde el principio:

• git diff a secas no muestra los cambios preparados. Si preparas todo con git add -A y luego ejecutas git diff, la salida estará vacía. No es que no hayas cambiado nada: es que no hay diferencia entre tu disco y el área de preparación. Este es el desconcierto número uno con git diff.

• git diff HEAD es la suma de las otras dos. Preparado o no, si difiere del último commit, aparece.

• Ninguna de las tres muestra ficheros sin seguimiento. Un fichero nuevo que nunca has añadido no tiene "versión anterior" con la que compararlo, así que git diff lo ignora por completo. Para eso está git status.

Volvamos al repositorio de Ana. Acaba de retocar estilos.css y todavía no ha preparado nada:

En tres segundos sabe qué ha hecho: ha suavizado el color del borde y ha añadido el cursor de puntero. Ninguna sorpresa, ningún resto de depuración.

Ahora prepara el cambio y repite:

Exacto: el disco y el área de preparación coinciden, así que no hay nada que mostrar. Para ver ese cambio hay que preguntar por la otra comparación.

Esta es la forma más importante de todas, porque muestra literalmente lo que vas a confirmar:

--cached es un sinónimo exacto y más antiguo. --staged se añadió en Git 1.6 porque resultaba más comprensible; usa el que prefieras, aunque --staged es más claro.

Aquí es donde git diff demuestra su valor. Ana sigue trabajando y añade una línea más a estilos.css después de haber preparado:

Ahora las tres formas dan tres respuestas distintas:

Tres preguntas, tres respuestas precisas. El MM de git status te avisa de que hay algo raro; git diff te dice exactamente qué.

Compara tu directorio de trabajo con la última confirmación, ignorando el área de preparación. Es la respuesta a "¿qué he tocado desde el último commit?", que es la pregunta que uno se hace al volver de comer o al retomar el trabajo por la mañana.

HEAD no tiene nada de especial aquí: es simplemente una referencia a una confirmación, y git diff acepta cualquiera. Estas variantes son igual de válidas:

La notación HEAD~n y el resto de formas de referirse a una confirmación las veremos en detalle en Visualizando el Historial de Confirmaciones.

El formato que produce git diff se llama unified diff y es un estándar de la informática desde los años ochenta. Lo verás en Git, en las revisiones de código de GitHub y GitLab, en los parches de correo y en la salida de decenas de herramientas. Saber leerlo es una habilidad transferible.

Vamos a diseccionar una salida completa, línea por línea. Ana ha modificado app.js:

Indica que empieza la comparación de un fichero. a/ es la versión antigua y b/ la nueva; son prefijos convencionales, no directorios reales. En un renombrado verías nombres distintos a cada lado.

Si el diff incluye varios ficheros, verás una de estas líneas por cada uno: es el separador que te dice dónde empieza cada bloque.

Los hashes abreviados de los blobs antiguo y nuevo, y el modo de fichero (100644 = fichero normal). Esto conecta directamente con El Modelo de Datos de Git: el diff no es una entidad guardada en Git, sino algo que Git calcula al vuelo comparando dos blobs. Si el modo cambiara (por ejemplo, al hacer un fichero ejecutable), verías old mode y new mode en líneas aparte.

--- marca la versión antigua y +++ la nueva. Por eso, en el cuerpo del diff, - significa "estaba en la versión antigua" y + significa "está en la nueva".

Casos especiales que aclaran mucho:

Esta es la línea que más cuesta al principio y la que más información contiene. Se lee así:

Aplicado al ejemplo:

De los números se deduce todo: 8 líneas se han convertido en 12, luego el bloque ha crecido en 4. Y efectivamente, si cuentas el cuerpo: 7 líneas de contexto, 1 eliminada y 5 añadidas. Así se verifica cualquier cabecera @@:

• Líneas antiguas = contexto + eliminadas → 7 + 1 = 8.
• Líneas nuevas = contexto + añadidas → 7 + 5 = 12.

El texto del final no es una línea del fichero: Git lo extrae buscando hacia arriba la última línea que parece una declaración de función o sección. Sirve para orientarte cuando el diff es largo. Se puede afinar por lenguaje con .gitattributes, que veremos en Atributos de Fichero con .gitattributes.

Cuando el número de líneas es 1, se omite: @@ -12 +12 @@ significa "una línea a cada lado".

Cada línea del cuerpo empieza con un carácter que indica su naturaleza:

Aplicado a nuestro ejemplo:

Dos observaciones importantes:

1. Git no entiende de "líneas modificadas". Una modificación se representa siempre como una eliminación seguida de una adición. Por eso el primer par de líneas aparece como - y + aunque conceptualmente sea "la misma línea, cambiada".
2. Las líneas de contexto están por algo. Por defecto Git muestra 3 líneas de contexto a cada lado del cambio, para que puedas situarlo. Se ajusta con -U<n>:

Significa que ese fichero no termina con un salto de línea. Es una convención POSIX que muchas herramientas dan por hecha, y su ausencia genera diffs ruidosos: si alguien añade el salto final, todas las líneas cercanas pueden aparecer como cambiadas. Configurar el editor para que añada siempre el salto final evita este ruido.

Antes de seguir, lee este fragmento y responde: ¿cuántas líneas tenía el bloque antes y cuántas tiene ahora?

Cinco antes, tres después: se han eliminado dos líneas de depuración. Este es exactamente el tipo de hallazgo que justifica revisar el diff antes de confirmar.

git diff también compara dos puntos cualesquiera del historial:

Muestra todo lo que cambió entre esas dos confirmaciones, agregado en un solo diff. No importa cuántas confirmaciones haya en medio: compara los dos estados finales.

Formas equivalentes y muy usadas:

Esta última merece una nota: cuando le das un solo argumento, git diff compara esa confirmación con tu directorio de trabajo, no con HEAD. Es la misma lógica que git diff HEAD.

Para inspeccionar una confirmación aislada, lo idiomático es:

que muestra los metadatos (autor, fecha, mensaje) y el diff. Es el tema de la lección siguiente.

git diff acepta nombres de rama exactamente igual que hashes:

Y existe una notación de tres puntos, git diff main...desarrollo, que compara desde el punto en que ambas se separaron. Como en este módulo trabajamos siempre sobre main, lo dejamos apuntado: se desarrolla en el módulo 3.

En un cambio que toca quince ficheros, ver el diff completo es inmanejable. Se acota con -- seguido de rutas:

El doble guion -- separa las opciones de las rutas. Es opcional cuando no hay ambigüedad, así que git diff app.js funciona igual. Se vuelve obligatorio cuando un nombre de fichero podría confundirse con un nombre de rama o de confirmación:

Sin el --, Git intentaría interpretar main como una referencia y, si existiera la rama, obtendrías algo completamente distinto de lo que pedías. Acostumbrarse a poner -- antes de las rutas es un buen hábito.

Se combina con todo lo anterior:

Cada línea muestra el fichero, el número total de líneas afectadas y una barra proporcional de + (adiciones) y - (eliminaciones). Es la primera vista que conviene mirar ante un cambio grande: te dice dónde mirar después.

Variantes:

--numstat da adiciones, eliminaciones y nombre separados por tabuladores: ideal para procesar con scripts.

--name-status añade una letra por fichero: M modificado, A añadido, D borrado, R renombrado (el número indica el porcentaje de similitud: R100 es un renombrado sin cambios de contenido).

Estas opciones son muy prácticas encadenadas con otros comandos:

En un fichero de texto (documentación, README, contenido HTML), cambiar una palabra hace que toda la línea aparezca como eliminada y añadida. Es ilegible:

Con --word-diff el cambio real salta a la vista:

Lo eliminado va entre [- -] y lo añadido entre {+ +}. Con color en el terminal es todavía más claro.

Variantes:

Es imprescindible para revisar textos y muy útil en CSS y HTML.

Un reformateo automático, un cambio de indentación de tabuladores a espacios o un ajuste del editor pueden generar un diff de doscientas líneas donde el cambio real es de dos. La familia de opciones de espacios en blanco lo resuelve:

Un aviso: -w sirve para leer, no para decidir. Si el fichero es sensible a la indentación (Python, YAML, Makefile), esconder los cambios de espaciado puede ocultarte un error real. Úsalo para localizar el cambio de fondo y después vuelve al diff completo.

--color-moved es una joya poco conocida: cuando refactorizas moviendo un bloque de un sitio a otro, distingue visualmente "esto se ha movido" de "esto es nuevo".

Para diffs grandes o para gente que se maneja mejor con una vista de dos columnas, Git puede delegar en una herramienta externa:

Acepta exactamente los mismos argumentos que git diff.

Para Visual Studio Code, que es lo que usa Ana:

Para Meld (multiplataforma, gratuito y muy claro):

Para el opendiff de macOS, que le viene bien a Bruno:

Y un ajuste que casi todo el mundo acaba poniendo:

Sin él, Git pregunta antes de abrir cada fichero, lo cual es agotador cuando el cambio afecta a diez.

Las variables $LOCAL y $REMOTE que aparecen en la configuración son ficheros temporales que Git crea con cada versión y pasa a la herramienta. Todo esto se guarda en el ~/.gitconfig con el mecanismo que vimos en Configurando Git:

La recomendación práctica: usa git diff como herramienta por defecto —es más rápido y siempre está— y reserva difftool para los cambios grandes.

Mención aparte: existe también git mergetool, el equivalente para resolver conflictos de fusión. Se configura de forma análoga y lo veremos en Resolviendo Conflictos de Fusión.

Todo lo anterior se condensa en una rutina de treinta segundos que conviene automatizar mentalmente:

El paso realmente valioso es el penúltimo. Lo que detecta habitualmente:

• Restos de depuración: console.log, print, puntos de interrupción.
• Credenciales o URLs de pruebas.
• Bloques de código comentado que ibas a borrar.
• Cambios accidentales por autoformato del editor en ficheros que no tocabas.
• Ficheros que se colaron en un git add -A apresurado.
• Cambios que creías haber hecho y no estaban.

Si prefieres no ejecutar un comando aparte, la opción -v de git commit incluye el diff en la plantilla del mensaje:

Y para dejarlo activado siempre:

Es probablemente el ajuste con mejor relación entre esfuerzo y beneficio de todo Git.

• Ejecutar git diff después de git add y creer que no hay cambios. La salida vacía significa "el disco coincide con el área de preparación". Lo que buscas es git diff --staged.
• Esperar ver ficheros nuevos en git diff. Un fichero sin seguimiento no tiene versión anterior, así que no aparece. Para eso está git status. Si quieres verlo, prepáralo primero (git add -N fichero lo registra como vacío y hace que sus contenidos salgan en el diff).
• Leer al revés la cabecera @@. El primer número es de la versión antigua y el segundo de la nueva. Confundirlos lleva a interpretar mal el sentido del cambio.
• Pensar que Git guarda diffs. No los guarda: guarda instantáneas y calcula el diff cuando se lo pides, como vimos en el modelo de datos. Por eso puedes comparar dos confirmaciones cualesquiera, por lejanas que estén.
• Abusar de -w. En lenguajes sensibles a la indentación, ignorar espacios puede ocultarte el error que estás buscando. Es una herramienta de lectura, no de revisión final.
• No usar -- antes de una ruta ambigua. Si tienes un fichero llamado igual que una rama, git diff main no hará lo que crees.
• Revisar un cambio de 40 ficheros con el diff completo. Empieza por --stat para ver el mapa, y baja al detalle solo donde importe.
• Consejo: define alias para lo que más uses: git config --global alias.d diff y git config --global alias.ds "diff --staged".
• Consejo: si la salida de git diff se te queda "atrapada" en el paginador, recuerda que se recorre con las flechas o la barra espaciadora y se sale con q. Para desactivarlo puntualmente, git --no-pager diff.
• Consejo: git diff --stat justo después de git add -A es la forma más rápida de detectar que has añadido algo que no querías.

Monta este escenario y responde razonadamente antes de ejecutar cada comando:

1. ¿Qué mostrará git status -s?
2. ¿Qué mostrará git diff? ¿Cuántas líneas + tendrá?
3. ¿Qué mostrará git diff --staged?
4. ¿Qué mostrará git diff HEAD?
5. Si confirmas ahora sin más git add, ¿qué contendrá el fichero en el historial?
6. Comprueba tus respuestas ejecutándolo todo.

Interpreta esta salida y responde a las preguntas:

1. ¿Cuántos ficheros afecta este cambio y qué le pasa a cada uno?
2. En estilos.css, ¿cuántas líneas se han eliminado y cuántas se han añadido? ¿Cómo cambia el número total de líneas del bloque?
3. ¿Qué significa exactamente --- /dev/null en el segundo fichero?
4. ¿Qué significa index 0000000..7a8b9c0?
5. ¿Hay algo en este diff que no deberías confirmar? Explica por qué y qué harías.
6. Escribe el comando que mostraría solo el resumen por ficheros de este cambio.

Simula la situación de un fichero reindentado a la vez que se cambia una línea de lógica:

1. Ejecuta git diff y cuenta cuántas líneas aparecen como cambiadas.
2. Usa la opción adecuada para ver solo el cambio de lógica.
3. Explica por qué el resultado de los dos comandos es tan distinto.
4. ¿Qué habría sido mejor hacer desde el principio para que el historial fuera legible? Escribe la secuencia de comandos correcta.
5. Usa --word-diff sobre el mismo cambio y comenta si aporta algo en este caso.

Solución al Ejercicio 1

1. git status -s:

Hay una versión preparada (cambio 1) y el disco difiere de ella (cambio 2).

2. git diff — lo no preparado. Muestra únicamente el cambio 2:

Dos líneas +: la línea en blanco y la función. La línea tareas.push({...}) aparece como contexto, no como añadida, porque en el área de preparación ya está así.

3. git diff --staged — lo que va a entrar. Solo el cambio 1:

4. git diff HEAD — el total, ambos cambios juntos:

5. Al confirmar sin más git add entraría solo el cambio 1. El fichero en el historial tendría el push con el objeto, pero no la función contarTareas, que seguiría pendiente en el directorio de trabajo.

Comprobación:

Solución al Ejercicio 2

1. Dos ficheros:

• estilos.css: modificado (existe el par --- a/ +++ b/ con el mismo nombre y modo 100644).
• config.js: fichero nuevo, como indican new file mode 100644 y --- /dev/null.

2. En estilos.css: 3 líneas eliminadas (color: #333;, margin-bottom: 1rem; y .oculto { display: none; }) y 1 añadida (color: #1f2937;).

La cuenta encaja con la cabecera @@ -8,10 +8,8 @@: el bloque pasa de 10 a 8 líneas, es decir, pierde 2 (−3 +1 = −2). Y se puede verificar contando a mano las líneas del fragmento:

• Versión antigua = líneas de contexto + líneas - → 7 de contexto + 3 eliminadas = 10.
• Versión nueva = líneas de contexto + líneas + → 7 de contexto + 1 añadida = 8.

Este ejercicio de comprobación es la mejor forma de asegurarte de que has entendido la cabecera @@: los dos números siempre deben cuadrar con lo que ves en el cuerpo.

3. --- /dev/null indica que la versión antigua del fichero no existe: es un fichero nuevo. /dev/null es el "dispositivo nulo" de los sistemas Unix, y aquí funciona como "la nada". El caso simétrico, +++ /dev/null, indicaría un borrado.

4. index 0000000..7a8b9c0 son los hashes de los blobs antiguo y nuevo. El de la izquierda es todo ceros porque no hay blob antiguo: coherente con que el fichero sea nuevo.

5. Sí, hay un problema: CLAVE_DEBUG = 'test-1234' en config.js. Aunque sea una clave de pruebas, es un secreto en el código, y confirmarlo lo deja en el historial de forma permanente para cualquiera que clone el repositorio. Aunque sea inofensiva hoy, establece un mal precedente y es exactamente el mecanismo por el que acaban filtrándose claves reales.

Qué haría:

Si config.js no debiera versionarse en absoluto:

6. El resumen por ficheros:

Solución al Ejercicio 3

1. El diff completo:

Catorce líneas aparecen como cambiadas (7 eliminadas y 7 añadidas), cuando el cambio real de comportamiento es uno solo.

2. Ver solo la lógica:

Ahora solo hay un par -/+: la condición. La indentación de las demás líneas se ignora, así que el cambio real aparece aislado.

3. Por qué la diferencia es tan grande. Git compara líneas completas, carácter a carácter. Cambiar cuatro espacios por dos al principio de una línea la convierte, a ojos de Git, en una línea distinta: la antigua se elimina y la nueva se añade. Como el reformateo afecta a las siete líneas del cuerpo de la función, las siete aparecen cambiadas y el cambio de lógica se pierde entre ellas. -w le dice a Git que normalice los espacios antes de comparar, con lo que solo queda la diferencia real.

4. Lo correcto desde el principio: dos confirmaciones separadas. Mezclar reformateo con cambios funcionales es una mala práctica bien conocida, porque hace imposible revisar el cambio y arruina el git blame de todo el bloque.

El diff de la segunda confirmación es de dos líneas y se revisa en cinco segundos. Además, si mañana hay que deshacer el cambio de lógica, se deshace sin arrastrar el reformateo.

Si los dos cambios ya están mezclados en el disco, git add -p con la opción e permite separarlos, aunque en este caso concreto —donde cada línea contiene ambos cambios a la vez— sería más práctico rehacer el trabajo en dos pasos.

5. Con --word-diff:

Aporta bastante: al comparar por palabras en lugar de por líneas, la reindentación deja de generar ruido casi por completo y el cambio de la condición queda señalado con precisión quirúrgica. En cambios de texto y en casos como este, --word-diff y -w se complementan bien:

Ya sabes leer los cambios antes de que entren en la historia del proyecto. Recapitulando:

• git diff compara siempre dos zonas, y la forma que uses decide cuáles: git diff (disco ↔ preparación), git diff --staged (preparación ↔ HEAD) y git diff HEAD (disco ↔ HEAD, es decir, el total).
• Una salida vacía de git diff no significa "no he cambiado nada": casi siempre significa que ya lo has preparado todo.
• Ningún git diff muestra ficheros sin seguimiento. Para eso está git status.
• El formato unified diff tiene una estructura fija: cabecera diff --git, hashes de blob, marcadores ---/+++, cabeceras de fragmento @@ -a,b +c,d @@ con su contexto, y líneas de contexto, eliminadas (-) y añadidas (+). Git no representa "líneas modificadas": una modificación es una eliminación más una adición.
• Se pueden comparar dos confirmaciones cualesquiera (git diff <sha1> <sha2>) y acotar por ruta con -- <ruta>, usando -- siempre que el nombre pueda ser ambiguo.
• Las opciones cambian la legibilidad radicalmente: --stat para el mapa general, --name-only/--name-status para la lista, --word-diff para textos y -w para separar el cambio real del ruido de espaciado.
• git difftool delega en una herramienta visual y acepta los mismos argumentos; compensa en cambios grandes.
• El hábito que importa: git diff --staged antes de cada git commit, o directamente commit.verbose = true.

Con git status sabes dónde estás, con git diff sabes qué has cambiado y con git add/git commit decides qué queda registrado. Falta la última pieza del ciclo básico: mirar hacia atrás.

Un historial solo vale lo que vale la capacidad de consultarlo. Después de doscientas confirmaciones, ¿cómo encuentras cuándo se introdujo una función? ¿Quién tocó estilos.css la semana pasada? ¿En qué confirmación desapareció aquella línea que juras haber escrito?

En la siguiente lección, Visualizando el Historial de Confirmaciones, veremos git log con todos sus formatos y filtros, los formatos personalizados con --pretty, la búsqueda "pickaxe" que encuentra cuándo apareció o desapareció un texto concreto, git show para inspeccionar una confirmación, y las distintas formas de referirse a un commit —HEAD, HEAD~3, HEAD^— que ya hemos ido usando de pasada y que conviene entender bien.