Skip to main content

Git Troubleshooting

Common Git problems and their solutions.

Authentication Issues​

"You need to sign in to GitHub"​

Solution: VS Code will open a browser. Sign in to GitHub and authorize VS Code.

If browser doesn't open:

  1. Go to GitHub.com and sign in
  2. Go to Settings → Developer settings → Personal access tokens
  3. Generate a new token with repo scope
  4. Use this token as password when Git asks

"Permission denied" when pushing​

Cause: You're not a member of the repository.

Solution: Contact IT Lead to be added to the repository with appropriate permissions.

Push/Pull Issues​

"rejected - non-fast-forward"​

Cause: Someone else pushed changes while you were working.

Solution:

# Pull latest changes first
git pull origin [branch-name]

# Resolve any conflicts if prompted

# Then push again
git push

"Your branch is behind"​

Cause: Remote has changes you don't have locally.

Solution:

git pull origin [branch-name]

Or in VS Code: Click the Sync button (↑↓)

"failed to push some refs"​

Cause: Multiple possible causes.

Solution:

# First, fetch and check status
git fetch origin
git status

# If behind, pull first
git pull origin [branch-name]

# Then push
git push

Branch Issues​

"Detached HEAD" warning​

Cause: You're not on a proper branch.

Solution: Click the branch name in VS Code bottom-left and select a real branch (main or develop).

Or in terminal:

git checkout develop

"Cannot delete branch" that you're on​

Cause: You can't delete the branch you're currently on.

Solution:

# Switch to a different branch first
git checkout develop

# Then delete the other branch
git branch -d feature/old-branch

Can't switch branches - uncommitted changes​

Cause: You have changes that would be overwritten.

Solutions:

Option 1: Commit your changes

git add .
git commit -m "WIP: saving changes"

Option 2: Stash your changes

git stash
git checkout other-branch
# Later, restore with:
git stash pop

Option 3: Discard changes (careful!)

git checkout -- .

Commit Issues​

Accidentally committed to wrong branch (main/develop)​

If you haven't pushed yet:

# Move the commit to a new branch
git branch feature/my-changes

# Reset the current branch
git reset --hard HEAD~1

# Switch to new branch
git checkout feature/my-changes

If you already pushed:

danger

DON'T try to fix this yourself. Contact IT Lead immediately for help reverting.

Want to undo last commit but keep changes​

# Undo commit, keep changes staged
git reset --soft HEAD~1

# Or undo commit, keep changes unstaged
git reset HEAD~1

Commit message was wrong​

Before pushing:

git commit --amend -m "New correct message"

After pushing: Create a new commit instead - don't try to change history.

Merge Issues​

PR says "Can't automatically merge"​

Cause: There are conflicts between your branch and the target branch.

Solution:

# Update your branch with latest develop
git checkout your-branch
git fetch origin
git merge origin/develop

# Resolve conflicts in VS Code
# Then commit and push
git add .
git commit -m "Resolve merge conflicts"
git push

Merge conflict - don't know what to do​

Solution:

  1. Don't panic! You can always abort:

    git merge --abort

  2. If you want to resolve:

    • Open conflicted file in VS Code
    • Look for <<<<<<<, =======, >>>>>>>
    • Click "Accept Current" or "Accept Incoming" or edit manually
    • Remove all conflict markers
    • Save the file
    • Stage and commit

Merge went wrong, want to start over​

# Abort the merge
git merge --abort

# Go back to clean state
git checkout develop
git pull origin develop

# Try again

File Issues​

Made changes but don't see them in Source Control​

Checklist:

  1. Did you save the file? (Ctrl+S)
  2. Are you in the right folder?
  3. Is the file inside the Git repository?

Check which folder Git is tracking:

git rev-parse --show-toplevel

Want to discard all my local changes​

# Discard unstaged changes
git checkout -- .

# Also remove untracked files (careful!)
git clean -fd

Accidentally deleted a file​

If not committed:

git checkout -- [filename]

If committed but not pushed:

git reset HEAD~1

If pushed:

# Restore from the previous commit
git checkout HEAD~1 -- [filename]
git add [filename]
git commit -m "Restore deleted file"
git push

VS Code Issues​

Git features not working in VS Code​

Solutions:

  1. Restart VS Code
  2. Open the folder directly (File → Open Folder)
  3. Make sure you're in the repo folder, not a parent folder
  4. Check Git is installed: Open terminal, type git --version

Source Control panel is empty​

Cause: VS Code may not recognize the folder as a Git repository.

Solutions:

  1. Open the correct folder (the one with .git folder)
  2. Reload VS Code (Ctrl+Shift+P → "Reload Window")
  3. Check if .git folder exists: 
    ls -la  # Should show .git directory

Getting Help​

When to Ask for Help​

  • Before doing anything that affects main or develop directly
  • When you see an error you don't understand
  • If a merge conflict involves code you didn't write
  • When in doubt about any destructive action

What to Include When Asking​

  1. The command you ran - exact command
  2. The error message - full text
  3. What you were trying to do - context
  4. What branch you're on - git branch

Quick Status Check​

Run these to understand your current state:

git status           # What's changed?
git branch           # What branch am I on?
git log --oneline -5 # Last 5 commits

Prevention Tips​

  1. Pull before you start - Always get latest code
  2. Commit often - Small, frequent commits are easier to undo
  3. Push daily - Back up your work
  4. Use branches - Never work directly on main/develop
  5. Read before confirming - Check what Git is about to do
  6. Ask if unsure - It's better to ask than to break something