StackPractices
intermediate Por Mathias Paulenko

Limpia el historial de commits con git rebase interactivo

Haz squash, reordena, edita y divide commits con git rebase interactivo. Cubre pick, squash, fixup, reword, drop y resolución de conflictos.

Temas: devops

Visión General

El rebase interactivo permite reescribir el historial de commits antes de fusionar una rama. Puedes combinar commits relacionados, reordenarlos, corregir sus mensajes, dividir commits grandes y eliminar los que no deberían llegar a producción. El resultado es un historial que los revisores pueden seguir de verdad — y git blame sigue siendo útil meses después. Esta receta recorre cada acción del rebase interactivo con ejemplos reales, incluidas las dos cosas que más confunden la primera vez: la lista de tareas muestra los commits del más antiguo al más reciente, y edit pausa la reproducción a mitad de camino, no al final.

Cuándo Usar

  • Estás limpiando una rama de función antes de abrir o actualizar una pull request — un historial ordenado combina bien con una plantilla de pull request para que el revisor vea una sola narrativa limpia.
  • Tienes commits WIP, fix o typo que pertenecen dentro de un commit más grande y con sentido.
  • Un mensaje de commit necesita reescritura — alcance equivocado, errata o falta de contexto.
  • Los commits quedaron en el orden incorrecto, o un commit junta varios cambios que deberían revisarse por separado.
  • Un commit no pertenece a la rama — un helper de depuración o un experimento revertido.

No uses rebase cuando la rama ya está publicada y tus compañeros la descargaron. Reescribir un historial compartido obliga a todos a reconciliar sus clones, y --force-with-lease solo protege el remoto, no su trabajo local. Usa git revert sobre commits públicos o fusiona con normalidad. Para una rama personal con historial trivial, el squash-merge desde la interfaz del PR suele bastar.

Solución

Iniciar un rebase interactivo

# Rebase de los últimos 5 commits
git rebase -i HEAD~5

# Rebase hasta un commit específico — todo lo posterior se reescribe
git rebase -i <commit-hash>

# Rebase sobre una rama (habitual antes de fusionar)
git rebase -i main

La segunda forma te ahorra contar commits: pasa el hash del commit anterior a los que quieres tocar.

Tu editor se abre con la lista de tareas:

pick 1a2b3c4 Add user model
pick 5d6e7f8 WIP: fix validation
pick 9a0b1c2 WIP: tests
pick 3d4e5f6 Add user API endpoints
pick 7a8b9c0 Fix typo in endpoint

# Comandos de rebase:
# pick   = usar el commit tal cual
# reword = usar el commit, editar el mensaje
# edit   = usar el commit, pausar para corregirlo
# squash = combinar con el commit anterior
# fixup  = como squash, descartando el mensaje
# drop   = eliminar el commit

Ojo con el orden: la lista va del commit más antiguo al más reciente, al revés que git log. El primer pick es el primer commit que Git va a volver a aplicar, así que al hacer squash siempre estás fusionando con la línea de arriba. Casi todo el mundo marca la dirección equivocada la primera vez.

Archivos complementarios: el repo companion de git-rebase-interactive-tutorial tiene un demo.sh que construye un repo de juguete con estos mismos commits para practicar cada acción de verdad.

Combinar commits con squash

pick 1a2b3c4 Add user model
squash 5d6e7f8 WIP: fix validation
squash 9a0b1c2 WIP: tests
pick 3d4e5f6 Add user API endpoints
pick 7a8b9c0 Fix typo in endpoint

Al guardar, Git abre un editor para combinar los mensajes:

# This is a combination of 3 commits.
# This is the 1st commit message:
Add user model

# The commit messages of commits being squashed:
WIP: fix validation

WIP: tests

Edita hasta dejar un solo mensaje limpio:

Add user model with validation and tests

Fixup — combinar y descartar el mensaje

pick 1a2b3c4 Add user model
fixup 5d6e7f8 WIP: fix validation
fixup 9a0b1c2 WIP: tests
pick 3d4e5f6 Add user API endpoints

Fixup fusiona el commit con el anterior y descarta su mensaje — no hay segunda ventana del editor, lo que lo convierte en la opción más rápida para ruido tipo WIP.

Reescribir un mensaje con reword

pick 1a2b3c4 Add user model
reword 3d4e5f6 Add user API endpoints
pick 7a8b9c0 Fix typo in endpoint

Git pausa y abre un editor sobre el mensaje de ese commit. Escribe el texto nuevo, guarda y la reproducción continúa.

Editar un commit (pausa para modificar)

pick 1a2b3c4 Add user model
edit 3d4e5f6 Add user API endpoints
pick 7a8b9c0 Fix typo in endpoint

Git se detiene en el commit marcado, con sus cambios ya aplicados. Puedes modificar archivos, prepararlos y corregir el commit ahí mismo:

# Hacer los cambios
vim src/api/users.py
git add src/api/users.py

# Corregir el commit
git commit --amend

# Continuar el rebase
git rebase --continue

Eliminar un commit

pick 1a2b3c4 Add user model
drop 5d6e7f8 Add debug logging
pick 3d4e5f6 Add user API endpoints

Borrar la línea hace lo mismo. Si un commit posterior dependía del cambio eliminado, espera un conflicto en el siguiente pick.

Reordenar commits

pick 3d4e5f6 Add user API endpoints
pick 1a2b3c4 Add user model
pick 7a8b9c0 Fix typo in endpoint

Git vuelve a aplicar los commits en el nuevo orden. Reordenar commits que tocan el mismo código puede generar conflictos aunque cada uno se aplicara limpio en el orden original.

Dividir un commit

edit 1a2b3c4 Add user model and API endpoints
pick 3d4e5f6 Add tests
pick 7a8b9c0 Fix typo

Cuando Git pausa en la línea edit, estás situado en ese commit con sus cambios ya aplicados. Sácalos del índice y vuelve a commitear por partes:

# Revierte el commit pero conserva los cambios en el árbol de trabajo
git reset HEAD^

# Prepara y commitea la primera parte
git add src/models/user.py
git commit -m "Add user model"

# Prepara y commitea la segunda parte
git add src/api/users.py
git commit -m "Add user API endpoints"

# Continúa el rebase — Git aplica los picks restantes
git rebase --continue

git reset HEAD^ usa el modo mixto por defecto: elimina el commit pero conserva el contenido de los archivos, que es justo lo que necesitas para dividir.

Resolver conflictos durante el rebase

git rebase -i main
# CONFLICT (content): Merge conflict in src/models/user.py

Resuelve el conflicto:

# 1. Edita el archivo para resolver los conflictos
vim src/models/user.py

# 2. Prepara el archivo resuelto
git add src/models/user.py

# 3. Continúa el rebase
git rebase --continue

Si prefieres abortar:

git rebase --abort

Y si quieres omitir el commit conflictivo:

git rebase --skip

Autosquash con commits fixup

# Crea un commit fixup dirigido a un commit concreto
git commit --fixup 1a2b3c4

# Rebase con autosquash — Git reordena los fixups junto a su objetivo
git rebase -i --autosquash HEAD~5

Git 2.32 añadió dos formas más útiles para cuando la corrección también debe tocar el mensaje original:

git commit --fixup=amend:1a2b3c4   # aplica la corrección y corrige el mensaje del objetivo
git commit --fixup=reword:1a2b3c4 # igual, pero abre el editor para confirmar

Git coloca los commits fixup justo después de su objetivo y los marca automáticamente:

pick 1a2b3c4 Add user model
fixup 9a0b1c2 fixup! Add user model
pick 3d4e5f6 Add user API endpoints

Force push después del rebase

# Force push seguro — falla si alguien subió cambios desde tu último fetch
git push --force-with-lease origin feature-branch

# Nunca uses force push a secas en ramas compartidas
# git push --force  # PELIGROSO

Explicación

El rebase interactivo vuelve a aplicar los commits uno a uno, ejecutando sobre cada uno la acción que elegiste. Nada se modifica “en el sitio” — todos los commits posteriores al primero que tocaste reciben un hash nuevo, y esa es exactamente la razón por la que rebase y ramas compartidas no se llevan bien.

El rebase interactivo convierte una lista de tareas desordenada de picks y squash en un historial limpio de dos commits.

Las acciones disponibles:

  • pick: conserva el commit tal cual. Es la acción por defecto.
  • reword: conserva el commit, pero abre un editor para cambiar el mensaje.
  • edit: pausa en el commit para que puedas modificar archivos y hacer git commit --amend. Luego git rebase --continue reanuda la reproducción donde quedó.
  • squash: fusiona el commit con el anterior y abre un editor para combinar ambos mensajes.
  • fixup: fusiona con el commit anterior pero descarta el mensaje — sin ventana del editor.
  • drop: elimina el commit por completo. Mismo efecto que borrar la línea.
  • exec: ejecuta un comando de shell en ese punto de la reproducción.
  • break: detiene el rebase en ese punto; git rebase --continue lo reanuda.

Conceptos clave:

  • Rebase reescribe el historial. Los commits viejos se sustituyen por otros nuevos con hashes distintos — quien haya descargado los antiguos se queda en una rama divergente.
  • Nunca hagas rebase de commits ya publicados en ramas compartidas. Los clones de tus compañeros dejarán de coincidir con el remoto.
  • --force-with-lease es la forma segura de subir un historial reescrito: falla si el remoto se movió desde tu último fetch, en lugar de sobrescribir el trabajo ajeno sin avisar.
  • --autosquash mueve los commits fixup! y squash! junto a su objetivo en la lista de tareas, convirtiendo git commit --fixup en tu forma habitual de corregir hacia adelante.
  • Los conflictos aparecen cuando los commits dependen entre sí — resuelve, prepara y continúa. Si el mismo conflicto vuelve en cada pick, git rerere puede recordar cómo lo resolviste.

Recuperación y movimientos avanzados

Si un rebase se tuerce, tienes dos vías de escape. git rebase --abort a mitad de sesión devuelve la rama a su estado previo. Cuando ya terminó, ORIG_HEAD sigue apuntando a la punta anterior, así que git reset --hard ORIG_HEAD es la forma más rápida de deshacer — y git reflog registra cada movimiento de HEAD por si necesitas un punto aún más viejo.

Para revisar qué cambió realmente un rebase — por ejemplo antes de un force-push sobre una rama que un compañero ya vio — git range-diff <punta-vieja>..<punta-nueva> compara las dos series de commits en lugar de los árboles. Muestra mensajes reescritos, commits eliminados y cambios reales de código en una sola vista.

Dos flags que conviene tener a mano:

  • git rebase -i --root reescribe hasta el primer commit del repo — útil en repositorios nuevos.
  • GIT_SEQUENCE_EDITOR=true git rebase -i HEAD~3 acepta la lista de tareas tal cual, que es como los scripts y alias ejecutan un rebase sin abrir el editor.

Una línea exec ejecuta un comando de shell en ese punto de la reproducción. Pon una entre picks para detener el rebase si un commit intermedio no compila:

pick 1a2b3c4 Add user model
exec npm test
pick 3d4e5f6 Add user API endpoints
exec npm test

Variantes

Elegir entre squash, fixup y el resto se reduce a qué sobrevive: el cambio en sí, y su mensaje.

AcciónEfectoUsar cuando
squashCombina + edita el mensajeCommits relacionados, quieres un solo mensaje
fixupCombina + descarta el mensajeCommits WIP, el mensaje sobra
rewordSolo edita el mensajeCorregir una errata, mejorar la claridad
editPausa y modificaDividir un commit, añadir un archivo olvidado
dropElimina el commitRevertir un cambio no deseado
execEjecuta un comandoCorrer tests en un commit concreto

exec y break no tocan los commits — controlan la reproducción en sí.

Pautas

  • Haz rebase de tu rama de función antes de fusionarla — un historial lineal y combinado es lo que hace que git log --oneline y git bisect sean realmente útiles meses después.
  • Usa squash cuando los mensajes individuales aportan contexto que quieres en el commit final; usa fixup para commits WIP y typo cuyo mensaje es puro ruido.
  • Haz force-push con --force-with-lease, nunca con --force a secas: se niega a sobrescribir el remoto si alguien subió cambios después de tu último fetch.
  • Corrige hacia adelante con git commit --fixup <sha> más --autosquash mientras trabajas, y deja que el rebase ensamble el historial limpio al final.
  • Mantén los commits pequeños y con un solo propósito — son mucho más fáciles de reordenar, dividir y revisar que los grandes commits mezclados.
  • Escribe el mensaje combinado pensando en el revisor, no en ti: debe describir el cambio completo, no el camino recorrido.
  • Ejecuta tu suite de tests después de un rebase que tocó código. Los commits reaplicados pueden producir un árbol que compila pero se comporta distinto — como mínimo, corre los tests que cubren los archivos que combinaste, eliminaste o reordenaste.
  • Solo haz rebase de ramas que son tuyas. main, develop y cualquier rama que tus compañeros hayan descargado están prohibidas — git revert existe para arreglar historial público.
  • Ten git reflog siempre presente. Registra cada movimiento de HEAD durante unos 90 días, así que un rebase fallido casi siempre se puede recuperar.

Errores Comunes

  • Hacer rebase de commits que ya están en una rama compartida — el historial de todos los demás diverge y pasarán la tarde desenredando sus clones.
  • Usar git push --force donde --force-with-lease se habría negado: puedes sobrescribir el push de un compañero sin darte cuenta.
  • Combinar diez commits en un solo commit gigante de “feature” — es imposible de revisar y doloroso de revertir. Combina en unidades lógicas.
  • Saltarte los tests después de reaplicar commits. Un squash que se aplica limpio puede producir un árbol roto cuando los estados intermedios chocaban semánticamente.
  • Eliminar un commit del que dependen commits posteriores — tendrás un conflicto en cada pick siguiente, y la solución suele ser --abort y una lista de tareas nueva.
  • Editar archivos durante un conflicto y olvidar git rebase --continue; el rebase se queda pausado mientras sigues escribiendo comandos sobre un estado a medias.
  • Entrar en pánico a mitad del rebase y cerrar la terminal. --abort deja la rama exactamente como estaba — no hace falta borrar nada.
  • Olvidar que git reflog existe. Cuando --abort ya no es opción, reflog — o ORIG_HEAD — aún te devuelve la punta anterior.

Lecturas Recomendadas

Preguntas frecuentes

¿Es seguro el rebase interactivo?

Sí — en una rama de función donde solo trabajas tú, con --abort y git reflog como red de seguridad. Deja de ser seguro en el momento en que los commits viven en una rama compartida como main o develop, porque todos los demás heredarían un historial divergente.

¿Cuál es la diferencia entre squash y fixup?

Ambos fusionan un commit con el de arriba. Squash abre un editor para que combines los mensajes; fixup descarta el mensaje por completo y se salta el editor. Usa squash cuando el mensaje tiene contexto que vale la pena conservar, y fixup para commits WIP o de corrección de erratas.

¿Cómo me recupero de un rebase fallido?

Durante la sesión, git rebase --abort restaura el estado previo. Si ya terminó, git reset --hard ORIG_HEAD vuelve a la punta anterior en un solo paso, y git reflog lista cada movimiento de HEAD, así que nada se pierde de verdad.

¿Debo hacer rebase antes de fusionar un PR?

Sí — hacer rebase sobre el main más reciente primero da a los revisores un historial lineal y atrapa los conflictos en tu rama en lugar de dentro del merge. Combina los commits WIP, reescribe los mensajes confusos y elimina los callejones sin salida antes de pedir revisión.

¿Cuál es la diferencia entre git rebase y git merge?

git merge une dos ramas con un commit de merge que conserva ambos historiales padre. git rebase vuelve a aplicar tus commits encima de la rama objetivo, produciendo un historial lineal sin commit de merge. Usa merge para ramas compartidas donde preservar el contexto importa; usa rebase para ramas privadas donde importa la legibilidad. La guía de estrategias de ramificación compara cuándo encaja cada modelo en un equipo.

¿Cómo resuelvo conflictos durante un rebase interactivo?

Cuando aparece un conflicto, Git pausa la reproducción. Corrige los marcadores en el archivo, haz git add y luego git rebase --continue. Si el commit no vale el esfuerzo, git rebase --skip lo descarta; --abort cancela todo. Resolver un commit cada vez mantiene los conflictos pequeños — una lista de tareas llena de squash y reordenamientos es lo que convierte un conflicto en cinco.