[ PROMPT_NODE_24697 ]
Git
[ SKILL_DOCUMENTATION ]
# 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**:
```bash
# 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.
```bash
# 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**:
```bash
# Test SSH connection
ssh -T [email protected]
ssh -vT [email protected] # Verbose for debugging
# Check loaded keys
ssh-add -l
```
**Solutions**:
```bash
# 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 "[email protected]"
# 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**:
```bash
# 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 [email protected]: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**:
```bash
# 1. See conflicting files
git status
# 2. Open file and look for conflict markers
<<<<<<>>>>>> 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**:
```bash
# 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**:
```bash
git merge --abort
# Or
git rebase --abort
```
---
### Cannot pull with rebase: unstaged changes
```
error: cannot pull with rebase: You have unstaged changes.
```
**Solutions**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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:
```bash
# 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**:
```bash
# 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**:
```bash
# List all stashes
git stash list
# If empty, nothing was stashed
```
---
### Conflict when applying stash
```
CONFLICT (content): Merge conflict in file.js
```
**Solutions**:
```bash
# 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**:
```bash
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**:
```bash
# 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**:
```bash
# 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**:
```bash
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**:
```bash
# 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**:
```bash
# 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**:
```bash
git config --global user.email "[email protected]"
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**:
```bash
# 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 |
Source: claude-code-templates (MIT). See About Us for full credits.