解决 Git Push 失败：处理“非快进”与“非相关历史”问题

解决 Git Push 失败：处理“非快进”与“非相关历史”问题

在使用 Git 进行版本控制时，git push 是将本地代码推送到远程仓库的关键操作，但过程中可能会遇到各种报错。今天就来聊聊两种常见的 git push 失败场景及解决办法。

一、“非快进”推送失败

（一）错误现象

执行 git push -u origin master 命令后，终端出现类似如下提示：

To https://gitee.com/xxx/git-text.git! [rejected]        master -> master (non-fast-forward)
error: failed to push some refs to 'https://gitee.com/xxx/git-text.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

从提示可知，远程仓库的代码版本比本地新，直接推送会覆盖远程更新，所以 Git 拒绝了“非快进”的推送操作。

（二）原因分析

这种情况通常是因为远程仓库在创建时，勾选了“初始化 README.md 等文件”选项，远程仓库已有内容，而本地仓库是另外初始化的，本地分支落后于远程分支。

（三）解决方法

方法一：先拉取再推送（推荐空目录场景）

如果是在一个全新的、空的本地目录下开发，建议先把远程仓库克隆（clone）到本地：

git clone https://gitee.com/xxx/git-text.git

克隆完成后，将项目代码拷贝到这个克隆下来的目录里，然后进行提交（git add .、git commit -m "提交说明"），最后再执行 git push 推送代码。这样能保证本地和远程仓库历史一致，避免冲突。

方法二：拉取并合并远程代码（已有本地仓库场景）

如果本地已经有仓库且有代码，可先执行 git pull 拉取远程代码。但如果本地和远程仓库历史完全无关，直接 git pull 可能会出现新的错误（如下一种情况的“非相关历史”错误），这时候就需要结合“合并非相关历史”的操作。

二、“合并非相关历史”错误

（一）错误现象

使用 TortoiseGit 等图形化工具执行 pull 操作时，可能会出现类似如下提示：

fatal: refusing to merge unrelated histories
git 未能顺利结束（退出码 128）

同时工具界面会有“合并非相关历史(M)”的选项，如图所示：

（二）原因分析

本地仓库和远程仓库的提交历史完全没有关联，Git 不知道如何合并这两个毫无关系的历史线，所以拒绝合并。

（三）解决方法

在 TortoiseGit 中，当出现这个错误时，点击“合并非相关历史(M)”按钮，工具会强制合并本地和远程的非相关历史，之后再执行 git push 操作，就能成功将代码推送到远程仓库了。

如果是用命令行操作，可执行：

git pull origin master --allow-unrelated-histories

这条命令允许合并非相关历史，执行完成后，再进行 git push 即可。

总结

在使用 git push 时，遇到“非快进”或“非相关历史”的问题，核心思路是让本地和远程仓库的历史尽可能保持一致或能合理合并。根据本地仓库的实际情况，选择先克隆再开发，或者拉取合并远程代码（必要时合并非相关历史），就能顺利完成代码推送啦。