Resolve Conflicts with Main Branch

Sync the current branch with main and resolve any merge or rebase conflicts.

Prerequisites

• Current branch is not main or master (if it is, create a feature branch first).
• Working directory is clean, or user is aware uncommitted changes may need stashing.

Workflow

Step 1: Confirm Branch and Status

git branch --show-current
git status

If there are uncommitted changes, ALWAYS use the AskQuestion tool:

• Title: "Uncommitted Changes Detected"
• Question: "You have uncommitted changes. How would you like to proceed?"
• Options:
  • id: "stash", label: "Stash them and continue"
  • id: "abort", label: "Abort, I'll commit them first"

Based on the response:

• "stash" → Run git stash push -m "WIP before syncing with main" and continue
• "abort" → Stop the workflow

Step 2: Fetch Latest Main

git fetch origin main

Use master instead of main if the default branch is master in this repo.

Step 3: Choose Merge vs Rebase

• Merge: Preserves full history, creates a merge commit. Safer for shared branches.
• Rebase: Linear history, no merge commit. Prefer for local/feature branches.

Default to merge unless the user asks for rebase or the project convention is rebase.

Merge:

git merge origin/main

Rebase:

git rebase origin/main

Step 4: Detect Conflicts

If the command exits with a conflict (non-zero exit or message like "CONFLICT"):

git status

Note every file listed as "both modified" or "Unmerged paths".

Step 5: Resolve Each Conflicted File

For each conflicted file:

1. Open the file and find conflict markers:

   • <<<<<<< HEAD (your branch)
   • =======
   • >>>>>>> origin/main (or commit hash)

2. Decide the correct result: keep one side, combine both, or write new content. Remove the markers and leave the intended final text.

3. Stage the resolved file:

   git add <path>
   

If the user wants to accept one side entirely for a file:

• Keep current branch version:

  git checkout --ours <path>
  git add <path>
  

• Keep main's version:

  git checkout --theirs <path>
  git add <path>
  

(For rebase, "ours" is the branch being rebased onto, "theirs" is the current branch—semantics are reversed vs merge. Prefer editing the file when unsure.)

Step 6: Complete the Operation

After merge:

git status   # confirm no unmerged paths
git commit -m "Merge origin/main into <branch-name>"

After rebase:

git status   # confirm clean
git rebase --continue

If more conflicts appear, repeat from Step 4. To abort rebase:

git rebase --abort

Step 7: Verify

git log --oneline -5
git status

Confirm history looks correct and working tree is clean.

Optional: Restore Stash

If you stashed in Step 1:

git stash list
git stash pop

Resolve any stash conflicts the same way (edit markers, then git add).

Safety Rules

• Do not force push to fix conflicts unless the user explicitly requests it (e.g. after rebase on a shared branch).
• Do not run git merge --abort or git rebase --abort unless the user asks to cancel the sync.
• Prefer resolving by editing files so the user sees and approves the result; use --ours/--theirs only when the user clearly wants one side entirely.