Git 拉取代码报 refusing to merge unrelated histories

本地项目已经提交过代码，添加远程地址后执行 git pull，却出现：

fatal: refusing to merge unrelated histories

一种常见情况是，本地先运行了 git init 并提交代码，远程仓库创建时又单独生成了 README 或许可证提交。两边文件可能属于同一个项目，但提交历史从不同的起点开始，Git 找不到共同祖先，因此拒绝默认合并。

--allow-unrelated-histories 可以允许这种合并，但它不会判断远程仓库是否选错，也不会替你保留冲突文件的正确内容。先确认两边历史的关系，再在独立分支上合并。示例使用远程名 origin 和远程分支 main；实际仓库使用其他名称时需替换。

先排除远程地址和历史不完整的问题

在项目目录中查看当前仓库、分支、远程地址和工作区状态：

git rev-parse --show-toplevel
git branch --show-current
git remote -v
git status --short --untracked-files=all

确认目录确实是目标项目，远程地址属于预期仓库，当前分支不是意外创建的空壳项目。远程名只是一个本地别名：添加 origin 并不会让两个已有仓库的历史自动变成同源。查看地址时也不要把其中可能包含的凭据贴到公开日志里。

如果当前处于 detached HEAD、尚无首次提交，或正在进行另一次 merge、rebase，应先处理那种状态，不要直接套用下面的分支操作。

确认远程无误后，只拉取对象和远程分支信息，暂不合并：

git fetch origin
git branch -r
git rev-parse --is-shallow-repository
git merge-base HEAD origin/main

git fetch 不会把远程文件合并进当前工作区。先从远程分支列表确认 origin/main 存在；若配置只抓取了特定分支，应先调整抓取范围，不能把“找不到这个引用”当成“没有共同祖先”。

git merge-base 若输出提交 ID，说明当前可见历史中有共同祖先，不应再按两段独立历史处理。没有输出时，还要看错误信息、引用是否有效，以及仓库是否为浅克隆。浅克隆可能没有取回足够的历史，缺少祖先并不等于两边独立初始化。

只有浅克隆且远程保有完整历史时，才考虑补全：

git fetch --unshallow origin

补全可能下载较多对象。完成后重新检查共同祖先；远程本身也不完整时，不能假定这条命令一定取回全部历史。如果原来是正常协作仓库，后来突然失去共同祖先，还应核对远程是否重建或重写过历史，先与仓库负责人确认。

合并前先保存本地工作

另一个经常紧接着出现的报错是：

Your local changes to the following files would be overwritten by merge
Please commit your changes or stash them before you merge.

这表示工作区里的修改会与合并操作冲突，是另一道保护。允许合并独立历史不会解除它。

开始前保存一份可恢复的项目副本，包括 .git 和需要保留的未跟踪文件、被忽略的本地配置。不要只复制当前可见的源代码文件。然后审阅本地修改：适合进入版本历史的内容，按文件暂存并提交；不适合提交的内容，先单独备份并妥善移出可能被合并覆盖的位置。凭据和本地环境文件不应为了让工作区变干净而提交。

继续操作前，须保存本地工作，并让暂存区和工作区保持干净。git status 不显示被忽略文件，并不代表这些文件不存在，所以仍需保留前面的副本。

为当前提交留下一个备份分支，再创建专门用于本次合并的分支：

git branch backup/before-unrelated-merge
git checkout -b integrate/remote-main

这两个名字都应尚未使用；已有同名分支时换一个新名字，不要强制覆盖。备份分支只保存提交位置，不保存未提交文件。原工作分支也不会因为随后在新分支上合并而移动。

明确需要保留两边历史时再合并

当远程地址、目标分支和独立初始化的原因都已经确认，并且两边提交都需要保留，可以执行：

git merge --allow-unrelated-histories --no-ff --no-commit \
  --no-overwrite-ignore origin/main

这次操作把远程历史合入当前的 integrate/remote-main 分支。--allow-unrelated-histories 放行无共同祖先的合并；--no-commit 留出检查结果的机会，配合 --no-ff 避免快进更新跳过这个停顿。工作区和暂存区仍会发生变化，这并不是只读预览。

--no-overwrite-ignore 用于在合并要覆盖被忽略文件时中止，避免把“已经加入 .gitignore”误当成文件不会被改动的保证。它不能代替备份，也不能解决文件内容冲突。

两边都创建过 README、许可证或同名配置时，可能发生 add/add 冲突。按文件确认要保留的内容，不要把所有冲突统一选成某一边。允许合并只放开历史关系限制，并不表示任意一边的文件都可以丢弃。

查看仍未解决的文件：

git status
git diff --name-only --diff-filter=U

编辑冲突文件，删除冲突标记并保留需要的内容后，逐个暂存。比如实际冲突文件是 README.md：

git add -- README.md
git diff --cached --stat
git diff --cached
git diff --cached --check

README.md 只是示例，不应照抄成所有冲突都已解决。检查暂存内容中有没有意外删除、凭据、构建产物或错误的许可证；--check 能发现部分空白问题和冲突标记，不能证明代码逻辑正确。还应运行项目本来需要的构建或测试。

确认没有未解决冲突，且结果符合预期后提交：

git commit -m "Merge remote main into local project"

确认两边提交都还在，再决定推送

提交完成后查看合并图，并确认合并前的两端都能从当前提交追溯到：

git log --graph --oneline --decorate -n 20
git merge-base --is-ancestor backup/before-unrelated-merge HEAD
git merge-base --is-ancestor origin/main HEAD

两条祖先检查成功时通常没有输出，退出状态为 0。它们证明当前历史包含对应提交，但不能证明冲突文件已经正确整理。文件审阅和项目验证仍然要做。

需要交给远程审核时，可先推送这个新分支：

git push -u origin integrate/remote-main

推送前再次核对暂存过的内容与提交历史，按仓库规则提交合并请求。无需为了这个错误直接覆盖远程 main，也不要把 --force 当成常规修复。远程在此期间有新提交时，先重新抓取并检查变化，再处理合并。

如果只想把本地文件放进现有远程仓库，并不需要保留本地提交历史，也可以在另一个目录正常克隆远程仓库，再有选择地复制项目文件进去、审阅后提交。不要复制旧目录的 .git，也不要删除旧目录；保留它能避免遗漏未跟踪文件或后续才发现有价值的历史。

放弃这次合并时

在合并仍未提交的阶段，可以取消：

git merge --abort

它会尝试恢复合并前的状态。若开始时夹带了未提交修改，恢复可能不完整，这也是要求先保存本地工作的原因。取消后检查 git status，再返回原工作分支。

如果已经提交，git merge --abort 不再是撤销该提交的办法。由于整个操作发生在新建的合并分支上，可以保留该分支供检查，返回原工作分支继续工作；未保存的后续修改仍需先处理。已经进入共享分支的合并，应按团队流程做新的回退提交，不要强推重写其他人正在使用的历史。