“needs merge” + “resolve your current index first”

Real error I hit on the my work backend backend while switching branches.

$ git checkout org-migration
controllers/SystemController.js: needs merge
error: you need to resolve your current index first

What actually happened

I was on org-migration-DA. Earlier I had started a merge into that branch (git merge something or git pull). That merge hit a conflict in controllers/SystemController.js and I never finished it. Git left the merge in progress and recorded that file as “needs merge” in the index.

Then I tried to git checkout to a different branch — and Git blocked me.

The two pieces of vocabulary

So “resolve your current index first” = “You have an unfinished merge sitting in your staging area. Finish it or cancel it before you walk away to another branch.”

The mental model

You opened surgery on a file, didn’t stitch it back up, and now you’re trying to walk out of the operating room. Git stops you at the door — leaving mid-merge would lose track of the conflict.

How to confirm what state you’re in

git status                 # look for "You have unmerged paths"
git rev-parse MERGE_HEAD   # prints a hash = a merge really is in progress

In my case git status showed ~13 files already staged and one still conflicted:

Unmerged paths:
  both modified:   controllers/SystemController.js

both modified = the same lines changed on both branches; Git won’t guess which to keep.

Two ways out

Option A — Finish the merge (keep the work)

1. Open the conflicted file. Find the markers:

   <<<<<<< HEAD
   my version
   =======
   their version
   >>>>>>> org-migration
   

2. Edit so the final code is correct. Delete all three marker lines.
3. Mark it resolved and commit:

   git add controllers/SystemController.js
   git commit            # completes the merge
   

4. Now git checkout org-migration works.

Option B — Abort the merge (throw it away)

git merge --abort        # restores the branch to before the merge started

Use this when the merge was a mistake or you want a clean slate. Then checkout freely.

The lesson

• A merge conflict isn’t an error — it’s Git asking you to make a decision it can’t make safely.
• Git won’t let you switch branches mid-merge because that would silently lose state. The “annoying” block is actually protecting your work.
• Finish what you start. Always close out a merge (commit or --abort) before moving on — don’t leave a repo half-merged.

What I actually did (and why it was safe)

I didn’t want the merge — I just wanted the org-migration branch’s code. So:

git merge --abort        # cancel the stuck merge on org-migration-DA
git checkout org-migration
git pull                 # fast-forward to the latest remote code

This worried me at first — was I deleting work? No. Here’s the key insight:

merge --abort ≠ deleting commits

• git merge --abort only undoes the in-progress merge in your working tree. It rewinds the branch to exactly where it was before the merge started. Existing commits are untouched.
• Switching branches doesn’t touch the branch you left. org-migration-DA still exists, with all its history, exactly as before. I just stepped off it.
• Even a merge I did abort isn’t truly gone — Git keeps a safety net in the reflog (git reflog) for a while, so an aborted/abandoned state is usually recoverable.

So the operation was non-destructive on every axis: the merge was only in-progress (nothing committed), the old branch was left alone, and switching branches is reversible.

Mental model

Think of branches as separate save files. Aborting a merge is like hitting “undo” inside one save file. Switching branches is like loading a different save file — it doesn’t erase the one you were in.

One-line summary

“needs merge / resolve your current index first” = there’s an unfinished merge in your staging area. Resolve + git add + git commit, or git merge --abort. Then you’re free to move.

And don’t panic: merge --abort and switching branches are non-destructive — the branch you leave keeps all its work.