Ejecutó git pull y, en lugar de los cambios esperados, la terminal le mostró una línea roja: fatal: refusing to merge unrelated histories. El proyecto no se actualizó, los commits no se descargaron y usted se quedó preguntándose si rompió el repositorio.

No, no lo rompió. Git simplemente se niega a mezclar dos historias independientes, y este es un comportamiento intencional, no un error. En cinco minutos no solo entenderá por qué ocurre este error, sino que también aprenderá a solucionarlo en cualquier situación: en el primer push, tras perder la carpeta .git y al fusionar proyectos dispares.

💡 Resumen rápido:

• Cuándo Git se niega a fusionar ramas no relacionadas y por qué esto es correcto
• La bandera --allow-unrelated-histories, una solución universal para pull, merge y el primer push
• Escenarios paso a paso: clonación sin historial, repositorio nuevo, rebase y force-push
• Qué hacer si la bandera no ayuda y cómo evitar este error en el futuro

Qué significa el error y por qué Git lo lanza

Git rastrea el historial mediante una cadena de commits. Cada commit referencia a su padre, construyendo un grafo que Git usa para entender qué vino de dónde. Cuando usted hace git merge, Git busca un ancestro común entre dos ramas y calcula la diferencia a partir de él.

Pero a veces simplemente no hay un ancestro común. Dos grafos de commits no se intersectan, como dos proyectos separados que nunca supieron el uno del otro. En tal situación, Git se niega a fusionar historias a ciegas y lanza:

1
fatal: refusing to merge unrelated histories

Esto no es un error en el sentido habitual. Es una protección: Git le está diciendo: «No entiendo cómo se relacionan estas dos historias, así que no voy a adivinar». La solución existe y está incorporada en Git a partir de la versión 2.9.0 (publicada en junio de 2016).

Dos escenarios típicos que conducen al error

Primer escenario, **corrupción o eliminación de la carpeta **.git. Usted clonó un proyecto, trabajó con el código, pero la carpeta .git se eliminó (accidentalmente, por un antivirus o al copiar sin archivos ocultos). Git pierde todo el historial local y, al intentar git push o git pull, trata su directorio de trabajo como un proyecto completamente nuevo, sin relación con el repositorio remoto.

Segundo escenario, un repositorio nuevo se encuentra con uno existente. Usted hizo git init, añadió varios commits localmente y luego intentó conectar un repositorio remoto que ya tiene su propio historial. Git ve dos grafos de commits independientes y se niega a mezclarlos. Esto sucede a menudo cuando comienza un proyecto desde cero y luego decide subirlo a GitHub sobre un repositorio existente, o al transferir código de un proyecto a otro.

Ambos escenarios se resuelven con el mismo mecanismo, pero antes de aplicarlo, debe entender qué quiere lograr exactamente: fusionar dos historias en una o reemplazar completamente una historia por otra.

Solución: la bandera --allow-unrelated-histories

La clave para solucionar esto es la bandera --allow-unrelated-histories. Le indica explícitamente a Git: «Sé que estas ramas no tienen un ancestro común y quiero fusionarlas conscientemente». La bandera funciona con ambos comandos principales, git pull y git merge.

**Para **git pull (el caso más común):

1
git pull origin main --allow-unrelated-histories

Reemplace main por el nombre de su rama si es diferente (master, develop, etc.). Git creará un commit de fusión que conecte las dos historias independientes. Es probable que se abra un editor para el mensaje del commit; describa por qué está fusionando las historias, guarde y cierre el editor.

**Para **git merge (cuando las ramas son locales):

1
git merge feature-branch --allow-unrelated-histories

Después de una fusión exitosa, Git le pedirá que suba el resultado. No olvide hacerlo:

1
git push origin main

Matiz importante: --allow-unrelated-histories no elimina los conflictos de fusión. Si ambas ramas tienen archivos con los mismos nombres, Git aún le pedirá que resuelva los conflictos manualmente; la bandera solo maneja la conexión de historias, no el contenido de los archivos.

Escenarios paso a paso para diferentes situaciones

Situación 1: primer push a un repositorio remoto no vacío

Creó un proyecto localmente (git init → commits) y en GitHub ya existe un repositorio con README.md y .gitignore. Un git push directo no funcionará porque la rama remota contiene commits que usted no tiene.

Secuencia correcta:

Primero, descargue el historial remoto y fusiónelo con su local:

1
git pull origin main --allow-unrelated-histories

Resuelva los conflictos si los hay (normalmente conflictos en README.md), haga un commit de fusión y luego:

1
git push origin main

Situación 2: recuperación tras perder.git

La carpeta .git se eliminó, pero el directorio de trabajo está intacto. Puede restaurar la conexión con el repositorio remoto sin perder los cambios no confirmados:

1
git init
2
git remote add origin <repository-url>
3
git fetch origin
4
git reset --mixed origin/main

El comando git reset --mixed sincroniza el índice de Git con la rama remota, pero mantiene todos sus archivos de trabajo sin tocar. Después de esto, añada los cambios y haga un nuevo commit:

1
git add .
2
git commit -m "Recovery after losing .git"
3
git push origin main

Este enfoque es preferible a --allow-unrelated-histories porque no crea un commit de fusión artificial y mantiene el historial limpio.

Situación 3: rebase con historias no relacionadas

El comando git rebase también puede lanzar este error, especialmente al usar la bandera --preserve-merges (ahora reemplazada por --rebase-merges). Solución: añada --allow-unrelated-histories:

1
git rebase --rebase-merges --allow-unrelated-histories main

Pero tenga cuidado: el rebase reescribe el historial y, si alguien más está trabajando con esta rama, les creará problemas. Para ramas compartidas, prefiera siempre merge.

Qué hacer si la bandera no ayuda

A veces --allow-unrelated-histories funciona sin errores, pero el resultado no es el que esperaba.

Problema: el commit de fusión ensucia el historial. Si fusionó dos proyectos grandes, el grafo de commits se vuelve difícil de leer. En este caso, considere una alternativa: transferir archivos con preservación del historial mediante git format-patch y git am:

1
git format-patch --root -o patches/ HEAD
2
git am patches/*.patch

Problema: después de la fusión el proyecto no compila. Fusionar historias no relacionadas puede provocar archivos de configuración duplicados, conflictos de dependencias o versiones de paquetes incompatibles. Después de --allow-unrelated-histories, verifique siempre: dependencias (npm install / composer install), archivos de configuración (.env, config/), rutas e importaciones en el código. Es mejor dedicar cinco minutos a la verificación ahora que lidiar con builds fallidas en CI más tarde.

Problema: cambió de opinión. Puede deshacer una fusión de historias no relacionadas de la forma estándar: git reset --hard HEAD~1 (si aún no ha subido el resultado) o git revert -m 1 HEAD (si ya lo subió).

Cómo evitar el error en el futuro

Tres reglas simples que le ahorrarán este error en el trabajo diario.

No elimine .git sin necesidad absoluta. Si necesita copiar código sin historial, use git archive o copie los archivos excluyendo la carpeta oculta .git de forma consciente, no accidental.

No cree un repositorio nuevo dentro de uno existente. Si necesita extraer parte del código a un proyecto separado, use git subtree split o git filter-branch (ahora se recomienda git filter-repo). Estas herramientas preservarán el historial de los archivos necesarios y Git sabrá de dónde vinieron.

Antes de hacer git init en una carpeta con código, verifique siempre si ya existe un repositorio allí: git status. Si Git responde fatal: not a git repository, puede inicializar. Si muestra el estado, ya está dentro de un repositorio existente y git init no es necesario aquí.

Para quienes empiezan a trabajar con Git, recomendamos nuestra guía "Guía de Git para principiantes", que recorre paso a paso las claves SSH, la creación de repositorios y el flujo de trabajo completo en GitHub. Y si Git aún no está instalado, comience con la guía "Cómo instalar Git en Windows".

⁉️🤔 Preguntas frecuentes

¿Qué versiones de Git soportan --allow-unrelated-histories?

La bandera apareció en Git 2.9.0 (junio de 2016) y está presente en todas las versiones posteriores. Si su versión de Git es más antigua, actualícela: el comando git --version mostrará la versión actual, y git update-git-for-windows (en Windows) o el gestor de paquetes de su sistema la actualizarán a la versión más reciente. La forma más fácil de verificar la versión de Git es el comando git --version en la terminal. A mediados de 2026, la rama actual es 2.48+. Si está en Windows y Git se instaló hace mucho tiempo, descargue un instalador nuevo desde git-scm.com; la actualización automática en versiones antiguas funcionaba de forma inestable.

¿Puedo usar la bandera directamente con git push?

No, git push no acepta --allow-unrelated-histories. Push no crea una fusión, solo envía commits existentes. El error de «unrelated histories» en push significa que su rama local y la remota han divergido a nivel de historial. Solución: primero git pull --allow-unrelated-histories, resuelva conflictos y solo entonces git push. Formalmente, --allow-unrelated-histories funciona con git fetch + git merge y con git pull (que internamente hace fetch + merge). Push sigue siendo una operación separada que se realiza después de una fusión exitosa. No intente eludir esto con --force, perderá los commits de otras personas en el repositorio remoto.

¿Qué es mejor para un historial limpio: merge o rebase?

Para conectar historias no relacionadas, definitivamente merge. Rebase en este contexto crea más problemas de los que resuelve: intenta reaplicar commits de una rama sobre otra, pero sin un ancestro común esto genera conflictos en cada commit. Merge con --allow-unrelated-histories hace exactamente lo necesario: crea un punto de conexión entre dos grafos, después de lo cual el historial queda unificado. Excepción: cuando intencionalmente quiere reescribir el historial y sabe exactamente lo que hace. Por ejemplo, al transferir código de un repositorio a otro con limpieza de commits antiguos. En este caso, git rebase --allow-unrelated-histories puede tener sentido, pero para el trabajo diario elija merge.

Perdí la carpeta .git, pero tengo cambios sin commit. ¿Los perderé?

No, no los perderá. La carpeta .git en sí contiene solo el historial y los metadatos de Git, no sus archivos de trabajo. Todos los archivos modificados, nuevos e incluso no confirmados permanecerán en el directorio de trabajo sin tocar. El procedimiento de recuperación se describe en la «Situación 2» anterior: git init → git remote add → git fetch → git reset --mixed. Punto clave: use exactamente --mixed, no --hard. La bandera --mixed restablece el índice pero preserva todos los cambios en los archivos. Si no está seguro, haga una copia de seguridad de toda la carpeta del proyecto antes de la recuperación; esto tomará diez segundos y eliminará por completo el riesgo de pérdida de datos en cualquier situación no estándar.

El error ocurre al clonar a través de un IDE. ¿Es el mismo problema?

Sí, el mismo. Algunos IDE (por ejemplo, PHPStorm, Visual Studio, versiones antiguas de IntelliJ) al crear un proyecto desde una plantilla inicializan un nuevo repositorio Git y luego intentan conectar un remoto. Este es exactamente el segundo escenario del inicio del artículo. La solución es la misma: abra una terminal en la carpeta del proyecto y ejecute git pull origin main --allow-unrelated-histories. Después de la fusión manual, el IDE detectará el nuevo estado automáticamente; solo actualice la ventana del proyecto o haga clic en Refrescar en el panel de Git.

¿Debería temerle al error «unrelated histories»?

No. Este es uno de los errores más seguros de Git: no corrompe datos, no elimina archivos y no impide continuar trabajando. La bandera --allow-unrelated-histories no es un parche ni una solución provisional, sino una capacidad documentada añadida específicamente por los desarrolladores de Git para los casos en que conscientemente desea conectar dos historias independientes.

Una vez que domine este comando, obtendrá una herramienta poderosa: ahora puede fusionar proyectos de cualquier grado de aislamiento, transferir código entre repositorios y restaurar el trabajo tras perder .git, todo sin pánico y sin recrear el repositorio desde cero. Si Git le enseñó algo hoy, es que «fatal» en sus mensajes no significa «fatal para el proyecto», significa «no voy a adivinar, dígame explícitamente qué hacer».