davila7--claude-code-templates/cli-tool/components/skills/development/error-resolver/patterns/git.md

Git Error Patterns

Common Git errors with diagnosis and solutions.

Push/Pull Errors

Failed to push: rejected

! [rejected]        main -> main (non-fast-forward)
error: failed to push some refs to 'origin'

Causes:

1. Remote has commits you don't have locally
2. Force push required (history rewritten)
3. Branch protection rules

Solutions:

# Option 1: Pull and merge first (safest)
git pull origin main
git push origin main

# Option 2: Pull with rebase
git pull --rebase origin main
git push origin main

# Option 3: Force push (CAREFUL - overwrites remote)
# Only if you intentionally rewrote history
git push --force-with-lease origin main

---

Remote contains work you do not have locally

hint: Updates were rejected because the remote contains work that you do not have locally.

Same as above - pull first, then push.

# Standard workflow
git fetch origin
git merge origin/main  # Or: git rebase origin/main
git push

---

Permission denied (publickey)

Permission denied (publickey).
fatal: Could not read from remote repository.

Causes:

1. SSH key not added to agent
2. SSH key not added to GitHub/GitLab
3. Wrong SSH key
4. Using HTTPS URL instead of SSH

Diagnosis:

# Test SSH connection
ssh -T git@github.com
ssh -vT git@github.com  # Verbose for debugging

# Check loaded keys
ssh-add -l

Solutions:

# Add SSH key to agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519  # Or your key file

# Generate new key if needed
ssh-keygen -t ed25519 -C "your@email.com"

# Copy public key to GitHub/GitLab
cat ~/.ssh/id_ed25519.pub
# Then add in GitHub Settings -> SSH Keys

# Or use HTTPS instead of SSH
git remote set-url origin https://github.com/user/repo.git

---

Authentication failed

remote: Invalid username or password.
fatal: Authentication failed for 'https://github.com/...'

Causes:

1. Wrong credentials
2. Password auth disabled (GitHub)
3. Token expired

Solutions:

# Use Personal Access Token instead of password
# Generate at: GitHub -> Settings -> Developer settings -> Personal access tokens

# Update stored credentials
git credential reject
protocol=https
host=github.com
# Press Enter twice

# Or use credential helper
git config --global credential.helper cache
git config --global credential.helper 'cache --timeout=3600'

# Or switch to SSH
git remote set-url origin git@github.com:user/repo.git

---

Merge Conflicts

Automatic merge failed

CONFLICT (content): Merge conflict in file.js
Automatic merge failed; fix conflicts and then commit the result.

Resolution Workflow:

# 1. See conflicting files
git status

# 2. Open file and look for conflict markers
<<<<<<< HEAD
your changes
=======
their changes
>>>>>>> branch-name

# 3. Edit file to resolve (remove markers, keep desired code)

# 4. Stage resolved files
git add file.js

# 5. Complete merge
git commit
# Or if rebasing: git rebase --continue

Tools:

# Use merge tool
git mergetool

# Configure VS Code as merge tool
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'

Abort if needed:

git merge --abort
# Or
git rebase --abort

---

Cannot pull with rebase: unstaged changes

error: cannot pull with rebase: You have unstaged changes.

Solutions:

# Option 1: Stash changes
git stash
git pull --rebase
git stash pop

# Option 2: Commit changes first
git add .
git commit -m "WIP"
git pull --rebase

# Option 3: Discard changes (CAREFUL)
git checkout -- .
git pull --rebase

---

Checkout/Switch Errors

Cannot checkout: local changes would be overwritten

error: Your local changes to the following files would be overwritten by checkout

Solutions:

# Option 1: Stash changes
git stash
git checkout other-branch
git stash pop  # To get changes back

# Option 2: Commit changes
git add .
git commit -m "WIP"
git checkout other-branch

# Option 3: Discard changes (CAREFUL)
git checkout -- file.js      # Single file
git checkout -- .            # All files
git reset --hard             # Everything including staged

---

Pathspec did not match any file

error: pathspec 'branch-name' did not match any file(s) known to git

Causes:

1. Branch doesn't exist
2. Typo in branch name
3. Remote branch not fetched

Solutions:

# List all branches
git branch -a

# Fetch remote branches
git fetch origin

# Checkout remote branch
git checkout -b branch-name origin/branch-name
# Or (newer Git)
git switch branch-name

---

Reset/Revert Errors

HEAD detached

You are in 'detached HEAD' state.

What it means: You checked out a commit, not a branch.

Solutions:

# Go back to branch
git checkout main

# Create new branch from current state
git checkout -b new-branch-name

# See where HEAD is
git log --oneline -1

---

Cannot do soft reset with paths

fatal: Cannot do soft reset with paths.

Solution: Use different command:

# To unstage file
git restore --staged file.js
# Or older Git:
git reset HEAD file.js

---

Refusing to reset in dirty worktree

fatal: Failed to resolve 'HEAD~1' as a valid ref.

Solution:

# Stash changes first
git stash
git reset --hard HEAD~1
git stash pop

---

Stash Errors

No stash entries found

No stash entries found.

Check stashes:

# List all stashes
git stash list

# If empty, nothing was stashed

---

Conflict when applying stash

CONFLICT (content): Merge conflict in file.js

Solutions:

# Resolve conflicts manually (same as merge conflicts)
# Then either:
git stash drop  # Remove stash after resolving

# Or if you want to keep stash:
# Just resolve conflicts, add, and commit

---

Rebase Errors

Cannot rebase: uncommitted changes

error: cannot rebase: You have unstaged changes.

Solution:

git stash
git rebase origin/main
git stash pop

---

Rebase conflict

CONFLICT (content): Merge conflict in file.js
error: could not apply abc1234... commit message

Resolution:

# 1. Fix conflicts in files

# 2. Stage resolved files
git add file.js

# 3. Continue rebase
git rebase --continue

# Or abort entire rebase
git rebase --abort

# Skip this commit (lose its changes)
git rebase --skip

---

Submodule Errors

Submodule not initialized

fatal: no submodule mapping found in .gitmodules for path 'submodule-path'

Solutions:

# Initialize submodules
git submodule init
git submodule update

# Or clone with submodules
git clone --recurse-submodules repo-url

# Update existing clone
git submodule update --init --recursive

---

Submodule HEAD detached

HEAD detached at abc1234

Solution:

cd submodule-path
git checkout main  # Or desired branch
cd ..
git add submodule-path
git commit -m "Update submodule to main"

---

LFS Errors

File exceeds GitHub file size limit

remote: error: File large-file.zip is 150.00 MB; this exceeds GitHub's file size limit of 100.00 MB

Solutions:

# Install Git LFS
brew install git-lfs  # macOS
git lfs install

# Track large files
git lfs track "*.zip"
git lfs track "*.psd"
git add .gitattributes

# If already committed, need to rewrite history
git filter-branch --tree-filter 'git lfs track "*.zip"' HEAD
# Or use BFG Repo Cleaner

---

LFS objects missing

Encountered 1 file that should have been a pointer, but wasn't

Solutions:

# Fetch LFS objects
git lfs fetch --all

# Or pull LFS objects
git lfs pull

# Migrate existing files to LFS
git lfs migrate import --include="*.psd"

---

Configuration Errors

Author identity unknown

Author identity unknown
Please tell me who you are.

Solution:

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

---

Unsafe repository

fatal: detected dubious ownership in repository

Causes: Repository owned by different user (common in Docker/WSL).

Solution:

# Add exception for this repo
git config --global --add safe.directory /path/to/repo

# Or for all repos (less secure)
git config --global --add safe.directory '*'

---

Quick Reference Table

Error	Category	Quick Fix
Push rejected	Push	git pull --rebase then push
Permission denied	Auth	Check SSH key: ssh-add -l
Auth failed	Auth	Use Personal Access Token
Merge conflict	Merge	Edit file, remove markers, git add
Unstaged changes	Checkout	git stash first
Pathspec not found	Branch	git fetch then checkout
HEAD detached	Branch	git checkout main
No stash entries	Stash	Nothing was stashed
Rebase conflict	Rebase	Fix conflict, git rebase --continue
File too large	LFS	Use Git LFS for large files
Identity unknown	Config	Set user.email and user.name