fatal: not a git repository 报错速查：.git 丢失与目录定位

更新时间：2026-10-24。FAQ 速查页，面向刚上手 Git、在某目录里敲 git status 却撞 fatal: not a git repository 的同学。这句报错的含义只有一个：Git 从当前目录一路向上找，都没找到一个可用的 .git。但「找不到」背后收敛在六根轴上：压根不在仓库里、.git 被删或半截损坏、GIT_DIR 环境变量把 Git 指去了别处、把 bare 仓库当工作区用、人在子目录但父链被挂载点截断、以及拿一个从没 git init 过的裸目录当仓库。顺一遍基本必中。如果你报错是仓库里的操作失败（提交、推送被拒），那归本簇其他篇管，本篇只管「Git 根本不承认这里是个仓库」。

本文要回答的问题

• not a git repository (or any of the parent directories): .git 这后半句在提示什么排查动作？
• .git 明明在，git status 还是说不是仓库，怎么判断 .git 是不是坏的？
• GIT_DIR / GIT_WORK_TREE 环境变量为什么会把正常仓库「变没」？
• clone 下来一个 xxx.git 目录，进去敲 git 命令为什么报这个错？
• 什么情况下该重建 .git，什么情况下还有救？

一、报错原文与典型现象

报错的几种真实措辞如下（工程路径以 /proj/demo 占位）：

$ cd /proj/demo && git status
fatal: not a git repository (or any of the parent directories): .git

$ git log
fatal: your current branch 'master' does not have any commits yet
# 注意：这条不是 not a git repository，仓库是好的，只是还没提交过

$ GIT_DIR=/tmp/foo git status
fatal: not a git repository: '/tmp/foo'
# 带具体路径的这一变体，说明 Git 被环境变量指去了别处

读报错先抓后半句：(or any of the parent directories): .git 意思是 Git 从当前目录一路向上找到根都没捡到 .git，属于「根本没找到」；而 fatal: not a git repository: '/tmp/foo' 直接点名了一个路径，属于「被指去了错的地方」。前者查目录定位，后者查环境变量，两路不要混。

二、病因处置速查表

报错现象 / 场景	可能原因	快速验证	处置
任何 git 命令都报 not a git repository	当前目录不在任何仓库内	pwd 对比记忆中的仓库路径；ls -a 看有没有 .git	cd 进真正的仓库目录，或 git init 新建
昨天还能用，今天报这个错	.git 目录被误删（清理脚本、rm -rf 误伤）	ls -a /proj/demo 看 .git 是否还在	有远端就重新 clone；没有则从备份恢复
.git 在但仍报错	.git 半截损坏（HEAD 丢了、objects 目录被清空）	cat /proj/demo/.git/HEAD；git fsck	重建引用或从远端重 clone 保工作区
报错里带一个陌生路径	GIT_DIR/GIT_WORK_TREE 环境变量误设	env | grep GIT_	unset GIT_DIR GIT_WORK_TREE 后重试
进 xxx.git 目录敲 status 报错	那是 bare 裸仓库，没有工作区	cat xxx.git/HEAD 存在但没有源码文件	bare 仓库只做远端用；工作请 clone 一份
仓库在挂载盘/NFS 上，偶发报这个错	挂载掉了，Git 向上越过了挂载点	df . 看当前目录落在哪个挂载	重新挂载后再操作
submodule 里报 .git 文件指向失效	父仓库被整体挪了路径，gitfile 断链	cat 子模块/.git 看 gitdir 指向	git submodule absorbgitdirs 或修正指向

三、排查决策图

下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。

读这张图抓住两个分水岭：第一刀切在环境变量——报错里点名了陌生路径、或 env | grep GIT_ 有输出，就不用查目录了，卸变量即可；第二刀切在 ls -a——.git 在不在决定走「重建」还是「修坏」。.git 在但 HEAD 坏了是最容易被误判成「仓库没了」的情形，其实工作区文件都还在，值得花两分钟确认再决定动不动大刀。

四、逐条排查展开

第一条：先确认自己站在哪。 这是出现率最高的病因——开一个项目副本、解压了一份源码、或者终端还停留在上个目录，就敲了 git 命令。Git 的规则是从当前目录逐级向上找 .git，找到根目录为止，途中一个都没有就报这个错。确认动作：

pwd
ls -a | head
# 没有 .git 就 cd 到真正的仓库，或者确实要在这里建仓：
git init

注意区分「这不是仓库」和「这是空仓库」：fatal: your current branch 'master' does not have any commits yet 说明 .git 好好的，只是还没第一笔提交，不属于本篇范畴。

第二条：.git 被删。 清理脚本里一个 rm -rf */.git、或者「这个隐藏目录是干嘛的删掉省空间」，都能制造这个报错。工作区文件通常还在（Git 的恨铁不成钢之处：源码都在，历史没了）。处置顺序：有远端就 git clone 重拉一份、把工作区未提交的改动手工拷回去；没有远端就看备份。教训是任何批量清理命令先把 .git 加进排除列表。

第三条：.git 在但坏了。 断电、磁盘满、杀进程杀在写引用中途，都可能让 .git/HEAD 或某个 ref 文件变成空文件。确认：

cat /proj/demo/.git/HEAD
# 正常应类似 ref: refs/heads/master；空文件就是坏点
git fsck

HEAD 空了就手写回 ref: refs/heads/master；ref 文件空了就按 reflog 里的哈希重建。修不好时，重 clone 远端再把工作区盖回来是兜底。这类损坏的细节可对照 reset、revert、restore 三件套 与 reflog 找回丢失提交 里的引用修复思路。

第四条：GIT_DIR 环境变量误设。 有些部署脚本、裸仓库钩子教程会教你 export GIT_DIR=/srv/repo.git，设完忘了 unset，这个终端里的所有 git 命令就都被指去了别处——报错的措辞也变成 fatal: not a git repository: '/srv/repo.git' 这种带点名的变体。确认与处置：

env | grep GIT_
unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE

脚本里要用也请在命令行内联临时设置（GIT_DIR=/srv/repo.git git status），不要 export 到会话。

第五条：把 bare 仓库当工作区。 git clone --bare 或服务器上的 xxx.git 目录，本身就是「只有 .git 内容、没有工作区」的形态——进去敲 git status 必然报 not a git repository（它缺的正是「工作区视角」）。bare 仓库的职责是当远端被推来推去，日常开发永远 clone 出一份普通仓库来干活。建仓与克隆的完整区分见 Git 配置、init 与 clone 入门。

第六条：挂载点与 submodule 断链。 仓库放在 U 盘、NFS、Docker 卷上时，挂载一掉，Git 就顺着父目录找过了头，报错同样是这句。df . 看当前目录落在哪个挂载点上即可确认。submodule 场景则是 .git 不是目录而是一个文本文件（gitfile），里面写着 gitdir: ../.git/modules/xxx，父仓库被整体挪路径后这条指向就断了，用 git submodule absorbgitdirs 重新收纳或手工修正指向。子模块与远端协作的背景见 remote、pull、push 用法。

还有一个容易误判的变体：大小写与软链。 macOS 默认文件系统大小写不敏感，Linux 敏感——在 Mac 上 cd /Proj/Demo 能进，把同样习惯带到 Linux 服务器就进了另一个目录，那里没有 .git 自然报这个错。软链同理：ls -a 看到的是链接目标的内容，而某些自动化脚本用 -d .git 判断时对软链行为不一致。拿不准就用 pwd -P（物理路径）和 ls -ld .git 双重确认自己到底站在哪。

CI 里的高发剧本：checkout 步骤没跑或跑错目录。 流水线日志里满屏 not a git repository，十有八九是构建脚本的 cd 进了打包产物目录而不是源码目录，或者 checkout 步骤因为凭据问题被跳过。CI 里排这个错就一条：在报错命令前插一行 pwd && ls -a，下一次构建日志会直接告诉你答案。

五、规范做法与预防

• 远端永远可重 clone：代码不 push 等于没有备份，.git 丢了只要有远端就是十秒钟的事。
• 清理脚本排除 .git：find . -name .git -prune 是肌肉记忆级的写法。
• GIT_DIR 只内联不 export：写钩子/部署脚本时把变量绑在单条命令上，会话环境保持干净。
• 磁盘写满先停手：磁盘满时 git 写引用最容易写半截，先清空间再操作。
• 脚本里先判后跑：自动化脚本开头加 git rev-parse --is-inside-work-tree 守卫，不在仓库里直接退出并提示，而不是让后续命令连环炸。
• submodule 挪路径后立刻收纳：整个仓库搬家后第一件事跑 git submodule absorbgitdirs，别等哪天进子模块才发现 gitfile 断链。
• 重要仓库双远端：除了主远端再挂一个镜像远端（哪怕是自己另一台机器），.git 损坏时的兜底选项多一个。

这一篇在知识体系里的位置

本篇是 Git 排错速查簇的入口篇，定位「Git 不承认这里是仓库」：仓库正常、要理解日常三板斧看 status、add、commit 工作流；仓库定位没问题但推送/拉取失败看 Git push 被拒 non-fast-forward 速查 与 remote、pull、push 用法；认证环节报 Authentication failed 看 Git 认证失败速查；.git 内部引用损坏的找回手段看 tag、bisect、reflog；从零建仓的概念底座看 Git 配置、init 与 clone。

一句话总结

fatal: not a git repository 先跑两刀分档：env | grep GIT_ 排掉 GIT_DIR 误设（unset 即解），ls -a 看 .git 在不在——不在就 cd 回真仓库或重 clone，在但报错就 cat .git/HEAD + git fsck 查半截损坏，引用坏了手写重建、修不好就从远端重 clone 保工作区。bare 仓库只当远端不干活、清理脚本永远排除 .git、代码天天 push，这个报错基本绝迹。