🔧 FAQ & Troubleshooting

Issue 1: Detached HEAD

# Scenario: You checked out a specific commit
git checkout a1b2c3d
Note: switching to 'a1b2c3d'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

# Don't panic! Detached HEAD just means you're not on any branch.
# If you want to develop from here, create a new branch:
git switch -c my-experiment

# If you just want to look around, switch back to a normal branch:
git switch main

💡 Tip: Detached HEAD is not an error! It's useful when viewing history or debugging old versions. Only if you make commits in detached state without creating a branch might those commits be "lost" (though reflog can still find them).

Issue 2: Unresolvable Merge Conflicts

# If the conflict is too complex and you want to abort
git merge --abort

# If it's a conflict during rebase
git rebase --abort

# If it's a conflict during cherry-pick
git cherry-pick --abort

Issue 3: "Lost" Commits

# Scenario: After git reset --hard, you realize you still needed something

# Step 1: Don't close the terminal! Don't run other commands!

# Step 2: Check reflog
git reflog
f4e5d6c HEAD@{0}: reset: moving to HEAD~1
d4e5f6a HEAD@{1}: commit: feat: this commit was reset
f4e5d6c HEAD@{2}: commit: feat: add welcome message
a1b2c3d HEAD@{3}: commit (initial): feat: create homepage

# Step 3: Find the lost commit
git show d4e5f6a

# Step 4: Recover
# Option A: Reset directly back
git reset --hard d4e5f6a

# Option B: Create a new branch pointing to that commit
git branch recovery d4e5f6a

Issue 4: Push Rejected

# Scenario: git push was rejected
git push
! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'github.com:yourname/website.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally.

# Reason: The remote has commits you don't have locally

# Solution 1: Pull then push (recommended)
git pull --rebase origin main
git push

# Solution 2: If you just need to push amended commits, force push
# ⚠️ Dangerous! Only use on your own branches!
git push --force-with-lease origin feature/my-branch

⚠️ Warning: git push --force is a dangerous operation that can overwrite remote commits. If you must force push, use --force-with-lease, which prevents you from overwriting when there are new remote commits — an extra safety net compared to --force.

Issue 5: Committed Files You Didn't Mean to Commit

# Scenario: You accidentally committed the .env file (it has passwords!)

# Step 1: Remove from Git (but keep local file)
git rm --cached .env
rm '.env'

# Step 2: Add to .gitignore
echo ".env" >> .gitignore

# Step 3: Commit the change
git add .gitignore
git commit -m "chore: remove .env file and add to gitignore"

# Step 4: If already pushed to remote, it's still in history!
# Need to use git filter-branch or BFG to clean history:
# Recommended: BFG Repo-Cleaner (simpler and faster)
# java -jar bfg.jar --delete-files .env

# ⚠️ Important: If the password has been leaked, change it immediately!
# Cleaning history is just a measure; changing the password is the real fix.

Issue 6: Permission Denied

# SSH permission issue
git push
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

# Troubleshooting steps:

# 1. Check if SSH key exists
ls -la ~/.ssh/
total 16
drwx------  2 yourname yourname 4096 Jun 20 10:00 .
-rw-------  1 yourname yourname  411 Jun 20 10:00 id_ed25519
-rw-r--r--  1 yourname yourname  102 Jun 20 10:00 id_ed25519.pub
-rw-r--r--  1 yourname yourname  812 Jun 20 10:00 known_hosts

# 2. Test SSH connection
ssh -T git@github.com
Hi yourname! You've successfully authenticated, but GitHub
does not provide shell access.

# 3. If connection fails, check if ssh-agent is running
eval "$(ssh-agent -s)"
Agent pid 12345

# 4. Add key to ssh-agent
ssh-add ~/.ssh/id_ed25519