fatal: not a git repository —— 五种成因，一条命令

■ space · 巡查探针 · fig 1

Git 沿着树向上找 .git,碰到第一条就停 —— 五件事会打断这场搜寻,一条命令把它们分开。

■ 先说答案

运行 git rev-parse --show-toplevel || ls -a —— 还没动手之前,一条命令先分清成因。

根目录打出来了 → 你站在 repo 之外; cd 就在那里。但 .git 里不见 ls -a → 这里从来没有过 repo:重新 clone,别 git init。

机器上每个 repo 都报错 → 导出了 GIT_DIR ; unset GIT_DIR。

5种成因藏在同一行 fatal 背后

1条命令把它们分开

20分钟 —— 「上层文件夹」的猜法就要这么多

01向上找

git 找的是一条记录,一路向上,碰到第一条就停 —— 机器把这趟搜寻重放一遍

FIG 1 · 向上探寻器按键 1–6 —— 或用按钮

探测仪

$ git rev-parse --show-toplevel
/home/you/projects/myapp

找到了 —— 向上找停在 .GIT修法 —— 无需修:这趟向上找很健康

出发 src/api/ · 触过的楼层 2 · 判词找到

你在这里 → 你在这里敲了 git pull → 向上找在这里停住,停在它碰到的第一个 .git

02成因表

五件事打断搜寻 —— 把你的症状对上一行

症状	可能成因	修法
单个项目里报错, `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`,否则重新 clone

验证: git rev-parse --show-toplevel → repo 根路径,没有错误

03前两个在撒谎

表格修的是症状;前两种成因正是肌肉记忆撒谎的地方

子文件夹形态—你刚 cd 进了 docs/ 或 src/api/,shell 的习惯说根就在这里 —— git 向上找,什么都没找到,熄火

clone 形态—git clone 总会建一个以 repo 命名的子文件夹 —— checkout 就在你所站位置的下一层

zip 形态—Code → Download ZIP 只发源码快照:没有 .git,没有历史,没有 remote

拷贝形态—文件被拷走时没带上隐藏文件夹 —— 清理工具把 .git 当「隐藏垃圾」删掉,结局一样

跳到根目录 —— repo 内任何深度都好使

git rev-parse --show-toplevel   # prints the root when one exists
cd "$(git rev-parse --show-toplevel)"   # jump there in one step

这里从来没有过 repo —— 把历史找回来

ls -a   # no .git here
git clone <url>   # the fix — again, not git init

git init 修不了 repo —— 它只会把一个空壳建在你站的地方。

04后三个跟着你走

剩下三个是环境性的 —— 错误被导出、悬空,或者从未出生

线索:一小时前 git 还在这好使

env | grep GIT_DIR     # GIT_DIR=/some/old/path
unset GIT_DIR

GIT_DIR 被导出—一条固定路径取代了搜寻,于是每个「正常」目录都成了「不是仓库」 —— 如果每天早上都回来,某一行在 ~/.bashrc、 ~/.zshrc,或者 CI 包装脚本里把它导出了:在那里清掉

死指针—.git 单行文件,点名磁盘上别处的某个目录;目标被挪走或删掉 → 指针悬空,即使 .git 明明就在那儿 —— git worktree repair 能接回多少接回多少,其余情形:重新 clone

submodule—文件夹在父 repo 的树里存在,却从未被初始化 —— 里面还没有 .git ;从父级再跑一次 git submodule update --init --recursive 就把它补齐

未被跟踪的流浪汉搭着拷贝来的树的便车 —— clone 到位之后,一次 clean 打扫就安顿了它们

■ 诚实印记 实测环境:git 2.4x · bash + zsh · submodule 与 worktree。首次发布 2026-09-28。 向上搜索、GIT_DIR 覆盖和 worktree 指针文件,都是 git 有据可查的发现行为;五种成因是这条报错背后的完整清单,从一个个死而复生的 repo 里敲出来。

五种成因到此为止 · 没有任何 fetch · 全程本地