Cerrábamos el módulo 4 con una advertencia: a partir de ahora el historial es compartido. Ana, Bruno y Carla trabajan sobre el mismo repositorio de git.ejemplo.es, y cada push deja commits que las otras dos personas pueden descargarse en cualquier momento. Esa es exactamente la circunstancia que convierte a git rebase en la herramienta más útil y más temida de Git.

git rebase sirve para una cosa muy concreta: coger una serie de commits y reaplicarlos sobre otra base. Sirve para que una rama que nació hace tres días vuelva a estar "encima" de main sin ensuciar el historial con fusiones; sirve para reordenar y limpiar tu trabajo antes de enseñárselo a nadie; y sirve para mover una rama que colgaba del sitio equivocado. Lo que la gente teme de ella es su otra cara: no mueve commits, los sustituye por otros nuevos. Y sustituir commits que ya están publicados es, como veremos, una forma bastante eficaz de arruinarle la tarde a tus compañeros.

Esta lección explica el mecanismo con detalle suficiente para que no haya magia: qué objetos se crean, qué hashes cambian, qué se conserva, cómo se resuelven los conflictos que aparecen a mitad y —sobre todo— cuándo conviene usar rebase y cuándo conviene usar merge.

1. La regla de oro del módulo
2. Qué hace git rebase realmente
3. Un rebase paso a paso en gestor-tareas
4. Qué se conserva y qué cambia en los commits reaplicados
5. Rebase frente a merge
6. git rebase --onto: mover un tramo concreto
7. Conflictos durante un rebase: --continue, --skip, --abort
8. La inversión de ours y theirs
9. Romper la regla de oro: qué pasa exactamente
10. git pull --rebase
11. rebase.autoStash y otras opciones cómodas
12. La red de seguridad

Antes de escribir un solo comando, la regla que gobierna todo el módulo 5:

No reescribas historial que ya has publicado y que otras personas pueden tener descargado.

Todo lo que veremos en las lecciones 05-01, 05-02 y 05-03 crea commits nuevos que sustituyen a otros. Mientras esos commits vivan solo en tu disco, reescribirlos es gratis: nadie más los ha visto. En cuanto los envías a git.ejemplo.es, dejan de ser tuyos: pasan a formar parte de una realidad compartida, y cambiarlos obliga a los demás a rehacer su copia.

La regla tiene una excepción muy acotada y muy conocida: tu propia rama de trabajo, publicada solo para tener copia o para una revisión, que nadie más está usando como base. Es un caso legítimo y habitual, pero exige avisar y exige --force-with-lease (lección 04-05). Volveremos a la regla en cada apartado que reescriba commits, hasta que resulte cargante. Ese es el objetivo.

La frase que suele repetirse es "rebase mueve tus commits encima de otra rama". Es cómoda y es falsa, y la diferencia importa.

Recuerda el modelo de datos de la lección 01-04: un commit es un objeto inmutable cuyo hash SHA-1 se calcula a partir de todo su contenido, y ese contenido incluye el hash de su padre. Por tanto:

• Si cambias el padre de un commit, cambia su contenido.
• Si cambia su contenido, cambia su hash.
• Si cambia su hash, ya no es el mismo commit: es otro objeto distinto.

Un commit no se puede "mover" igual que no se puede cambiar el pasado. Lo que hace git rebase es:

1. Calcular la lista de commits que están en tu rama y no en la nueva base.
2. Guardar el cambio (el diff) que introduce cada uno.
3. Situarse en la nueva base.
4. Aplicar esos cambios uno a uno, creando un commit nuevo por cada uno.
5. Mover la referencia de rama a la punta de la cadena nueva.

Los commits antiguos siguen existiendo en la base de datos de objetos —los objetos de Git no se borran al instante—, pero se quedan sin ninguna rama que los alcance. Son, a efectos prácticos, historia muerta.

Ese es el punto de partida: Carla creó su rama cuando main estaba en b3f7c21, y mientras trabajaba Ana publicó e91d4a8. Después del rebase:

Fíjate bien en los identificadores: 7c2e5f9 y a4b1d83 han desaparecido del dibujo, y en su lugar hay d5e8f31 y 92c7a06. El contenido de los cambios es el mismo, los mensajes son los mismos, el autor es el mismo. Los commits, no.

Carla lleva dos días con funcionalidad/etiquetas-color: quiere que cada tarea pueda llevar un color. Mientras tanto, Ana ha publicado un cambio en main. Carla quiere ponerse al día sin crear un commit de fusión.

La bifurcación está clara: dos commits por un lado, uno por el otro, y b3f7c21 como ancestro común. Comprobemos qué commits se van a reaplicar antes de tocar nada:

Esa es exactamente la lista de la que hablábamos: el rango main..HEAD que aprendiste en la lección 02-06. Ahora sí:

Ya no hay bifurcación: una sola línea recta. Y los hashes de los dos commits de Carla han cambiado. Vale la pena verificar con git show que el cambio es idéntico:

Mismo autor, misma fecha de autoría, mismo mensaje, mismo diff. Distinto objeto.

Un detalle importante para el final: como la rama de Carla no estaba publicada, aquí no hay nada que negociar. Si lo estuviera, el siguiente git push sería rechazado por non-fast-forward (lección 04-05) y habría que usar --force-with-lease.

Esta tabla resuelve la mayoría de las dudas de quien empieza:

Dos consecuencias prácticas:

• git log muestra por defecto la fecha de autoría, así que después de un rebase el historial sigue enseñando las fechas originales. Si quieres ver la de confirmación: git log --pretty=fuller.
• Si en tu equipo alguien mira "quién confirmó qué", el rebase te pone a ti como committer de commits ajenos. No es un problema, pero conviene saberlo.

Las dos integran el trabajo de una rama con el de otra. La diferencia no es técnica sino narrativa: qué historia quieres que cuente el repositorio.

Y el criterio, resumido en tres reglas que sí puedes memorizar:

1. Rebase para lo que aún es tuyo. Tu rama local, antes de publicarla o antes de pedir su integración: ponla al día sobre main con rebase.
2. Merge para juntar historias que ya son públicas. Integrar una rama de funcionalidad terminada en main es un hecho que merece quedar registrado; ahí un merge (a menudo --no-ff, lección 03-03) es la opción honesta.
3. Ante la duda, merge. Es la opción que nunca destruye nada.

Hay equipos que llevan esto al extremo en un sentido ("historial lineal siempre") y otros en el contrario ("nunca reescribir nada"). Las dos posturas son defendibles y las veremos con nombre propio en el módulo 7 (flujos de trabajo) y en la lección 08-02, cuando hablemos de la política de historial limpio. Aquí nos ocupa el mecanismo.

git rebase <base> cubre el 90 % de los casos, pero tiene un supuesto implícito: que quieres reaplicar todo lo que hay entre el ancestro común y tu rama. A veces no es eso lo que quieres.

Le pasó a Carla. Empezó funcionalidad/orden-por-fecha sin darse cuenta de que estaba situada en funcionalidad/etiquetas-color en lugar de en main. Ahora su rama nueva arrastra los dos commits de las etiquetas de color, que no tienen nada que ver.

Quiere que funcionalidad/orden-por-fecha cuelgue directamente de main (que está en e91d4a8) y contenga solo 3f9a2c4 y 6b1e7d5. Para eso está la forma de tres argumentos:

La forma de leerla en voz alta es esta:

• <hasta> — la rama que quiero mover (si la omites, la rama actual).
• <desde> — el punto a partir del cual empiezan los commits que quiero llevarme. Este commit no se incluye; funciona como el límite exclusivo de un rango desde..hasta.
• <nueva-base> — dónde quiero que queden pegados.

Aplicado al caso de Carla:

Los dos commits de la fecha se han reaplicado sobre main con hashes nuevos, y la rama de las etiquetas de color se ha quedado donde estaba, intacta.

Otros usos habituales de --onto, para que reconozcas el patrón:

Ese último es un buen ejercicio mental: 8b6d3c2 es el commit que queremos eliminar, 4e7f2a9 es su padre, y estamos diciendo "coge todo lo que hay después de 8b6d3c2 y pégalo directamente sobre su padre". El rebase interactivo (lección 05-02) tiene una forma mucho más cómoda de hacer lo mismo, pero conviene entender que por debajo es esto.

Un rebase aplica commits uno a uno, así que puede pararse una vez por cada commit. La mecánica de resolución —los marcadores <<<<<<<, git status, editar, git add— es exactamente la que aprendiste en la lección 03-05; no la repetimos. Lo que cambia es cómo se sale del atasco.

Supongamos que Carla rebasa y el segundo commit choca:

Ese bloque de git status es tu panel de control: te dice en qué commit de la lista vas y qué queda. Las tres salidas:

Tres advertencias importantes:

• --skip no es "sáltate el conflicto": es "tira este commit a la basura". Si el commit tenía cambios que no están en ninguna otra parte, los pierdes de la rama resultante. Úsalo solo cuando estés seguro de que su contenido ya está aplicado.
• --abort es completamente seguro. Devuelve la rama exactamente donde estaba, con los commits originales y sus hashes originales. Cuando dudes, aborta y piensa con el repositorio en calma.
• No hagas git commit a mano durante un rebase. Después de resolver y hacer git add, es git rebase --continue quien crea el commit. Si haces git commit, --continue te dirá que no queda nada que confirmar (y en versiones antiguas puede dejar la lista descuadrada).

Un detalle útil: si tras resolver el conflicto el resultado es idéntico a la base (es decir, tu commit ya no aporta nada), git rebase --continue lo detecta y te propone saltarlo. Es normal y no indica ningún problema.

Aquí está la trampa que confunde a todo el mundo, incluidos veteranos.

En una fusión normal (lección 03-05), ours es tu rama —donde estás— y theirs es la rama que traes. Intuitivo.

En un rebase se invierte. Y no es un capricho: es la consecuencia lógica del mecanismo. Recuerda que un rebase primero se coloca en la nueva base y luego aplica tus commits encima, uno a uno, como si fueran parches ajenos. Por tanto, en cada paso:

Dicho de forma memorable: durante un rebase, "los suyos" eres tú.

La consecuencia práctica es directa. Si durante un rebase quieres quedarte con tu versión del fichero:

Lo mismo vale para -X ours / -X theirs cuando se los pasas al rebase, y para los nombres de las etapas del índice (:2: y :3:) que viste en 03-05. Si alguna vez dudas, no adivines: mira el contenido antes de decidir.

Un consejo que ahorra muchos disgustos: configura el estilo zdiff3 (lección 03-05) también aquí. Ver el ancestro común dentro del marcador hace la orientación mucho menos dependiente de recordar quién es quién:

Y si el mismo conflicto se repite commit tras commit dentro del mismo rebase, existe git rerere (reuse recorded resolution), que memoriza cómo resolviste un conflicto y lo aplica solo la próxima vez que aparezca idéntico. Se mencionó en 03-05 y su configuración se sale de esta lección.

Veámoslo con nombres y apellidos, porque el mecanismo del desastre explica la regla mejor que cualquier advertencia.

1. Bruno publica funcionalidad/exportacion-csv con tres commits: 2a7f4c1, 9e3b8d6, 5c1a9f2.
2. Carla hace git fetch y crea su rama a partir de ese trabajo. Ahora tiene esos tres commits en su disco.
3. Bruno rebasa su rama sobre main porque main ha avanzado. Sus tres commits se convierten en d8b2e50, 71f6c34, ae95d18.
4. Bruno hace git push --force-with-lease. El servidor ahora apunta a ae95d18.
5. Carla hace git pull.

Lo que ve Carla:

Y a partir de aquí, según su configuración de pull:

• Con pull.ff only (la que configuramos en 01-06): el pull falla con un aviso de divergencia. Es el mejor de los casos: Carla se entera y puede preguntar.
• Con merge: Git fusiona la cadena vieja con la nueva y aparecen los tres commits duplicados, cada uno dos veces con hashes distintos, más un commit de fusión, más un puñado de conflictos absurdos donde cada cambio choca consigo mismo.
• Con rebase: Carla reaplica sus commits (que incluyen los tres viejos de Bruno) sobre la cadena nueva, y obtiene el mismo festival de duplicados.

Y si Carla resuelve mal y publica, los commits viejos vuelven al servidor y el rebase de Bruno queda deshecho. Es el ciclo clásico: alguien rebasa, alguien lo revierte sin querer, y el historial acaba con todo por duplicado.

Cómo se evita, en orden de eficacia:

1. No reescribir ramas compartidas. Si más de una persona trabaja en ella, se integra con merge y punto.
2. Si la rama es tuya y publicada solo como copia, rebasa cuando quieras, pero avisa antes de forzar y usa siempre --force-with-lease (nunca --force), que se niega si alguien ha publicado algo que tú no tienes.
3. Si has sido la víctima, la salida es git reset --hard origin/<rama> para descartar tu copia vieja y volver a aplicar lo tuyo encima. La casuística completa, con los pasos para no perder trabajo, está en la lección 09-03.

En la lección 04-04 dejamos pendiente esta opción. Ya podemos entenderla del todo.

git pull es fetch + integración. Con --rebase, la integración es un rebase de tus commits locales sobre lo que acabas de traer:

Comparación de los tres modos, ahora completa:

Por qué gusta tanto: cuando dos personas tocan cosas distintas del mismo proyecto y sincronizan a menudo, pull con merge genera un reguero de commits "Merge branch 'main' of git.ejemplo.es..." que no cuentan absolutamente nada. pull --rebase los elimina.

Y por qué hay que usarlo con cabeza: reescribe tus commits locales. Eso es inofensivo si no los has publicado (que es el caso típico: acabas de hacerlos y aún no ha habido push), y es exactamente el escenario del apartado 9 si sí los has publicado.

Para dejarlo configurado:

pull.rebase merges (equivalente a --rebase-merges) merece una nota: por defecto, un rebase descarta los commits de fusión de la cadena que reaplica y aplana todo en una línea. Si tenías fusiones intencionadas en tu trabajo local, merges las conserva reconstruyéndolas.

Si dejas pull.ff only como configuración global (nuestra recomendación de 01-06 y la más segura para aprender), siempre puedes pedir el rebase puntualmente con git pull --rebase. Lo explícito gana.

git rebase exige un directorio de trabajo limpio: si tienes cambios sin confirmar, se niega a empezar.

La solución manual es git stash, rebasar y git stash pop (lección 05-04). La automática:

Con eso, Git aparta los cambios solo, rebasa y los devuelve al terminar. Si al devolverlos hay conflicto, te avisa y el stash se queda a salvo en la pila. Es una comodidad excelente, y su equivalente para pull es rebase.autoStash combinado con pull.rebase, o git pull --rebase --autostash.

Otras opciones que conviene conocer:

rebase.updateRefs resuelve un problema molesto: si tienes ramas apiladas (b sale de a, c sale de b) y rebasas c, las referencias intermedias se quedaban apuntando a los commits viejos. Con esta opción activada, Git las arrastra.

Un rebase puede salir mal: puedes hacer --skip de un commit que no debías, resolver un conflicto al revés, o darte cuenta a los diez minutos de que la base era otra.

Buena noticia: los commits originales siguen ahí. Como vimos en el apartado 2, el rebase no borra objetos, solo deja de referenciarlos, y Git guarda un registro de por dónde ha pasado cada referencia. Ese registro es el reflog, y con él se recupera el estado anterior a un rebase casi siempre.

Este curso dedica la lección 09-04: Recuperando Confirmaciones Perdidas a ese tema, incluido el procedimiento exacto para deshacer un rebase desastroso. Aquí basta con que sepas dos cosas:

1. Que la red existe: un rebase mal hecho es recuperable durante semanas.
2. Que no es excusa para saltarse la regla de oro, porque el reflog es local. Recupera tu repositorio; no arregla los de tus compañeros que ya se descargaron los commits que reescribiste.

Y el reflejo barato que sí puedes adoptar hoy: antes de un rebase que te dé respeto, deja una marca.

Una rama son 41 bytes. La tranquilidad, bastante más.

Error 1: creer que el rebase "mueve" los commits. Los sustituye por otros nuevos con hashes distintos. Todo el peligro del rebase deriva de este hecho, y quien lo interioriza deja de tener sorpresas.

Error 2: rebasar una rama compartida. Si Bruno y Carla trabajan los dos en funcionalidad/exportacion-csv, ninguno de los dos la rebasa. Se integra con merge. La comodidad de un historial lineal no compensa una tarde de duplicados.

Error 3: usar --ours durante un rebase pensando que es tu versión. Es la de la base. Durante un rebase, tú eres theirs. Ante la duda, git show :2:fichero y git show :3:fichero.

Error 4: usar git rebase --skip para "quitarme el conflicto de encima". Descarta el commit entero. Si contenía trabajo real, desaparece de la rama resultante.

Error 5: hacer git commit en medio de un rebase. Quien confirma es git rebase --continue. Tú solo resuelves y haces git add.

Error 6: git push --force en lugar de --force-with-lease. El primero pisa lo que haya en el servidor sin mirar; el segundo se niega si alguien ha publicado algo que tú no tienes. La diferencia se explicó en 04-05 y aquí es donde de verdad importa.

Error 7: rebasar sin fetch previo. git rebase main usa tu main local, que puede llevar dos días desactualizado. El orden correcto es git fetch origin, actualizar main, y entonces rebasar (o rebasar directamente sobre origin/main).

Consejo 1: rebasa pronto y a menudo. Una rama que se pone al día cada día tiene conflictos pequeños; una que lo hace después de dos semanas tiene un conflicto por commit y todos grandes.

Consejo 2: mira siempre git log --oneline main..HEAD antes de rebasar. Esa lista es exactamente lo que se va a reescribir. Si te sorprende su longitud o su contenido, la base que ibas a usar no era la que creías.

Consejo 3: activa rebase.autoStash y merge.conflictStyle zdiff3. Dos líneas de configuración que eliminan dos de las fricciones más habituales.

Consejo 4: si el rebase se pone feo, aborta. git rebase --abort es gratis y siempre funciona. Volver a intentarlo con la cabeza fría, con los commits más pequeños o con --onto bien elegido suele ser mucho más rápido que insistir.

Crea un repositorio de prácticas con una rama main y una rama funcionalidad/algo que salga de ella. Añade dos commits a cada una. Después:

1. Anota los hashes de los dos commits de la rama de funcionalidad.
2. Rebásala sobre main.
3. Demuestra con comandos que los hashes han cambiado, que la fecha de autoría se ha conservado y que la de confirmación no.
4. Demuestra que los commits originales siguen existiendo en la base de datos de objetos.

Reproduce el problema de Carla: crea rama-a sobre main con dos commits, y rama-b sobre rama-a con otros dos. Después, usando git rebase --onto, consigue que rama-b cuelgue de main conteniendo solo sus dos commits propios. Verifica el resultado con git log --graph --all --oneline.

Provoca un conflicto durante un rebase (las dos ramas modificando la misma línea de un fichero). Con el rebase parado:

1. Muestra las tres versiones del fichero desde el índice (etapas :1:, :2: y :3:) e identifica cuál corresponde a tu commit.
2. Resuelve quedándote con tu versión usando la opción correcta de git checkout.
3. Termina el rebase.
4. Repite el experimento desde cero pero abortando con --abort, y comprueba que la rama vuelve a tener sus hashes originales.

Solución 1:

El hash es distinto, la fecha de autoría idéntica y la de confirmación es la del momento del rebase.

Existe como objeto aunque ninguna rama lo alcance. Es lo que hace posible la recuperación de la lección 09-04.

Solución 2:

rama-b cuelga de main con sus dos commits y sin rastro de A1 ni A2.

Solución 3:

La etapa :3: es la mía: durante un rebase, mi commit es theirs.

--abort restaura la rama exactamente como estaba: mismos commits, mismos hashes, mismo directorio de trabajo.

git rebase deja de dar miedo en cuanto se entiende qué hace de verdad. Lo esencial de esta lección:

• Rebase no mueve commits: crea commits nuevos. Cambia el padre, luego cambia el hash, luego es otro objeto. Los originales quedan huérfanos pero siguen en la base de datos.
• git rebase <base> reaplica sobre <base> todo lo que hay en tu rama y no en ella; git rebase --onto <nueva-base> <desde> <hasta> te deja elegir con precisión qué tramo mover y adónde.
• Rebase frente a merge no es una cuestión técnica sino narrativa: merge cuenta lo que pasó, rebase cuenta una versión ordenada. Rebase para lo que aún es tuyo; merge para juntar historias públicas; ante la duda, merge.
• Los conflictos de un rebase se resuelven igual que los de una fusión (lección 03-05), pero se sale con --continue, --skip (que descarta el commit) o --abort (que es siempre seguro), y las caras ours/theirs están invertidas: la base es ours, tu commit es theirs.
• La regla de oro: no reescribas historial publicado que otros puedan tener. Si lo haces, tus compañeros acaban con todo duplicado y la única salida es coordinarse.
• git pull --rebase aplica esta misma idea al sincronizar y elimina los commits de fusión inútiles; rebase.autoStash quita la fricción de tener cambios sin confirmar.
• El reflog es la red de seguridad para tu repositorio (lección 09-04), no para el de los demás.

Hasta ahora hemos usado el rebase para una sola cosa: cambiar la base. Pero el mismo mecanismo —descomponer una rama en una lista de commits y volver a aplicarlos— permite mucho más si te dejan editar esa lista antes de que se ejecute: cambiar el orden, unir dos commits en uno, partir uno en dos, corregir un mensaje o eliminar un commit por completo.

Eso es exactamente lo que hace git rebase -i, y es lo que Bruno necesita para convertir sus commits arreglo, wip 2 y wip 3 en algo que se pueda enseñar sin vergüenza. Lo vemos en la lección 05-02: Rebase Interactivo.