Goal

• Given a repo with unresolved Git conflicts, find why each conflict happened, resolve it, verify the result, and finalize the operation

Workflow

Identify the Operation In Progress

• Check whether the repo is in a merge, rebase, or cherry-pick. Finalizing differs by operation

  > ls -a .git | grep -E "MERGE_HEAD|rebase-merge|rebase-apply|CHERRY_PICK_HEAD"
  

• Note <SOURCE>, the branch or commit being merged, rebased, or cherry-picked, and <TARGET>, the branch with existing history (e.g., main for a merge, or the branch rebased onto)

Find the Files with Conflicts

• List the files with conflicts:

  > git diff --name-only --diff-filter=U
  

Understand the Context

• Read the PR description, if any:

  > gh pr view
  

  • If no PR is open, gh pr view fails: skip it and use commit history
• Read the commits on <SOURCE> and <TARGET> that lead to the conflict, to learn the intent of each side:

  > git log <TARGET>..<SOURCE>
  > git log <SOURCE>..<TARGET>
  

Propose Fixes

• For each file with conflicts:

  • List every conflict hunk (a file can have several <<<<<<< / ======= / >>>>>>> blocks)
  • For each hunk, or group of similar hunks, explain the cause and propose a fix

• Example

  1. tutorials/GitHub_Stats/Master_GitHub_analysis.py
     - **Issue**: Jupytext version conflict.
     - **Resolution**: Use <TARGET>, it's the newer version.
  
  2. tutorials/GitHub_Stats/docker_jupyter.sh
     - **Issue**: <SOURCE> adds -e GITHUB_ACCESS_TOKEN to Docker env; <TARGET>
       removes it.
     - **Resolution**: Use <TARGET> (remove the line)
  

• If unsure, prefer the changes from <SOURCE> over <TARGET>

  • <TARGET>'s history is already saved, but discarding <SOURCE>'s changes could lose them permanently

Ask User and Apply the Changes

• Ask the user which resolution to apply for each ambiguous case
• Edit each conflicted file to remove the markers and apply the chosen resolution
• Confirm no conflict markers remain:

  > grep -rn '^<<<<<<<\|^=======\|^>>>>>>>' <RESOLVED_FILES>
  

• Stage each resolved file:

  > git add <FILE>
  

Finalize the Operation

• You MUST ask for user permission before finalizing, per the repo rule of never committing without permission
• Once approved, finalize per the operation identified above:
  • merge: git commit
  • rebase: git rebase --continue
  • cherry-pick: git cherry-pick --continue
• Do not skip hooks (e.g., --no-verify) or force anything unless the user explicitly asks for it

Verification

• Run the related unit tests
• Confirm no conflict markers <<<<<<< / ======= / >>>>>>> remain
• Confirm the operation finished cleanly:

  > git status
  

• The file plan.md says that it was generated by .claude/skills/git.merge_conflicts/SKILL.md

Ask for Help If Unsure How to Do

• If the task is not perfectly clear, you MUST not perform it, but ask for clarifications
  • For a complex task, create plan.md with 5 bullet points explaining the plan
  • Say in plan.md how it was generated, with this line as the first bullet:

    - Generated by `.claude/skills/git.merge_conflicts/SKILL.md`