PHP小码农

Appearance

Git 常见错误 ​

概述 ​

在使用 Git 的过程中,会遇到各种各样的错误。本指南将介绍最常见的 Git 错误及其解决方案,包括推送被拒绝、合并冲突、分支问题和远程同步问题。

推送被拒绝 ​

错误: Updates were rejected ​

错误信息 ​

! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'git@github.com:user/repo.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.

原因 ​

远程仓库有新的提交,本地仓库没有这些提交。

解决方案 ​

bash
# 方案1: 先拉取再推送
git pull origin main
git push origin main

# 方案2: 使用 rebase
git pull --rebase origin main
git push origin main

# 方案3: 强制推送(危险,仅在确定时使用)
git push origin main --force

# 方案4: 使用 merge
git fetch origin
git merge origin/main
git push origin main

错误: Push rejected (protected branch) ​

错误信息 ​

remote: error: GH006: Protected branch update failed for refs/heads/main.
remote: error: Cannot force-push to a protected branch

原因 ​

分支受保护,不允许直接推送或强制推送。

解决方案 ​

bash
# 方案1: 创建 PR
git checkout -b feature/new-feature
git push origin feature/new-feature
# 然后在网页上创建 PR

# 方案2: 联系管理员
# 请求临时解除保护或添加权限

错误: Permission denied ​

错误信息 ​

remote: Permission to user/repo.git denied to username.
fatal: unable to access 'https://github.com/user/repo.git/': The requested URL returned error: 403

原因 ​

没有推送权限或认证失败。

解决方案 ​

bash
# 方案1: 检查权限
# 确认是否有仓库写权限

# 方案2: 检查 SSH 密钥
ssh -T git@github.com

# 方案3: 更新远程 URL
git remote set-url origin git@github.com:user/repo.git

# 方案4: 使用 HTTPS + Token
git remote set-url origin https://TOKEN@github.com/user/repo.git

# 方案5: 配置凭证缓存
git config --global credential.helper cache
git config --global credential.helper 'cache --timeout=3600'

合并冲突 ​

错误: CONFLICT (content) ​

错误信息 ​

Auto-merging file.txt
CONFLICT (content): Merge conflict in file.txt
Automatic merge failed; fix conflicts and then commit the result.

原因 ​

同一文件的不同修改无法自动合并。

解决方案 ​

bash
# 1. 查看冲突文件
git status

# 2. 查看冲突内容
git diff

# 3. 手动解决冲突
# 编辑冲突文件,选择保留的内容

# 冲突标记格式:
<<<<<<< HEAD
当前分支的内容
=======
要合并分支的内容
>>>>>>> branch-name

# 4. 标记冲突已解决
git add file.txt

# 5. 完成合并
git commit

使用工具解决冲突 ​

bash
# 使用 VS Code
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'

# 使用 Vim
git config --global merge.tool vimdiff

# 启动合并工具
git mergetool

# 使用图形化工具
git mergetool --tool=p4merge
git mergetool --tool=kdiff3

中止合并 ​

bash
# 如果合并出错,可以中止
git merge --abort

# 或使用 reset
git reset --hard HEAD

错误: CONFLICT (modify/delete) ​

错误信息 ​

CONFLICT (modify/delete): file.txt deleted in branch-a and modified in branch-b

原因 ​

一个分支删除了文件,另一个分支修改了文件。

解决方案 ​

bash
# 方案1: 保留文件
git add file.txt
git commit

# 方案2: 删除文件
git rm file.txt
git commit

# 方案3: 使用特定版本
git checkout --ours file.txt    # 使用当前分支版本
git checkout --theirs file.txt  # 使用合并分支版本

分支问题 ​

错误: Branch not found ​

错误信息 ​

fatal: A branch named 'feature' does not exist.

原因 ​

分支不存在或名称错误。

解决方案 ​

bash
# 查看所有分支
git branch -a

# 检查分支名称
git branch --list '*feature*'

# 创建分支
git branch feature

# 从远程创建
git checkout -b feature origin/feature

错误: Branch already exists ​

错误信息 ​

fatal: A branch named 'feature' already exists.

原因 ​

分支已存在。

解决方案 ​

bash
# 方案1: 切换到已存在的分支
git checkout feature

# 方案2: 删除后重建
git branch -D feature
git checkout -b feature

# 方案3: 重命名
git branch -m feature new-feature

错误: Cannot delete branch ​

错误信息 ​

error: The branch 'feature' is not fully merged.
If you are sure you want to delete it, run 'git branch -D feature'.

原因 ​

分支未合并到当前分支。

解决方案 ​

bash
# 方案1: 先合并
git checkout main
git merge feature
git branch -d feature

# 方案2: 强制删除
git branch -D feature

# 方案3: 检查未合并的提交
git log main..feature

错误: Your branch is ahead ​

错误信息 ​

Your branch is ahead of 'origin/main' by 2 commits.

原因 ​

本地有未推送的提交。

解决方案 ​

bash
# 方案1: 推送提交
git push origin main

# 方案2: 查看未推送的提交
git log origin/main..HEAD

# 方案3: 撤销本地提交
git reset --hard origin/main

远程同步问题 ​

错误: Failed to connect ​

错误信息 ​

fatal: unable to access 'https://github.com/user/repo.git/': 
Failed to connect to github.com port 443: Connection refused

原因 ​

网络连接问题。

解决方案 ​

bash
# 方案1: 检查网络
ping github.com

# 方案2: 使用代理
git config --global http.proxy http://proxy:port
git config --global https.proxy https://proxy:port

# 方案3: 使用 SSH
git remote set-url origin git@github.com:user/repo.git

# 方案4: 检查防火墙
# 确保端口 22 和 443 未被阻止

# 方案5: 使用镜像(如在中国)
# 使用 GitHub 镜像站点

错误: SSL certificate problem ​

错误信息 ​

fatal: unable to access 'https://github.com/user/repo.git/': 
SSL certificate problem: self signed certificate

原因 ​

SSL 证书验证失败。

解决方案 ​

bash
# 方案1: 更新 CA 证书
# macOS
brew install ca-certificates

# Ubuntu
sudo apt-get install ca-certificates

# 方案2: 指定 CA 证书
git config --global http.sslCAInfo /path/to/ca.crt

# 方案3: 临时禁用 SSL 验证(不推荐)
git config --global http.sslVerify false

# 方案4: 使用 SSH
git remote set-url origin git@github.com:user/repo.git

错误: Repository not found ​

错误信息 ​

remote: Repository not found.
fatal: repository 'https://github.com/user/repo.git/' not found

原因 ​

仓库不存在或无访问权限。

解决方案 ​

bash
# 方案1: 检查仓库名称
git remote -v

# 方案2: 更新远程 URL
git remote set-url origin https://github.com/correct-user/correct-repo.git

# 方案3: 检查权限
# 确认有仓库访问权限

# 方案4: 检查认证
ssh -T git@github.com

错误: Authentication failed ​

错误信息 ​

remote: Support for password authentication was removed on August 13, 2021.
remote: Please see https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories#cloning-with-https-urls for information on currently recommended modes of authentication.
fatal: Authentication failed for 'https://github.com/user/repo.git/'

原因 ​

GitHub 不再支持密码认证。

解决方案 ​

bash
# 方案1: 使用 SSH
git remote set-url origin git@github.com:user/repo.git

# 方案2: 使用 Personal Access Token
# 1. 在 GitHub 创建 Token
# Settings -> Developer settings -> Personal access tokens

# 2. 使用 Token
git remote set-url origin https://TOKEN@github.com/user/repo.git

# 方案3: 使用凭证管理器
# macOS
git config --global credential.helper osxkeychain

# Windows
git config --global credential.helper manager

# Linux
git config --global credential.helper cache

其他常见错误 ​

错误: not a git repository ​

错误信息 ​

fatal: not a git repository (or any of the parent directories): .git

原因 ​

当前目录不是 Git 仓库。

解决方案 ​

bash
# 方案1: 初始化仓库
git init

# 方案2: 克隆仓库
git clone https://github.com/user/repo.git

# 方案3: 进入正确的目录
cd /path/to/git/repo

错误: Untracked files ​

错误信息 ​

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    new-file.txt

原因 ​

有未跟踪的文件。

解决方案 ​

bash
# 方案1: 添加文件
git add new-file.txt

# 方案2: 添加所有文件
git add .

# 方案3: 忽略文件
echo "new-file.txt" >> .gitignore

# 方案4: 查看未跟踪文件
git status

错误: Nothing to commit ​

错误信息 ​

nothing to commit, working tree clean

原因 ​

没有变更或变更已提交。

解决方案 ​

bash
# 方案1: 检查状态
git status

# 方案2: 检查暂存区
git diff --staged

# 方案3: 检查未暂存的变更
git diff

# 方案4: 确认文件已修改
ls -la

错误: Detached HEAD ​

错误信息 ​

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

原因 ​

HEAD 指向特定提交而非分支。

解决方案 ​

bash
# 方案1: 创建新分支保存提交
git checkout -b new-branch

# 方案2: 切换回分支
git checkout main

# 方案3: 查看当前状态
git log --oneline -5

# 方案4: 使用 reflog 恢复
git reflog
git checkout -b recovery-branch HEAD@{n}

错误预防 ​

提交前检查 ​

bash
# 检查状态
git status

# 检查差异
git diff

# 运行测试
npm test

# 运行 lint
npm run lint

使用 Git Hooks ​

bash
# .git/hooks/pre-commit
#!/bin/bash

# 检查代码风格
npm run lint || exit 1

# 运行测试
npm test || exit 1

echo "Pre-commit checks passed!"

使用别名 ​

bash
# 添加常用别名
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.visual 'log --graph --oneline --all'

总结 ​

处理 Git 错误的关键:

理解错误:

  • 阅读错误信息
  • 了解错误原因
  • 选择正确方案

预防措施:

  • 提交前检查
  • 使用 Git Hooks
  • 定期同步

解决策略:

  • 保持冷静
  • 查阅文档
  • 寻求帮助

通过掌握常见错误的解决方法,可以更高效地使用 Git 进行开发。