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.
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,fixotypoque 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.
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. Luegogit rebase --continuereanuda 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 --continuelo 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-leasees 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.--autosquashmueve los commitsfixup!ysquash!junto a su objetivo en la lista de tareas, convirtiendogit commit --fixupen 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 rererepuede 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 --rootreescribe hasta el primer commit del repo — útil en repositorios nuevos.GIT_SEQUENCE_EDITOR=true git rebase -i HEAD~3acepta 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ón | Efecto | Usar cuando |
|---|---|---|
| squash | Combina + edita el mensaje | Commits relacionados, quieres un solo mensaje |
| fixup | Combina + descarta el mensaje | Commits WIP, el mensaje sobra |
| reword | Solo edita el mensaje | Corregir una errata, mejorar la claridad |
| edit | Pausa y modifica | Dividir un commit, añadir un archivo olvidado |
| drop | Elimina el commit | Revertir un cambio no deseado |
| exec | Ejecuta un comando | Correr 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 --onelineygit bisectsean realmente útiles meses después. - Usa
squashcuando los mensajes individuales aportan contexto que quieres en el commit final; usafixuppara commitsWIPytypocuyo mensaje es puro ruido. - Haz force-push con
--force-with-lease, nunca con--forcea 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--autosquashmientras 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,developy cualquier rama que tus compañeros hayan descargado están prohibidas —git revertexiste para arreglar historial público. - Ten
git reflogsiempre 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 --forcedonde--force-with-leasese 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
--aborty 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.
--abortdeja la rama exactamente como estaba — no hace falta borrar nada. - Olvidar que
git reflogexiste. Cuando--abortya no es opción, reflog — oORIG_HEAD— aún te devuelve la punta anterior.
Lecturas Recomendadas
- git-rebase — documentación oficial de Git
- Uso de git rebase en la línea de comandos — GitHub Docs
- Referencia de git commit —fixup
- git range-diff — compara dos versiones de una serie de commits
- La receta de flujo de trabajo con Git cubre el modelo de ramas del día a día donde encajan estos comandos, y el documento de estrategia de ramificación te ayuda a dejar escritas las reglas de tu equipo.
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.
Recursos Relacionados
Flujo de trabajo Git: ramas, PRs e historial limpio
Un flujo de trabajo Git práctico para equipos: ramas de feature, pull requests, commits convencionales y cómo elegir el modelo de branching.
GuideEstrategias de Branching en Git Comparadas (GitFlow, GitHub, Trunk)
Trunk-based development, GitFlow, GitHub Flow y GitLab Flow comparados — con un marco de decisión según tamaño de equipo, cadencia de releases y madurez de CI/CD.
DocDocumento de Estrategia de Branching en Git
Una plantilla de documento para definir flujo de trabajo Git, convenciones de ramas, requisitos de merge y procedimientos de release para equipos de ingeniería.
DocPlantilla de Pull Request
Plantilla de pull request completa para estandarizar code reviews y mejorar la calidad de merges.
DocPlantilla de Checklist para Code Review
Checklist estructurada para revisiones de código consistentes y exhaustivas que detectan bugs, mejoran la legibilidad y comparten conocimiento en el equipo.
RecipeGitHub Actions: Ejemplos de Workflows CI/CD y Matriz
Cómo construir y desplegar con GitHub Actions usando workflows, matrices, caché, secrets, environments y workflows reutilizables.