Provides comprehensive guidelines for resolving merge conflicts intelligently using git history and commit context. Use when tasks involve merge conflicts, rebasing, PR conflicts, or git conflict resolution. This skill analyzes commit messages, git blame, and code intent to make intelligent resolution decisions.
Use this skill when the task involves:
Do NOT use this skill when:
This skill resolves merge conflicts by analyzing git history, commit messages, and code changes to make intelligent resolution decisions. Given a PR number (e.g., "#123"), it handles the entire conflict resolution process.
Extract the PR number from input like "#123" or "PR #123". Validate that a PR number was provided.
gh pr view [PR_NUMBER] --json title,body,headRefName,baseRefName
Get PR title and description to understand the intent and identify the source and target branches.
gh pr checkout [PR_NUMBER] --force
git fetch origin main
GIT_EDITOR=true git rebase origin/main
GIT_EDITOR=true to ensure non-interactive rebasegit status --porcelain
git diff --name-only --diff-filter=U
Identify files with merge conflicts (marked with 'UU') and create a list of files that need resolution.
Analyze each conflicted file to understand the changes:
<<<<<<< and >>>>>>>Determine the best resolution strategy for each conflict:
Apply the resolution strategy to resolve conflicts:
git addVerify the resolution and prepare for commit:
git status to confirm all conflicts are resolved| Command | Purpose |
|---|---|
gh pr checkout [PR_NUMBER] --force | Force checkout the PR branch |
git fetch origin main | Get the latest main branch |
GIT_EDITOR=true git rebase origin/main | Rebase current branch onto main (non-interactive) |
git blame -L [start],[end] [commit] -- [file] | Get commit information for specific lines |
git show --format="%H%n%an%n%ae%n%ad%n%s%n%b" --no-patch [sha] | Get commit metadata |
git show [sha] -- [file] | Get the actual changes made in a commit |
git ls-files -u | List unmerged files with stage information |
GIT_EDITOR=true git rebase --continue | Continue rebase after resolving conflicts |
Always prioritize understanding the intent behind changes rather than just looking at the code differences. Commit messages, PR descriptions, and issue references provide crucial context.
Example: When there's a conflict between a bugfix and a refactor, apply the bugfix logic within the refactored structure rather than simply choosing one side.
When possible, combine non-conflicting changes from both sides rather than discarding one side entirely. Both sides of a conflict often contain valuable changes that can coexist if properly integrated.
When using apply_diff, always escape merge conflict markers with backslashes to prevent parsing errors:
\<<<<<<< HEAD<<<<<<< HEADLook beyond the immediate conflict to understand related changes in tests, documentation, or dependent code. A change might seem isolated but could be part of a larger feature or fix.
| Category | Rule | Exception |
|---|---|---|
| Bugfix vs Feature | Bugfixes generally take precedence | When features include the fix |
| Recent vs Old | More recent changes are often more relevant | When older changes are security patches |
| Test Updates | Changes with test updates are likely more complete | - |
| Formatting vs Logic | Logic changes take precedence over formatting | - |
Problem: You might lose important changes or introduce regressions. Solution: Always analyze both sides using git blame and commit history.
Problem: The PR description often explains the why behind changes. Solution: Always fetch and read the PR information before resolving.
Problem: Merged code might be syntactically incorrect or introduce logical errors. Solution: Always check for syntax errors and review the final diff.
Problem: Unescaped conflict markers (<<<<<<, =======, >>>>>>) will be interpreted as diff syntax.
Solution: Always escape with backslash (\) when they appear in content.
When resolving conflicts with apply_diff, use this pattern:
<<<<<<< SEARCH
:start_line:45
-------
\<<<<<<< HEAD
function oldImplementation() {
return "old";
}
\=======
function newImplementation() {
return "new";
}
\>>>>>>> feature-branch
=======
function mergedImplementation() {
// Combining both approaches
return "merged";
}
>>>>>>> REPLACE
When reporting resolution progress:
Conflict in [file]:
- HEAD: [brief description of changes]
- Incoming: [brief description of changes]
- Resolution: [what was decided and why]
Successfully resolved merge conflicts for PR #[number] "[title]".
Resolution Summary:
- [file1]: [brief description of resolution]
- [file2]: [brief description of resolution]
[Key decision explanation if applicable]
All conflicts have been resolved and files have been staged for commit.