Al intentar hacer git pull, te encuentras con el siguiente error:
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
Este mensaje indica que tu rama local y la rama remota han divergido: ambas tienen commits únicos que la otra no tiene. Git necesita que decidas cómo combinar estos cambios.
La divergencia sucede cuando:
- Trabajas localmente y realizas commits en tu rama
main
- Mientras tanto, cambios se fusionan en el remoto (por ejemplo, a través de Pull Requests)
- Ambas ramas tienen commits exclusivos que la otra no posee
Ejemplo visual:
Local: A---B---C---L1
^(tu commit local)
Remote: A---B---C---R1---R2---R3
^(commits del remoto vía PR)
Antes de resolver, es crucial entender qué ha divergido.
git fetch origin main --tags
Este comando descarga los cambios del remoto sin fusionarlos.
Verifica qué commits están únicamente en cada lado:
# Commits que tienes localmente pero no están en el remoto
git log origin/main..main --oneline
# Commits que están en el remoto pero no tienes localmente
git log main..origin/main --oneline
# Ver el commit actual local
git rev-parse HEAD
# Ver el commit actual remoto
git rev-parse origin/main
En nuestro caso, obtuvimos:
--- Commits en local, no en remoto ---
81e3b93 feat: add new feature for data processing
--- Commits en remoto, no en local ---
9d3e3e9 Merge pull request #42 from team/feature/update-docs
285a538 Complete documentation review - all documents validated
000b9cb Fix configuration and add new parameters
a7694d3 Initial implementation plan
Interpretación: El remoto tiene un PR fusionado con 4 commits que no tenemos localmente, y nosotros tenemos 1 commit local que el remoto no tiene.
Existen tres estrategias principales:
Cuándo usarlo: Cuando trabajas con un equipo y quieres preservar toda la historia, incluyendo los merge commits de PRs.
Ventajas:
- ✅ Preserva la historia completa (incluidos merge commits)
- ✅ Muestra claramente cuándo se integraron features
- ✅ Más seguro: no reescribe historia
Desventajas:
- ⚠️ Crea un commit de merge adicional
- ⚠️ Historia no completamente lineal
Comando:
git merge origin/main --no-edit
Si prefieres revisar/editar el mensaje de merge:
Cuándo usarlo: Cuando trabajas solo o en una feature branch que aún no has compartido públicamente.
Ventajas:
- ✅ Historia completamente lineal
- ✅ Más limpia para revisar con
git log
Desventajas:
- ⚠️ Reescribe commits locales (cambian sus SHAs)
- ⚠️ Puede causar problemas si ya compartiste estos commits
- ⚠️ Pierdes el contexto de cuándo se integró el PR remoto
Comando:
Cuándo usarlo: Cuando quieres asegurarte de que solo hagas pull si no hay divergencia.
Comando:
git config pull.ff only
git pull
Si hay divergencia, fallará y tendrás que decidir merge o rebase manualmente.
# Sincronizar con remoto
git fetch origin main --tags
# Ver divergencias
echo "--- Commits locales únicos ---"
git log origin/main..main --oneline
echo "--- Commits remotos únicos ---"
git log main..origin/main --oneline
Para equipos colaborativos con PRs, merge es la opción más segura:
git merge origin/main --no-edit
Si hay conflictos, Git te lo indicará:
Auto-merging some-file.md
CONFLICT (content): Merge conflict in some-file.md
Automatic merge failed; fix conflicts and then commit the result.
Pasos para resolver:
a) Abre el archivo con conflictos:
<<<<<<< HEAD
Tu versión local
=======
Versión del remoto
>>>>>>> origin/main
b) Edita manualmente para quedarte con el contenido correcto
c) Marca como resuelto:
d) Completa el merge:
git commit -m "Merge origin/main into main"
# Ver el log reciente
git log --oneline --graph -10
Deberías ver algo como:
* 3e1ed57 (HEAD -> main) Merge remote-tracking branch 'origin/main' into main
|\
| * 9d3e3e9 (origin/main) Merge pull request #42
| * 285a538 Complete documentation review
| * 000b9cb Fix configuration parameters
| * a7694d3 Initial implementation plan
* | 81e3b93 feat: add new feature for data processing
|/
* d140dce feat: improved monthly workflow
Salida esperada:
Enumerating objects: 15, done.
Counting objects: 100% (12/12), done.
Delta compression using up to 8 threads
Compressing objects: 100% (7/7), done.
Writing objects: 100% (7/7), 1.08 KiB | 1.08 MiB/s, done.
Total 7 (delta 5), reused 0 (delta 0)
remote: Resolving deltas: 100% (5/5), completed with 4 local objects.
To https://github.com/tu-usuario/tu-repositorio.git
9d3e3e9..3e1ed57 main -> main
Si tienes workflows de CI/CD u otros archivos críticos, verifica su integridad:
# Buscar un patrón específico en un archivo
grep -n "specific_pattern" .github/workflows/deploy.yml
# O leer el archivo completo
cat .github/workflows/deploy.yml
# Ambos deberían apuntar al mismo commit ahora
git rev-parse HEAD
git rev-parse origin/main
Si quieres establecer una estrategia por defecto para futuros git pull:
git config pull.rebase false
git config pull.rebase true
Añade --global:
git config --global pull.rebase false
# Ejecutar cada mañana o antes de empezar a trabajar
git fetch origin
Esto te mantiene informado de cambios remotos sin afectar tu trabajo local.
En lugar de trabajar directamente en main:
git checkout -b feature/my-feature
# ... hacer commits ...
git push origin feature/my-feature
# Abrir PR en GitHub
Esto evita divergencias en main.
git fetch origin
git status
# Si hay cambios remotos, decide merge o rebase
git pull
# Ahora puedes pushear
git push
# ❌ NUNCA en main compartido
git push --force origin main
# ✅ OK solo en tus feature branches
git push --force origin feature/my-feature
# Ver el reflog (historial de cambios de HEAD)
git reflog
# Volver a un estado anterior
git reset --hard HEAD@{2}
# ⚠️ CUIDADO: Esto descarta tus commits locales permanentemente
git reset --hard origin/main
# Guardar cambios temporalmente
git stash
# Sincronizar con remoto
git pull
# Recuperar tus cambios
git stash pop
La divergencia de ramas es un escenario común en equipos colaborativos. La clave está en:
- Entender qué ha divergido (análisis con
git log)
- Elegir la estrategia correcta (merge para equipos, rebase para trabajo local)
- Verificar el resultado antes de hacer push
En entornos colaborativos con Pull Requests, merge es generalmente la opción más segura ya que preserva la historia completa y evita reescribir commits que otros pueden estar usando como base.
