fatal: not a git repository — five causes, one command

■ space · the walk probe · fig 1

Git walks up the tree hunting .git, quits at the first one — five things break that hunt, one command splits them.

■ the answer first

Run git rev-parse --show-toplevel || ls -a — one command splits the causes before you touch anything.

Root printed → you're standing outside the repo; cd there. No .git in ls -a → there was never a repo: re-clone, don't git init.

Error in every repo on the machine → an exported GIT_DIR; unset GIT_DIR.

5causes behind one fatal line

1command splits them

20minutes the folder-above guess costs

01THE WALK

git hunts one entry, upward, and stops at the first — the machine replays the hunt

FIG 1 · THE WALK PROBEkeys 1–6 — or the buttons

the probe

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

FOUND — THE WALK STOPPED AT .GITfix — nothing to fix: the walk is healthy

START src/api/ · FLOORS TAPPED 2 · VERDICT FOUND

you are here → you typed git pull here → the walk stops here, at the first .git it meets

02THE CAUSE TABLE

five things break the hunt — match your symptom to a row

symptom	likely cause	fix
error in one project, `ls -a` shows no `.git`	ZIP download / copied files	`git clone` again
error from a subfolder, root works	standing outside the tree	`cd "$(git rev-parse --show-toplevel)"`
error in every directory, even ones that worked	`GIT_DIR` exported	`unset GIT_DIR`, purge it from the shell profile
error inside a submodule folder	submodule not initialized	`git submodule update --init --recursive`
`.git` is a file, error persists	dangling worktree/submodule pointer	`git worktree repair`, else re-clone

verify: git rev-parse --show-toplevel → the repo root path, no error

03THE FIRST TWO LIE

the table fixes symptoms; the first two causes are where muscle memory lies

the subfolder shape—you cd'd into docs/ or src/api/ and the shell habit says the root is here — git walks up, finds nothing, quits

the clone shape—git clone always creates a subdirectory named after the repo — the checkout sits one level below where you're standing

the zip shape—Code → Download ZIP ships the source snapshot only: no .git, no history, no remote

the copied shape—files copied without the hidden folder — a cleanup tool that deleted .git as "hidden junk" ends the same way

jump to the root — works from any depth inside the repo

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

there was never a repo — recover the history

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

git init doesn't repair a repo — it creates an empty one where you stand.

04THE LAST THREE FOLLOW YOU

the remaining three are environmental — the error exports, dangles, or was never born

the tell: git worked here an hour ago

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

GIT_DIR exported—one fixed path replaces discovery, so every "ordinary" directory becomes "not a repository" — if it returns each morning, a line in ~/.bashrc, ~/.zshrc, or a CI wrapper exports it: purge it there

dead pointer—.git as a one-line file names a directory elsewhere on disk; the target moved or deleted → the pointer dangles and the error persists even though .git "is right there" — git worktree repair re-links what it can, anything else: re-clone

submodule—the folder exists in the parent repo's tree but was never initialized — there's no .git in it yet; git submodule update --init --recursive from the parent fills it in

untracked strays ride along with copied trees — a clean pass settles them once the clone is in place

■ honest stamp Tested on: git 2.4x · bash + zsh · submodules and worktrees. First published 2026-09-28. The walk-up search, the GIT_DIR override and the worktree pointer file are git's documented discovery behaviour; the five causes are the complete set behind this error, typed from repos that came back.

end of the five causes · nothing fetched · everything local