fatal: not a git repository？60 秒定位与修复

最快的丢时间方式：在仓库的上一级目录敲 git pull。Git 回你一句 fatal: not a git repository (or any of the parent directories): .git，而网上多数答案接着就喊 git init——四种真实成因里，这招错了三种。

60 秒分诊：

git rev-parse --show-toplevel || ls -a

上方存在仓库时，--show-toplevel 会打印仓库根目录——站错地方，结案，cd 过去即可。如果它也失败，同一行会列出当前目录内容：列表里没有 .git，说明这里从来就没有仓库可找。一条命令就能分开绝大多数病例的两种成因，剩下的罕见情况就是本文剩下的部分。

Git 为什么报「fatal: not a git repository」？

Git 查找仓库的方式，是从当前目录一路向上搜一个 .git，找到第一个就用。这条上行路径恰好有四种断法：你站在树外，.git 目录没了，一个环境变量把搜索引向了别处，或者 .git 存在却指向空处。Stack Overflow 2022 年的开发者调查显示约 94% 的开发机装着 Git，这个报错是集体必经之路。四种成因学一遍，就不再耗时间。

（如果你的仓库本身没事，只是想撤销一次提交，Undo Anything in Git 把本站所有修复路径收在一个地方。）

成因一：你站错了目录

最常见的一种。两个形态：

1. 你 cd 进了某个子目录——docs/、src/api/——而另一个项目养成的习惯告诉你根目录就在这里。Git 向上找，什么都没找到，放弃。
2. 你克隆了一个仓库，以为文件就在脚下，但 git clone 总会新建一个以仓库命名的子目录。checkout 在你位置的下一层。

git rev-parse --show-toplevel   # 存在时打印根目录
cd "$(git rev-parse --show-toplevel)"  # 一步跳过去

第二条命令永久解决肌肉记忆问题：在仓库内任何深度执行都有效。

成因二：没有 .git——这个目录从来不是仓库

ls -a 里没有 .git。通常是：

• 从 GitHub 下载的 ZIP。 Code → Download ZIP 只给文件：没有 .git，没有历史，没有 remote。GitHub 官方文档写明：ZIP 压缩包只含源码快照。
• 从别的机器或项目拷来的文件，隐藏目录没有跟着走。
• 清理工具把 .git 当成”没用的隐藏文件夹”删了。

修法：重新克隆，拿回历史。

cd ..
git clone https://github.com/<user>/<repo>.git

git init 在这里只会开一个全新仓库，什么都找不回来。而且拷贝来的文件堆里通常混着未跟踪文件；克隆落位之后，git remove untracked files 负责打扫。

git init 修不了仓库——它只在你站的地方新建一个空的。

成因三：GIT_DIR 被导出，殃及所有仓库

破案线索：错误跟着你走进一小时前还正常的目录。导出的 GIT_DIR 命令 Git 去看一条固定路径，放弃仓库发现，于是每个”普通”目录都成了 “not a repository”。

env | grep GIT_DIR     # GIT_DIR=/某条/旧路径
unset GIT_DIR

如果它每天早上都回来，说明 ~/.bashrc、~/.zshrc 或某个 CI 包装脚本里有一行在导出它。CI 系统设 GIT_DIR 是故意的：在流水线里正确，在你的交互 shell 里是地雷。

成因四：submodule 从未初始化

你 cd 进 vendor/libfoo/，Git 说这个目录不是仓库。它说的对：初始化之前，submodule 目录就是个空文件夹，.gitmodules 里有一行记录， checkout 则什么都没有。

cat .gitmodules        # 列出 submodule 路径
git submodule update --init --recursive

在仓库根目录执行，别站在 submodule 里——上行规则照样适用，而空的 submodule 没有根可供上行。

成因五：.git 是个文件，指向的目标没了

worktree 和 submodule 会把 .git 变成单行文件：gitdir: /真实/gitdir/路径。当真实 gitdir 被删掉（被清理的 .git/modules、被挪走的磁盘），指针悬空，向上搜索找到一个不应答的 .git：

$ ls -la .git
-rw-r--r-- 1 you you 35 Sep 28 10:12 .git     # 是文件，不是目录
$ cat .git
gitdir: ../.git/modules/libfoo

git worktree repair    # 重新连接路径变了的 worktree

如果 worktree repair 找不回目标，gitdir 就没了。submodule 的历史在父仓库的 .git/modules/<名字> 里；先确认它存在，再下最坏的结论。

症状 → 成因 → 修复

症状	最可能的成因	修复
某个项目报错，ls -a 里没有 .git	ZIP 下载 / 文件拷贝	重新 git clone
子目录报错，根目录正常	站在树外	cd "$(git rev-parse --show-toplevel)"
所有目录都报错，包括之前正常的	GIT_DIR 被导出	unset GIT_DIR，并从 shell 配置里清除
submodule 目录里报错	submodule 未初始化	git submodule update --init --recursive
.git 是文件，报错仍在	worktree/submodule 指针悬空	git worktree repair，否则重新克隆

那 git init 到底什么时候是对的？

一次：ls -a 没有 .git，而你本来就打算在这里开一个新仓库。执行它，然后下一条命令是 git add，不是 git log。

其余场景它是带签名的陷阱。git init 深一层，就建出一个没有提交的嵌套仓库——接下来 git log 回你 fatal: your current branch 'main' does not have any commits yet。这条报错的意思是：你刚在脚下新建了一个仓库，真正的仓库在上一级。清理是外科手术式的：

cd 嵌套目录
rm -rf .git    # 只删误建的仓库，文件原封不动

敲这条 rm 之前看清提示符：它必须运行在嵌套目录里，绝不能在项目根目录。然后 cd 回真正的根目录，用 git rev-parse --show-toplevel 确认 Git 找回了一开始就该找到的东西。