Git Troubleshooting

Introduction

Git error messages look cryptic until you know the pattern. This chapter collects frequent failures—wrong directory, identity not set, push rejected, merge conflicts, detached HEAD, and recovery after reset --hard—with step-by-step fixes you can reuse on any project.

Prerequisites

Chapters through Git and CI/CD or equivalent experience
Terminal and optional access to a test repo

fatal: not a git repository

text

fatal: not a git repository (or any of the parent directories): .git

Cause: current folder has no .git—not initialized or wrong directory.

Fix:

bash

cd path/to/your/project
git status

Or initialize:

bash

git init

Please Tell Me Who You Are

text

Please tell me who you are.
Run git config user.email ...

Fix:

bash

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

See Git Configuration.

failed to push / rejected

text

! [rejected] main -> main (non-fast-forward)

Remote has commits you lack.

Fix:

bash

git fetch origin
git pull origin main
# resolve conflicts if any
git push origin main

On feature branch: rebase or merge main, then push.

Permission errors: check Authentication—SSH key or PAT.

merge conflict During pull or merge

text

CONFLICT (content): Merge conflict in file.txt

Fix workflow:

Open conflicted files—remove <<<<<<<, =======, >>>>>>>
git add file.txt
git commit (merge) or git rebase --continue

Full guide: Resolving Merge Conflicts.

detached HEAD

Message when checkout commit or tag directly:

text

You are in 'detached HEAD' state.

You can look around; new commits are orphaned unless you create a branch:

bash

git switch -c recover-work

Or return to branch:

bash

git switch main

Recover After git reset --hard

Accidentally wiped commits:

bash

git reflog

Example output:

text

a1b2c3d HEAD@{0}: reset: moving to HEAD~3
e4f5g6h HEAD@{1}: commit: Important feature

Restore:

bash

git reset --hard e4f5g6h

Code explanation:

reflog keeps local HEAD moves ~90 days—rescue before garbage collection

Warning

Reflog Is Local

Pushed history others depend on still needs revert, not reset, on shared branches.

Large File Committed by Mistake

Symptoms: huge push, GitHub file size limit error.

Prevention: .gitignore, hooks Git Hooks.

Removal from history requires git filter-repo or BFG—rewrites history; coordinate with team. Concept only for learners—backup first.

.git Directory Too Large

Many binaries or long history:

bash

git count-objects -vH
git gc --prune=now

Use Git LFS for large assets (advanced topic)—track *.psd, big videos.

Common Status Messages

Message	Meaning
`Your branch is ahead of 'origin/main' by 2 commits`	Push pending
`Your branch is behind ...`	Pull pending
`nothing to commit, working tree clean`	All saved
`Untracked files`	Git not tracking—`git add` or ignore

Diagnostic Commands

bash

git status
git remote -v
git branch -vv
git log --oneline -5
git config --list --show-origin
ssh -T git@github.com

Run in repo root when debugging.

FAQ

Everything broken—start over?

Clone fresh copy; copy uncommitted work from old folder—last resort.

Corrupt repository?

git fsck finds bad objects; restore from remote clone if local-only corrupt.

Credential keeps failing?

Clear cached wrong password; regenerate PAT; verify remote URL.

Submodule errors?

Advanced—git submodule update --init if project uses submodules.

Windows path too long?

Enable long paths in Git for Windows settings or shorten directory depth.

Still stuck?

Copy exact error into search or git help topic—message usually names the fix.