Git Common Errors

Git Common Errors1. 这篇文章解决什么问题Git 报错时最容易让人慌的不是错误本身而是不知道它在说哪一层出了问题。常见错误包括1. not a git repository 2. remote origin already exists 3. failed to push some refs 4. non-fast-forward 5. refusing to merge unrelated histories 6. Your local changes would be overwritten 7. detached HEAD 8. Permission denied (publickey)这篇不追求覆盖所有错误只整理个人 C 后端项目里最常见、最容易卡住的几类。2. 先判断问题发生在哪一层遇到错误时先不要马上复制一堆命令乱试。先判断它属于哪一类仓库位置问题当前目录是不是 Git 仓库 工作区问题本地文件有没有未提交修改 暂存区问题是不是 add 或 commit 状态不清楚 历史问题本地和远程历史是否分叉 远程问题remote、SSH、权限是否正确固定先执行gitstatusgitremote-vgitbranch-vv很多问题看完这三个命令就能定位大半。3. not a git repository报错类似fatal: not a git repository (or any of the parent directories): .git意思是当前目录不是 Git 仓库 Git 往上找也没有找到 .git 目录常见原因1. 终端目录进错了 2. 项目还没有 git init 3. 只复制了源码文件没有复制 .git 目录处理方式pwdls-la确认当前目录。如果这是一个新项目可以执行gitinit如果这是 GitHub 上已有项目更推荐gitclone gitgithub.com:username/repo.git4. remote origin already exists报错类似error: remote origin already exists.意思是当前仓库已经有一个叫 origin 的远程地址 不能重复添加同名 remote先查看gitremote-v如果地址是对的不需要再添加。如果地址错了可以改gitremote set-url origin gitgithub.com:username/repo.git如果确实想删掉重新加gitremote remove origingitremoteaddorigin gitgithub.com:username/repo.git一般更推荐set-url意图更明确。5. Permission denied (publickey)报错类似gitgithub.com: Permission denied (publickey). fatal: Could not read from remote repository.意思是GitHub 没有通过你的 SSH 身份验证常见原因1. 本机还没有生成 SSH key 2. 公钥没有添加到 GitHub 3. remote 地址写成了没有权限的仓库 4. 多个 GitHub 账号使用了错误的 key先测试ssh-Tgitgithub.com如果 SSH 没配置好回到02-github-ssh-remote.md按步骤处理。6. failed to push some refs报错类似! [rejected] main - main (fetch first) error: failed to push some refs to github.com:username/repo.git通常表示远程分支上有本地没有的提交 Git 不允许你直接覆盖远程历史先执行gitfetch origingitlog--oneline--graph--decorate--all看清楚本地和远程历史。常见处理gitpull--rebaseorigin maingitpush或者gitpull origin maingitpush具体用 merge 还是 rebase可以回看05-merge-rebase-pull.md。不要一看到 push 被拒绝就马上gitpush--force这可能覆盖别人已经推上去的提交。7. non-fast-forward报错类似! [rejected] main - main (non-fast-forward)意思和上一节很接近你的本地分支不能直接快进到远程分支 本地和远程历史已经不一致常见情况远程多了 README 或其他初始化提交 另一台电脑已经 push 过新提交 队友先 push 了更新处理思路仍然是先 fetch 再看历史 再决定 merge 或 rebase 最后 push命令示例gitfetch origingitlog--oneline--graph--decorate--allgitrebase origin/maingitpush如果发生冲突按07-conflict-resolution.md处理。8. refusing to merge unrelated histories报错类似fatal: refusing to merge unrelated histories意思是本地仓库和远程仓库不是同一条历史 Git 找不到共同祖先常见原因1. 本地 git init 后提交了一次 2. GitHub 仓库创建时也初始化了 README 3. 然后试图把两个独立历史 pull 到一起更推荐的做法是如果 GitHub 仓库已经有 README优先 git clone 不要本地 git init 后再硬绑定如果你确认就是要合并两段历史可以执行gitpull origin main --allow-unrelated-histories然后解决可能出现的冲突。但这不是日常首选方案它更像是补救操作。9. Your local changes would be overwritten报错类似error: Your local changes to the following files would be overwritten by checkout:或者error: Your local changes would be overwritten by merge意思是你当前工作区有未提交修改 如果继续 checkout、merge 或 pull这些修改可能被覆盖先看gitstatus常见处理方式有三种。如果修改应该保留并提交gitadd.gitcommit-mwip: save current changes如果只是临时保存gitstash push-msave local changes如果确定不要这些修改gitrestore.具体选哪种取决于这些修改还有没有价值。10. detached HEAD看到HEAD detached at a8c912e意思是你当前没有站在某个分支上 而是直接站在某个 commit 上这通常发生在gitcheckout a8c912e此时如果你只是想查看旧版本没问题。如果你在 detached HEAD 状态下继续提交新提交可能没有分支名字保护。如果想保留这些提交立刻创建分支gitswitch-cdebug/old-version如果只是看完旧版本想回到 maingitswitch main11. pathspec did not match报错类似error: pathspec feature/cache did not match any file(s) known to git常见原因1. 分支名写错了 2. 本地还没有这个远程分支信息 3. 当前命令把参数当成了文件或分支但 Git 找不到先看本地分支gitbranch再看所有分支gitbranch-a如果远程确实有这个分支先更新远程信息gitfetch origin然后切换gitswitch feature/cache如果本地还没有这个分支可以基于远程创建gitswitch-cfeature/cache origin/feature/cache12. push 时提示 upstream 没设置报错可能类似fatal: The current branch feature/cache has no upstream branch.意思是当前本地分支还没有关联远程分支 Git 不知道 git push 默认要推到哪里第一次推送新分支时执行gitpush-uorigin feature/cache-u的作用是建立 upstream 关系。以后在这个分支上就可以直接gitpushgitpull13. 一个通用排查流程遇到 Git 错误时可以先按这个顺序来pwdgitstatusgitbranch-vvgitremote-vgitlog--oneline--graph--decorate--all然后问自己我现在在哪个目录 我现在在哪个分支 工作区是否干净 远程地址是否正确 本地和远程历史是否分叉大多数 Git 问题都可以从这几个问题里找到入口。14. 一句话总结Git 报错时不要先背命令先判断问题属于目录、工作区、历史还是远程。git status、git remote -v、git branch -vv和图形化git log是最实用的排查起点。