Git 常见问题与故障排除指南

本文档汇总了 Git 日常使用中高频出现的疑难杂症及其解决方案。

一、 .gitignore 规则不生效

1.1 问题现象

在 .gitignore 文件中添加了规则（例如忽略 bin/ 或 *.log），但执行 git status 时，这些文件依然显示在变更列表中，或者已经被提交到了版本库。

1.2 原因分析

Git 的忽略规则仅对 未被追踪 (Untracked) 的文件生效。如果一个文件已经被纳入版本控制（即之前已经 git add 并 commit 过），后续再添加到 .gitignore 中是无效的，因为 Git 会继续追踪它的变更。

1.3 解决方案

必须从 Git 的索引（暂存区）中移除这些文件，将其状态重置为 "Untracked"，然后再提交。

操作步骤：

1. 清除本地缓存：

   # 移除所有文件的缓存（保留本地物理文件，仅从 git 索引中删除）
   git rm -r --cached .

   注意：如果遇到 fatal: pathspec 'xxx' is in submodule 或其他特定文件错误，可尝试先手动移除特定文件 git rm --cached <file_path>。

2. 重新添加所有文件： 此时 Git 会重新读取 .gitignore 规则，忽略列表中的文件将不会被添加到暂存区。

   git add .

3. 提交变更：

   git commit -m "fix: refresh .gitignore rules"

---

二、 克隆大项目报错 (Remote end hung up)

2.1 问题现象

在克隆大型项目（或网络状况不佳）时，可能会遇到以下错误：

• fatal: The remote end hung up unexpectedly
• error: RPC failed; curl 18 transfer closed with outstanding read data remaining
• fatal: early EOF
• fatal: index-pack failed

2.2 解决方案

方案 A：增加 HTTP 缓存 (针对 postBuffer 溢出)

如果是因为单次提交的文件过大导致溢出，可以尝试增大 Git 的 HTTP 缓冲区（例如设置为 1GB 或 3GB）。

# 设置为 1GB
git config --global http.postBuffer 1048576000

# 或者设置为 3GB
git config --global http.postBuffer 3194304000

方案 B：调整最低速度限制 (针对网络超时)

如果是网络不稳定导致连接被断开，可以放宽最低速度限制和超时时间。

# 限制最低速度为 0 (不限制)
git config --global http.lowSpeedLimit 0
# 设置超时时间为 999999 秒
git config --global http.lowSpeedTime 999999

方案 C：浅克隆 (Shallow Clone)

如果项目历史记录过于庞大，可以先只克隆最近一次提交（浅克隆），成功后再拉取完整历史。

# 1. 浅克隆 (深度为 1)
git clone --depth=1 http://github.com/xxx/project.git

# 2. 进入目录
cd project

# 3. 转换为完整克隆 (拉取剩余历史)
git fetch --unshallow

注：如果 git fetch --unshallow 依然失败，可以尝试多次执行或分批拉取。

---

三、 只能看到 Master 分支

3.1 问题现象

克隆项目后，执行 git branch -a 或 git fetch 只能看到 remotes/origin/master，无法看到远程的其他分支。

3.2 原因分析

这通常是因为 Git 配置中的 fetch 规则被限制为仅拉取 master 分支。这可能是由某些 IDE 或特定克隆命令（如 --single-branch）生成的配置导致的。

3.3 解决方案

修改 .git/config 配置文件中的 fetch 规则。

1. 打开配置文件：编辑项目根目录下的 .git/config。

2. 查找 [remote "origin"] 部分：

   错误配置（仅包含 master）：

   [remote "origin"]
   url = https://github.com/xxx/project.git
   fetch = +refs/heads/master:refs/remotes/origin/master

3. 修改为通配符： 将 master 替换为 *，表示拉取所有分支。

   正确配置：

   [remote "origin"]
   url = https://github.com/xxx/project.git
   fetch = +refs/heads/*:refs/remotes/origin/*

4. 刷新远程分支：

   git fetch

   此时再执行 git branch -a 即可看到所有远程分支。