?!
Referencia · Problemas

Problemas comunes con Git en equipo

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.

¿Qué te está pasando?
  1. Mi rama lleva semanas sin integrarse y ahora el merge es un infiernoCon cuidado
  2. Siempre tengo conflictos en package-lock.json (o en otro lockfile)Riesgo bajo
  3. Dos ramas crearon migraciones de base de datos y ahora CI fallaCon cuidado
  4. Mi pull request es enorme y nadie lo revisaRiesgo bajo
  5. Necesito empezar algo que depende de un PR que todavía no se fusionaCon cuidado
  6. Mi rama está llena de commits «wip» y «arreglo» antes del PRRiesgo bajo
  7. Hay un bug en producción y main ya tiene cosas que no pueden salirCon cuidado
  8. Fusionaron un PR y ahora main está rotoCon cuidado
  9. Revertí un merge y al volver a fusionar la rama faltan cambiosRiesgo alto
  10. Tengo que publicar solo algunas de las funcionalidades que ya están en mainCon cuidado
  11. git pull dice «You have divergent branches»Riesgo bajo
  12. git push fue rechazado: «Updates were rejected»Riesgo bajo
  13. Mi fork quedó desactualizado respecto del repositorio originalRiesgo bajo
  14. Hice commits en main en vez de en mi ramaRiesgo bajo
  15. Un force push borró el trabajo de un compañeroRiesgo alto
  16. Subí una contraseña, una clave o un token al repositorioRiesgo alto
  17. GitHub rechaza mi push por archivos grandes (o el repo pesa demasiado)Con cuidado
  18. git status y git fetch tardan mucho en un repositorio giganteRiesgo bajo

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.

Más a fondo en Intermedio →
Riesgo bajo

git pull dice «You have divergent branches»

Lo que ves

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.

Más a fondo en Intermedio →
Riesgo bajo

git push fue rechazado: «Updates were rejected»

Lo que ves

El push falla y Git te sugiere hacer git pull.

 ! [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.

Más a fondo en Intermedio →
Riesgo bajo

Mi fork quedó desactualizado respecto del repositorio original

Lo que ves

Tu fork dice que está muchos commits atrás del original, y tus pull requests chocan con cambios que no tienes.

Por qué pasa. Un fork es una copia: no se actualiza solo. Tu clon conoce tu fork (origin) pero no el original, hasta que lo agregas como otro remoto.

El flujo recomendado

bash
git remote add upstream https://github.com/proyecto/tienda.git   # una vez
git fetch upstream
git switch main
git merge --ff-only upstream/main
git push origin main

# con GitHub CLI:
gh repo sync tu-usuario/tienda -b main
Otra salida

En GitHub, el botón «Sync fork» o gh repo sync hacen lo mismo desde la web o la terminal. Si hay conflictos, no sincronizan.

Para que no vuelva a pasar

No trabajes en el main de tu fork: una rama por pull request. Así main siempre se actualiza con fast-forward.

Más a fondo en Intermedio →

Conflictos que se repiten

Riesgo bajo

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.

El flujo recomendado

bash
git merge origin/main
# 1) resuelve package.json a mano (deja ambas dependencias)
git restore --theirs package-lock.json
npm install --package-lock-only
git add package.json package-lock.json
git commit --no-edit
Otra salida

Con pnpm o yarn la idea es la misma: resuelve package.json y vuelve a correr pnpm install o yarn install para regenerar el lockfile.

Para que no vuelva a pasar

Pull requests pequeños y las actualizaciones de dependencias agrupadas en un solo PR (Renovate o Dependabot), en vez de que cada rama las toque.

Más a fondo en Intermedio →
Con cuidado

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.

Más a fondo en Avanzado →

Pull requests y revisión

Riesgo bajo

Mi pull request es enorme y nadie lo revisa

Lo que ves

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.

El flujo recomendado

bash
git switch -c parte-1 main
git restore --source=feature -- src/api/
git commit -m "api de cupones"

git switch -c parte-2
git restore --source=feature -- src/ui/
git commit -m "pantalla de cupones"

git push -u origin parte-1 parte-2
gh pr create --base main --head parte-1
gh pr create --base parte-1 --head parte-2
Otra salida

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.

Más a fondo en Estrategias →
Con cuidado

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.

Más a fondo en Avanzado →
Riesgo bajo

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.

Más a fondo en Avanzado →

Releases y producción

Con cuidado

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.

Más a fondo en Estrategias →
Con cuidado

Fusionaron un PR y ahora main está roto

Lo que ves

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.

Más a fondo en Avanzado →
Riesgo alto

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.

Más a fondo en Avanzado →
Con cuidado

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.

Más a fondo en Estrategias →

Ramas compartidas

Riesgo bajo

Hice commits en main en vez de en mi rama

Lo que ves

Trabajaste directo en main y no te diste cuenta. Si main está protegida, el push falla.

Your branch is ahead of 'origin/main' by 2 commits.
  (use "git push" to publish your local commits)

Por qué pasa. Olvidaste crear la rama antes de empezar. Mientras no hayas hecho push, se arregla moviendo etiquetas: los commits no cambian.

El flujo recomendado

bash
git switch -c cupones            # la rama nueva se queda con los commits
git branch -f main origin/main   # main vuelve a donde estaba
git push -u origin cupones
Otra salida

Si ya subiste esos commits a main, no reescribas una rama compartida: revierte con git revert y vuelve a aplicar el trabajo desde una rama.

Para que no vuelva a pasar

Protege main en GitHub o GitLab para que no acepte push directos. Y muestra la rama actual en el prompt de tu terminal.

Más a fondo en Avanzado →
Riesgo alto

Un force push borró el trabajo de un compañero

Lo que ves

Los commits que alguien subió a una rama compartida desaparecieron después de un git push --force.

 + 3c4d5e6...7f8a9b0 feature -> feature (forced update)

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.

Más a fondo en Avanzado →

Seguridad y repos grandes

Riesgo alto

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.

Más a fondo en Experto →
Con cuidado

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.

Más a fondo en Experto →
Riesgo bajo

git status y git fetch tardan mucho en un repositorio gigante

Lo que ves

En un monorepo con cientos de miles de archivos, git status tarda varios segundos y clonar lleva media hora.

Por qué pasa. Por defecto Git revisa cada archivo del directorio en cada status y descarga toda la historia al clonar. A escala, las dos cosas pesan.

El flujo recomendado

bash
# repo nuevo:
scalar clone https://github.com/empresa/monorepo.git
# repo existente:
scalar register

# o a mano:
git sparse-checkout set --cone apps/tienda libs/pagos
git config core.fsmonitor true
git config core.untrackedCache true
git config feature.manyFiles true
git maintenance start
Para que no vuelva a pasar

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.

Más a fondo en Experto →