Los problemas que más se repiten al trabajar con otras personas: ramas que se quedan atrás, conflictos en el lockfile, pull requests enormes, hotfixes con una release en curso, main roto. Cada uno con el flujo recomendado, animado paso a paso.
Cómo usar esta página
Busca tu problema con tus palabras o elige un tema. Cada caso dice qué ves, por qué pasa, el flujo para salir paso a paso (con el grafo de commits cambiando en cada comando) y cómo evitar que se repita. Si lo tuyo es deshacer un error puntual, como un commit o una rama borrada, mira Rescate.
Nada coincide. Prueba con «conflicto», «rama», «release», «push» o «lento».
Integrar cambios
Con cuidado
Mi rama lleva semanas sin integrarse y ahora el merge es un infierno
Lo que ves
Al traer main aparecen conflictos en decenas de archivos, y el pull request dice que la rama tiene conflictos.
CONFLICT (content): Merge conflict in src/carrito.js
Automatic merge failed; fix conflicts and then commit the result.
Por qué pasa. Cada día que la rama no integra main, las dos historias se separan un poco más. Los conflictos no crecen de a uno: se acumulan y se cruzan entre sí.
El flujo recomendado
bash
git config --global rerere.enabled true # una sola vez
git fetch origin
git switch feature
git merge origin/main
# resuelve los conflictos
git add .
git commit --no-edit
git push
Otra salida
Si la rama es tan grande que el merge no tiene sentido, pártela en pull requests pequeños (mira «Mi pull request es enorme») y esconde lo incompleto detrás de un feature flag.
Para que no vuelva a pasar
Ramas de uno o dos días e integrar main a diario. Lo que no esté listo entra apagado con un feature flag en vez de esperar en una rama.
git pull se detiene y te pide elegir cómo reconciliar las ramas.
hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint: git config pull.rebase false # merge
hint: git config pull.rebase true # rebase
hint: git config pull.ff only # fast-forward only
fatal: Need to specify how to reconcile divergent branches.
Por qué pasa. Tienes commits locales y el remoto también tiene commits nuevos. Git puede unirlos con un merge o con un rebase, y desde Git 2.33 no elige por ti si no lo configuraste.
El flujo recomendado
bash
git pull --rebase # esta vez
git config --global pull.rebase true # siempre
git config --global rebase.autoStash true
Otra salida
Si prefieres no reescribir nunca tus commits, git config --global pull.rebase false hace merge. Y pull.ff only es la opción más estricta: solo trae cambios si no hay nada que reconciliar.
Para que no vuelva a pasar
Configura pull.rebase una vez en cada máquina, y haz git pull antes de empezar a trabajar.
! [rejected] main -> main (fetch first)
error: failed to push some refs to 'github.com:equipo/tienda.git'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. This is usually caused by another repository pushing to
hint: the same ref. If you want to integrate the remote changes, use
hint: 'git pull' before pushing again.
Por qué pasa. Alguien subió commits a esa rama después de tu último fetch. Si Git aceptara tu push, esos commits se perderían.
El flujo recomendado
bash
git pull --rebase
# si hay conflictos: resuélvelos, git add, git rebase --continue
git push
Para que no vuelva a pasar
Haz git pull antes de empezar y antes de subir. En ramas compartidas, trabaja en una rama propia y entra por pull request.
Siempre tengo conflictos en package-lock.json (o en otro lockfile)
Lo que ves
Casi cada pull request choca en package-lock.json, pnpm-lock.yaml o yarn.lock, con cientos de líneas en conflicto.
CONFLICT (content): Merge conflict in package-lock.json
Por qué pasa. El lockfile lo genera el administrador de paquetes. Si dos ramas agregan dependencias a la vez, las dos reescriben el mismo archivo enorme.
Dos ramas crearon migraciones de base de datos y ahora CI falla
Lo que ves
El merge entra sin conflictos, pero las pruebas o el ORM fallan: hay dos migraciones con el mismo número o el orden quedó roto.
Por qué pasa. Para Git son dos archivos distintos, así que no ve conflicto. El problema es de orden: las dos migraciones salieron de la misma base y ninguna conoce a la otra.
El flujo recomendado
bash
git fetch origin
git rebase origin/main
# renumera o regenera tu migración sobre la última de main
git mv db/0042_cupones.sql db/0043_cupones.sql
git commit --amend --no-edit
git push --force-with-lease
Otra salida
Algunas herramientas crean una migración de unión en vez de renumerar (por ejemplo alembic merge o makemigrations --merge en Django). Revisa la documentación de la tuya.
Para que no vuelva a pasar
Nombres con fecha y hora en vez de números correlativos, un check en CI que falle si hay dos migraciones en paralelo, y una merge queue para que cada PR se pruebe contra lo que entra antes.
Miles de líneas en decenas de archivos. La revisión tarda días y al final se aprueba sin leer.
Por qué pasa. Mezclaste refactor, funcionalidad y pruebas en una sola rama, y la abriste tarde. Revisar bien cuesta proporcionalmente más cuanto más grande es el cambio.
GitHub tiene pull requests apilados de forma nativa desde octubre de 2026 (extensión gh stack: gh stack init, gh stack add, gh stack submit). Solo funcionan con ramas del mismo repositorio, no entre forks.
Para que no vuelva a pasar
Separa el refactor en su propio PR antes de la funcionalidad, y abre el PR temprano como borrador. Una guía útil: si no se revisa en 20 minutos, es demasiado grande.
Necesito empezar algo que depende de un PR que todavía no se fusiona
Lo que ves
Tu siguiente tarea necesita el código de un PR en revisión. Si esperas, te quedas parado; si partes de main, no tienes lo que necesitas.
Por qué pasa. Las ramas no tienen que salir de main. Puedes apilar una sobre otra. Lo difícil es mantener la pila al día cuando la de abajo cambia por la revisión.
El flujo recomendado
bash
git switch -c parte-2 parte-1 # apila sobre el PR pendiente
# ...cuando parte-1 cambia por la revisión:
git commit --fixup=<commit-de-parte-1>
git rebase -i --autosquash --update-refs main
git push --force-with-lease origin parte-1 parte-2
# para siempre:
git config --global rebase.updateRefs true
Otra salida
Si el PR de abajo se fusiona con squash, rebasa la parte de arriba sobre main con git rebase --onto main parte-1 parte-2, para no arrastrar los commits viejos. En GitHub también puedes usar los PRs apilados nativos (gh stack).
Para que no vuelva a pasar
Pide que el PR de abajo se revise primero y mantén las pilas cortas: dos o tres partes.
Mi rama está llena de commits «wip» y «arreglo» antes del PR
Lo que ves
La historia de tu rama dice «wip», «ahora sí», «typo», «fix test». Quien revisa no entiende el cambio commit por commit.
Por qué pasa. Commiteas mientras trabajas (está bien). Lo que falta es ordenar antes de pedir revisión: juntar cada arreglo con el commit al que pertenece.
El flujo recomendado
bash
git commit --fixup=<commit> # al arreglar algo de un commit anterior
git rebase -i --autosquash main
git push --force-with-lease
# para no escribir --autosquash:
git config --global rebase.autoSquash true
Otra salida
Si tu equipo fusiona con «Squash and merge», la historia de la rama no llega a main: basta con que el título del PR sea claro.
Para que no vuelva a pasar
Usa git commit --fixup desde el principio, y git add -p para separar cambios distintos en commits distintos.
Hay un bug en producción y main ya tiene cosas que no pueden salir
Lo que ves
Producción está rota. Necesitas publicar un arreglo ya, pero main tiene funcionalidades a medio probar que no pueden salir todavía.
Por qué pasa. Lo que corre en producción es una versión anterior (un tag o una rama de release), no lo último de main. El arreglo tiene que llegar a esa versión.
El flujo recomendado
bash
# 1) el arreglo entra a main con un PR normal
# 2) llévalo a la versión que corre en producción:
git switch release/1.4
git cherry-pick -x <commit-del-arreglo>
git tag v1.4.1
git push origin release/1.4 v1.4.1
# si no tienes rama de release, créala desde el tag:
git switch -c hotfix/1.4.1 v1.4.0
Otra salida
Si no hay rama de release, créala desde el tag que está en producción (git switch -c hotfix/1.4.1 v1.4.0), aplica el arreglo allí, etiqueta y despliega. Después lleva el arreglo a main.
Para que no vuelva a pasar
Etiqueta cada versión que despliegas y esconde lo incompleto con feature flags: así main siempre se puede publicar y el hotfix es un despliegue normal.
CI está en rojo en main y nadie puede fusionar nada. El PR pasó sus pruebas, pero junto con lo demás falla.
Por qué pasa. El PR se probó contra una versión vieja de main. Por separado, cada cambio funcionaba; juntos no. Otras veces alguien saltó las pruebas.
El flujo recomendado
bash
git switch main && git pull
git revert -m 1 <commit-del-merge> # si el PR se fusionó con merge commit
git revert <commit> # si se fusionó con squash
git push # o un PR rápido si main está protegida
# después, para encontrar la causa:
git bisect start <malo> <bueno>
git bisect run npm test
Para que no vuelva a pasar
Una merge queue (GitHub) o merge train (GitLab): cada PR se prueba junto con main y con los PRs que entran antes, y solo se fusiona si todo pasa. Como mínimo, exige que la rama esté al día antes de fusionar.
Revertí un merge y al volver a fusionar la rama faltan cambios
Lo que ves
Corregiste la rama y la volviste a fusionar, pero en main solo aparece el arreglo: los cambios originales no están.
Por qué pasa. El revert deshace los archivos, pero no la historia: para Git, los commits de la rama ya están en main, así que el segundo merge solo trae lo nuevo.
El flujo recomendado
bash
# 1) revierte el commit que revirtió el merge
git revert <commit-del-revert>
# 2) vuelve a fusionar la rama corregida
git merge cupones
Otra salida
Si reescribiste la rama desde cero (un rebase que creó commits nuevos), no hace falta revertir el revert: son commits distintos y el merge los trae. La documentación de Git lo explica en «How to revert a faulty merge», y advierte que no se revierte un revert sin pensarlo.
Para que no vuelva a pasar
Para funcionalidades grandes, un feature flag permite apagar sin revertir merges. Y PRs pequeños: revertir uno pequeño es mucho menos delicado.
Tengo que publicar solo algunas de las funcionalidades que ya están en main
Lo que ves
En main hay tres funcionalidades. Negocio quiere publicar dos y dejar la tercera para el mes siguiente.
Por qué pasa. Integrar el código y lanzar la funcionalidad son dos decisiones distintas, pero el flujo las trata como una: lo que está en main sale.
El flujo recomendado
bash
# con feature flags: publica main tal cual
git tag v2.0.0
git push origin v2.0.0
# sin flags (más frágil): arma la release con copias
git switch -c release/2.0 <commit-base>
git cherry-pick -x <commit-P> <commit-Q>
# corre TODAS las pruebas en la rama release
Otra salida
Si no tienes feature flags, el cherry-pick sirve, pero corre todas las pruebas en la rama de release y anota con -x de dónde vino cada commit.
Para que no vuelva a pasar
Feature flags desde el inicio para todo lo que tarde más de unos días. Y borra los flags cuando la funcionalidad ya esté encendida para todos: si se acumulan, se vuelven deuda.
Por qué pasa.--force reemplaza la rama remota por la tuya sin mirar qué había. Si alguien subió algo después de tu último fetch, se pierde del remoto.
El flujo recomendado
bash
# en un clon que tenga el trabajo perdido (el de quien lo subió, o uno que hizo fetch antes):
git reflog show origin/feature
git branch rescate <hash-anterior-al-force>
git switch feature
git cherry-pick <hash> # o git merge rescate
git push
# de ahora en adelante:
git push --force-with-lease --force-if-includes
Otra salida
Si nadie tiene el commit en su clon, GitHub muestra el historial de push de la rama en la actividad del repositorio, y desde ahí puedes recuperar el hash.
Para que no vuelva a pasar
Nunca --force a secas: usa --force-with-lease --force-if-includes. Bloquea el force push en las ramas protegidas, y no rebasees ramas que usa más de una persona.
Subí una contraseña, una clave o un token al repositorio
Lo que ves
Un aviso de secret scanning, un correo de tu proveedor de nube, o lo ves tú: el secreto está en un commit que ya está en GitHub.
Por qué pasa. Un archivo .env o una clave escrita en el código entró en un commit. Borrarlo en un commit nuevo no basta: sigue en la historia.
El flujo recomendado
bash
# 1) revoca y cambia el secreto en el servicio (lo más importante)
# 2) bórralo de toda la historia (requiere git-filter-repo):
git filter-repo --sensitive-data-removal --invert-paths --path .env
git push --force --mirror origin
# 3) el equipo vuelve a clonar el repositorio
Otra salida
Si el secreto ya está revocado y no es sensible en sí (por ejemplo, una clave de prueba sin permisos), puedes dejar la historia como está. Reescribirla tiene costo: hashes nuevos, firmas que se pierden y clones que hay que rehacer.
Para que no vuelva a pasar
.env en .gitignore desde el primer commit, secretos en variables de entorno o en un gestor de secretos, push protection de GitHub activado y un hook de pre-commit con un escáner como gitleaks.
GitHub rechaza mi push por archivos grandes (o el repo pesa demasiado)
Lo que ves
El push falla por un archivo de más de 100 MB, o clonar el repositorio tarda muchísimo por diseños, videos o binarios versionados.
remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.
Por qué pasa. Git guarda cada versión completa de cada archivo. Con binarios que cambian seguido, el repositorio crece en cada commit y nunca se achica.
El flujo recomendado
bash
git lfs install
git lfs track "*.psd"
git add .gitattributes
git commit -m "guarda los .psd en LFS"
# solo si ya hay binarios en la historia (la reescribe):
git lfs migrate import --include="*.psd" --everything
git push --force-with-lease --all origin
Otra salida
Si solo necesitas clonar rápido un repo pesado que no es tuyo: git clone --filter=blob:none (clon parcial) descarga el contenido de los archivos solo cuando hace falta.
Para que no vuelva a pasar
LFS desde el primer día para diseños, videos y binarios; los artefactos de build en .gitignore, nunca en el repositorio.
Pon reglas de tamaño desde temprano (nada de binarios ni artefactos de build en el repo) y mide git status de vez en cuando: si pasa de un segundo, revisa estas opciones.