From 54c6a86858b5138bdc16cf3799b270845c61558b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=AE=B8=E6=9D=B0=E5=8F=8B=20Jieyou=20Xu=20=28Joe=29?=
 <39484203+jieyouxu@users.noreply.github.com>
Date: Mon, 2 Dec 2024 12:38:56 +0800
Subject: [PATCH] Explain how to deal with exploded git submodules (#2152)

---
 src/git.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/src/git.md b/src/git.md
index 90dbc3fb1..75e9d1f04 100644
--- a/src/git.md
+++ b/src/git.md
@@ -597,6 +597,27 @@ $ git submodule foreach git reset --hard
 
 and then try `git submodule update` again.
 
+Unfortunately sometimes your local git submodules configuration can become
+completely messed up for some reason.
+
+### Overcoming `fatal: not a git repository: <submodule>/../../.git/modules/<submodule>`
+
+Sometimes, for some forsaken reason, you might run into
+
+```text
+fatal: not a git repository: src/gcc/../../.git/modules/src/gcc
+```
+
+In this situation, for the given submodule path, i.e. `<submodule_path> =
+src/gcc` in this example, you need to:
+
+1. `rm -rf <submodule_path>/.git`
+2. `rm -rf .git/modules/<submodule_path>/config`
+3. `rm -rf .gitconfig.lock` if somehow the `.gitconfig` lock is orphaned.
+
+Then do something like `./x fmt` to have bootstrap manage the submodule
+checkouts for you.
+
 ## Ignoring commits during `git blame`
 
 Some commits contain large reformatting changes that don't otherwise change functionality. They can