Hands-onLesson 8 of 9

Troubleshooting

Solve common Git and GitHub issues quickly: merge conflicts, bad commits, rejected pushes, detached HEAD, and PR check failures.

Simple Explanation (ELI5)

Most Git problems are recoverable. The trick is knowing where you are (status/log), what changed, and choosing the right safe command to fix it.

Technical Explanation

Troubleshooting is state management: branch state, working tree state, staging state, and remote divergence. Use inspection commands first, then apply minimal corrective action.

Issue 1: Merge Conflict

bash
# Update branch
git fetch origin
git rebase origin/main

# Conflict appears: edit markers <<<<<<< ======= >>>>>>>
# Resolve file content manually

# Mark resolved
git add src/config/app.ts

# Continue rebase
git rebase --continue

# If needed, abort
git rebase --abort

Issue 2: Wrong Commit Message / Forgot File

bash
# Add missing file
git add src/new-file.ts

# Update last commit
git commit --amend -m "feat(api): add user settings endpoint"

# If already pushed, update remote carefully
git push --force-with-lease

Issue 3: Push Rejected (non-fast-forward)

bash
git fetch origin
git rebase origin/main
# Resolve conflicts if any
git push origin feature/my-branch

Issue 4: Detached HEAD

bash
# Save current detached work into branch
git checkout -b fix/detached-head-work

# Return to normal branch flow
git checkout main

Issue 5: Recover Lost Commit

bash
# Inspect recent HEAD movements
git reflog

# Recover commit by hash
git cherry-pick abc1234
# OR reset branch to that point
git reset --hard abc1234

Quick Diagnostic Checklist

QuestionCommand
Where am I?git status
What changed?git diff, git diff --staged
What history exists?git log --oneline --graph --decorate
What remotes?git remote -v
What branch state?git branch -vv

Real-world Use Case

During release prep, a developer accidentally force-pushed an outdated branch state. Team recovered all lost commits within minutes using reflog and protected branch backups, avoiding downtime and preserving audit history.

Interview Questions

Beginner

What causes merge conflicts?▾

Concurrent edits to overlapping lines in the same file across branches.

How do you abort a rebase?▾

Run git rebase --abort.

What is reflog used for?▾

Recovering references to commits after resets/rebases/accidental moves.

Why use force-with-lease not force?▾

It prevents overwriting remote updates you have not seen.

First command in any Git problem?▾

git status to inspect current repository state.

Intermediate

Reset soft vs mixed vs hard?▾

Soft keeps staged changes, mixed keeps working tree only, hard discards both staged and working tree changes.

How handle conflict in binary files?▾

Choose one side or regenerate artifact; manual merge markers are not possible.

When cherry-pick is preferred?▾

To apply a specific fix commit to another branch without full branch merge.

Why might PR checks fail only in CI?▾

Different runtime, env vars, dependency versions, or stricter CI scripts.

How avoid recurring conflicts in same file?▾

Refactor ownership boundaries and reduce parallel edits on shared hotspots.

Scenario-based

You force-pushed over teammate’s commit. Recovery?▾

Use reflog to find missing commit, restore/cherry-pick it, and communicate before next push.

Massive conflict after long-lived branch. Plan?▾

Split conflict resolution by subsystem, involve module owners, and run full regression tests.

Wrong file merged to main.▾

Revert offending commit/PR immediately and apply corrected change in a new PR.

PR blocked by required check that no longer exists.▾

Update branch protection rules to current workflow job names.

Developer lost local changes after hard reset.▾

Check reflog, recover previous HEAD commit, and reinforce safer workflow with stash/feature commits.

Summary

Most Git issues are recoverable with calm, state-first diagnosis. Learn inspection commands deeply and apply the smallest safe fix.

← Back to Course