Ajoit git pull, ja odotettujen muutosten sijaan terminaali tervehti sinua punaisella rivillä: fatal: refusing to merge unrelated histories. Projekti ei päivittynyt, committeja ei haettu, ja mietit, hajotitko repositorion.

Et hajottanut. Git yksinkertaisesti kieltäytyy sekoittamasta kahta itsenäistä historiaa, ja tämä on tarkoituksellista toimintaa, ei bugi. Viidessä minuutissa et ainoastaan ymmärrä, miksi tämä virhe ilmenee, vaan opit myös korjaamaan sen missä tahansa tilanteessa: ensimmäisessä pushissa, .git-kansion katoamisen jälkeen ja erillisten projektien yhdistämisessä.

💡 Nopea yleiskatsaus:

• Kun Git kieltäytyy yhdistämästä toisiinsa liittymättömiä haaroja ja miksi tämä on oikein
• --allow-unrelated-histories-lippu, universaali ratkaisu komentoihin pull, merge ja ensimmäiseen pushiin
• Vaiheittaiset skenaariot: kloonaus ilman historiaa, uusi repositorio, rebase ja force-push
• Mitä tehdä, jos lippu ei auta, ja miten välttää tämä virhe tulevaisuudessa

Mitä virhe tarkoittaa ja miksi Git heittää sen

Git seuraa historiaa commit-ketjun avulla. Jokainen commit viittaa edeltäjäänsä ja rakentaa graafin, jota Git käyttää ymmärtääkseen, mistä mikäkin on peräisin. Kun suoritat git merge, Git etsii kahden haaran yhteistä esivanhempaa ja laskee eron siitä.

Mutta joskus yhteistä esivanhempaa ei yksinkertaisesti ole. Kaksi commit-graafia eivät leikkaa toisiaan, kuten kaksi erillistä projektia, jotka eivät koskaan tienneet toisistaan. Tällaisessa tilanteessa Git kieltäytyy yhdistämästä historioita sokeasti ja heittää:

1
fatal: refusing to merge unrelated histories

Tämä ei ole virhe tavanomaisessa mielessä. Se on suoja: Git kertoo sinulle: "En ymmärrä, miten nämä kaksi historiaa liittyvät toisiinsa, joten en arvaa." Ratkaisu on olemassa, ja se on sisäänrakennettu Gitiin versiosta 2.9.0 alkaen (julkaistu kesäkuussa 2016).

Kaksi tyypillistä skenaariota, jotka johtavat virheeseen

Ensimmäinen skenaario, .git-kansion korruptoituminen tai poistuminen. Kloonasit projektin, työskentelit koodin parissa, mutta .git-kansio poistui (vahingossa, virustorjunnan toimesta tai kopioitaessa ilman piilotettuja tiedostoja). Git menettää kaiken paikallisen historian, ja yrittäessään git push tai git pull se kohtelee työhakemistoasi täysin uutena projektina, joka ei liity etärepositorioon.

Toinen skenaario, uusi repositorio kohtaa olemassa olevan. Suoritit git init, teit useita committeja paikallisesti ja yritit sitten yhdistää etärepositorion, jolla on jo oma historiansa. Git näkee kaksi itsenäistä commit-graafia ja kieltäytyy sekoittamasta niitä. Näin käy usein, kun aloitat projektin tyhjästä ja päätät sitten ladata sen GitHubiin olemassa olevan repositorion päälle tai kun siirrät koodia projektista toiseen.

Molemmat skenaariot ratkaistaan samalla mekanismilla, mutta ennen sen soveltamista sinun tulisi ymmärtää, mitä tarkalleen haluat saavuttaa: kahden historian yhdistämisen yhdeksi vai yhden historian korvaamisen kokonaan toisella.

Ratkaisu: --allow-unrelated-histories-lippu

Avain tämän korjaamiseen on --allow-unrelated-histories-lippu. Se kertoo Gitille nimenomaisesti: "Tiedän, että näillä haaroilla ei ole yhteistä esivanhempaa, ja haluan tietoisesti yhdistää ne." Lippu toimii molempien pääkomentojen, git pull ja git merge, kanssa.

Komennolle git pull (yleisin tapaus):

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

Korvaa main haarasi nimellä, jos se on eri (master, develop jne.). Git luo merge-commitin, joka yhdistää kaksi itsenäistä historiaa. Editori todennäköisesti avautuu commit-viestiä varten, kuvaile miksi yhdistät historiat, tallenna ja sulje editori.

Komennolle git merge (kun haarat ovat paikallisia):

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

Onnistuneen mergen jälkeen Git kehottaa sinua pushaamaan tuloksen. Älä unohda tehdä tätä:

1
git push origin main

Tärkeä vivahde: --allow-unrelated-histories ei poista merge-konflikteja. Jos molemmissa haaroissa on samannimisiä tiedostoja, Git pyytää sinua silti ratkaisemaan konfliktit manuaalisesti, lippu käsittelee vain historioiden yhdistämistä, ei tiedostojen sisältöä.

Vaiheittaiset skenaariot eri tilanteisiin

Tilanne 1: ensimmäinen push ei-tyhjään etärepositorioon

Loit projektin paikallisesti (git init → committeja), ja GitHubissa on jo repositorio, jossa on README.md ja .gitignore. Suora git push ei toimi, koska etähaara sisältää committeja, joita sinulla ei ole.

Oikea järjestys:

Hae ensin etähistoria ja yhdistä se paikalliseen:

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

Ratkaise konfliktit, jos niitä on (yleensä README.md-konflikti), tee merge-commit ja sitten:

1
git push origin main

Tilanne 2: palautus.git-kansion katoamisen jälkeen

.git-kansio on poistettu, mutta työhakemisto on ehjä. Voit palauttaa yhteyden etärepositorioon menettämättä committoimattomia muutoksia:

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

Komento git reset --mixed synkronoi Git-indeksin etähaaran kanssa, mutta jättää kaikki työtiedostosi koskemattomiksi. Tämän jälkeen lisää muutokset ja tee uusi commit:

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

Tämä lähestymistapa on parempi kuin --allow-unrelated-histories, koska se ei luo keinotekoista merge-commitia ja pitää historian siistinä.

Tilanne 3: rebase toisiinsa liittymättömien historioiden kanssa

Myös git rebase -komento voi heittää tämän virheen, erityisesti käytettäessä --preserve-merges-lippua (nykyään korvattu lipulla --rebase-merges). Ratkaisu: lisää --allow-unrelated-histories:

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

Mutta ole varovainen: rebase kirjoittaa historian uudelleen, ja jos joku muu työskentelee tämän haaran kanssa, aiheutat heille ongelmia. Jaetuille haaroille suosi aina merge-komentoa.

Mitä tehdä, jos lippu ei auta

Joskus --allow-unrelated-histories toimii ilman virheitä, mutta tulos ei ole sitä, mitä halusit.

Ongelma: merge-commit sotkee historian. Jos yhdistit kaksi suurta projektia, commit-graafista tulee vaikealukuinen. Harkitse tässä tapauksessa vaihtoehtoa: tiedostojen siirtoa historian säilyttäen komentojen git format-patch ja git am avulla:

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

Ongelma: mergen jälkeen projekti ei käänny. Toisiinsa liittymättömien historioiden yhdistäminen voi johtaa päällekkäisiin konfiguraatiotiedostoihin, riippuvuuskonflikteihin tai yhteensopimattomiin pakettiversioihin. Tarkista aina --allow-unrelated-histories-komennon jälkeen: riippuvuudet (npm install / composer install), konfiguraatiotiedostot (.env, config/), polut ja importit koodissa. On parempi käyttää viisi minuuttia tarkistukseen nyt kuin käsitellä epäonnistuneita koontiversioita CI-putkessa myöhemmin.

Ongelma: muutit mielesi. Voit peruuttaa toisiinsa liittymättömien historioiden mergen tavalliseen tapaan: git reset --hard HEAD~1 (jos et ole vielä pushannut tulosta) tai git revert -m 1 HEAD (jos olet jo pushannut).

Miten välttää virhe tulevaisuudessa

Kolme yksinkertaista sääntöä, jotka säästävät sinut tältä virheeltä päivittäisessä työssä.

Älä poista .git-kansiota ilman ehdotonta tarvetta. Jos sinun on kopioitava koodi ilman historiaa, käytä git archive -komentoa tai kopioi tiedostot tietoisesti ilman piilotettua .git-kansiota, ei vahingossa.

Älä luo uutta repositoriota olemassa olevan sisälle. Jos sinun on erotettava osa koodipohjasta erilliseksi projektiksi, käytä git subtree split- tai git filter-branch-komentoa (nykyään suositellaan git filter-repo-työkalua). Nämä työkalut säilyttävät tarvittavien tiedostojen historian, ja Git tietää, mistä ne ovat peräisin.

Ennen git init-komentoa koodikansiossa tarkista aina, onko siellä jo repositorio: git status. Jos Git vastaa fatal: not a git repository, voit alustaa. Jos se näyttää tilan, olet jo olemassa olevan repositorion sisällä, eikä git init-komentoa tarvita täällä.

Niille, jotka vasta aloittavat Gitin käytön, suosittelemme opastamme "Git-opas aloittelijoille", se käy läpi SSH-avaimet, repositorion luomisen ja koko GitHub-työnkulun vaihe vaiheelta. Ja jos Gitiä ei ole vielä asennettu, aloita oppaasta "Kuinka asentaa Git Windowsille".

⁉️🤔 Usein kysytyt kysymykset

Mitkä Git-versiot tukevat --allow-unrelated-histories-lippua?

Lippu ilmestyi Git 2.9.0:ssa (kesäkuu 2016) ja on läsnä kaikissa myöhemmissä versioissa. Jos Git-versiosi on vanhempi, päivitä se: git --version-komento näyttää nykyisen version, ja git update-git-for-windows (Windowsissa) tai järjestelmäsi paketinhallinta päivittää nykyiseen julkaisuun. Helpoin tapa tarkistaa Git-versio on git --version-komento terminaalissa. Vuoden 2026 puolivälissä nykyinen haara on 2.48+. Jos käytät Windowsia ja Git on asennettu kauan sitten, lataa uusi asennusohjelma osoitteesta git-scm.com, automaattinen päivitys vanhoissa versioissa toimi epävakaasti.

Voinko käyttää lippua suoraan git push-komennon kanssa?

Et, git push ei hyväksy --allow-unrelated-histories-lippua. Push ei luo mergeä, se vain lähettää olemassa olevat commitit. "Unrelated histories" -virhe pushissa tarkoittaa, että paikallinen haarasi ja etähaara ovat eriytyneet historiatasolla. Ratkaisu: ensin git pull --allow-unrelated-histories, ratkaise konfliktit ja vasta sitten git push. Muodollisesti --allow-unrelated-histories toimii komentojen git fetch + git merge ja git pull (joka sisäisesti tekee fetch + merge) kanssa. Push pysyy erillisenä operaationa, jonka suoritat onnistuneen mergen jälkeen. Älä yritä ohittaa tätä --force-lipulla, menetät muiden ihmisten commitit etärepositoriossa.

Mikä on parempi puhtaalle historialle: merge vai rebase?

Toisiinsa liittymättömien historioiden yhdistämiseen ehdottomasti merge. Rebase tässä kontekstissa luo enemmän ongelmia kuin ratkaisee: se yrittää toistaa yhden haaran commitit toisen päälle, mutta ilman yhteistä esivanhempaa tämä johtaa konflikteihin jokaisessa commitissa. Merge --allow-unrelated-histories-lipulla tekee juuri sen, mitä tarvitaan: luo yhden liitoskohdan kahden graafin välille, minkä jälkeen historia on yhtenäinen. Poikkeus: kun haluat tarkoituksella kirjoittaa historian uudelleen ja tiedät tarkalleen, mitä olet tekemässä. Esimerkiksi siirrettäessä koodia repositoriosta toiseen ja siivottaessa vanhoja committeja. Tässä tapauksessa git rebase --allow-unrelated-histories voi olla mielekäs, mutta päivittäiseen työhön valitse merge.

Kadotin .git-kansion, mutta minulla on committoimattomia muutoksia. Menetänkö ne?

Et, et menetä niitä. Itse .git-kansio sisältää vain historian ja Gitin metatiedot, mutta ei työtiedostojasi. Kaikki muokatut, uudet ja jopa committoimattomat tiedostot säilyvät työhakemistossa koskemattomina. Palautusmenettely on kuvattu yllä kohdassa "Tilanne 2": git init → git remote add → git fetch → git reset --mixed. Avainkohta: käytä nimenomaan --mixed, älä --hard. --mixed-lippu nollaa indeksin, mutta säilyttää kaikki muutokset tiedostoissa. Jos olet epävarma, tee varmuuskopio koko projektikansiosta ennen palautusta, tämä vie kymmenen sekuntia ja poistaa täysin tietojen menetyksen riskin kaikissa epästandardeissa tilanteissa.

Virhe ilmenee kloonattaessa IDE:n kautta. Onko tämä sama ongelma?

Kyllä, sama ongelma. Jotkin IDE:t (esimerkiksi PHPStorm, Visual Studio, IntelliJ:n vanhemmat versiot) alustavat uuden Git-repositorion luodessaan projektin mallipohjasta ja yrittävät sitten yhdistää etärepositorion. Tämä on juuri artikkelin alussa kuvattu toinen skenaario. Ratkaisu on sama: avaa terminaali projektikansiossa ja suorita git pull origin main --allow-unrelated-histories. Manuaalisen mergen jälkeen IDE poimii uuden tilan automaattisesti, päivitä vain projektin ikkuna tai napsauta Refresh Git-paneelissa.

Pitäisikö "unrelated histories" -virhettä pelätä?

Ei. Tämä on yksi Gitin turvallisimmista virheistä, se ei korruptoi dataa, ei poista tiedostoja eikä estä työn jatkamista. --allow-unrelated-histories-lippu ei ole purkka tai kiertotie, vaan dokumentoitu ominaisuus, jonka Gitin kehittäjät lisäsivät nimenomaan tilanteita varten, joissa haluat tietoisesti yhdistää kaksi itsenäistä historiaa.

Kun hallitset tämän komennon, saat käyttöösi tehokkaan työkalun: nyt voit yhdistää minkä tahansa eristysasteen projekteja, siirtää koodia repositorioiden välillä ja palauttaa työn .git-kansion katoamisen jälkeen, ja kaikki tämä ilman paniikkia ja repositorion uudelleenluontia tyhjästä. Jos Git opetti sinulle tänään jotain, se on se, että "fatal" sen viesteissä ei tarkoita "kohtalokasta projektille", se tarkoittaa "en arvaa, kerro minulle nimenomaisesti, mitä tehdä."