auldsyababua/merge-conflict-resolver

Merge Conflict Resolver Skill

Overview

A comprehensive skill for analyzing Git branch divergence, detecting potential merge conflicts before they occur, and guiding users through systematic conflict resolution. This skill provides both automated analysis and manual resolution workflows.

Features

1. Intelligent Auto-Detection

• Detects current branch automatically if not specified
• Auto-discovers repository root using git rev-parse --show-toplevel
• Defaults to origin/main as target branch (configurable)
• Works in any Git repository without hardcoded paths

2. 8-Step Analysis Workflow

1. Branch Verification - Validates current branch state
2. Status Display - Shows recent commits and current HEAD
3. Fetch Latest - Updates remote branch information
4. Commit Comparison - Analyzes branch divergence (merge-base analysis)
5. Change Analysis - Shows commits unique to each branch
6. File Changes - Lists modified files in both branches
7. Conflict Detection - Identifies files changed in both branches (potential conflicts)
8. Merge Attempt - Attempts automatic merge with detailed reporting

3. Color-Coded Output

• RED - Errors and conflict detection
• GREEN - Success messages and confirmations
• YELLOW - Warnings and important information
• BLUE - Section headers and step markers

4. Multiple Resolution Strategies

• Automated - resolve-merge-conflicts.sh (orchestrator)
• Detailed Analysis - analyze-and-merge.sh (8-step workflow with guidance)
• Simple Merge - simple-merge.sh (basic merge helper)
• Status Check - check-merge-status.sh (non-destructive analysis)

Usage

Quick Start (Recommended)

# Auto-detect current branch, merge from origin/main
cd /path/to/your/repo
/path/to/skills/merge-conflict-resolver/scripts/resolve-merge-conflicts.sh

# Specify branches explicitly
./scripts/resolve-merge-conflicts.sh feature/my-branch origin/main

# Or just specify source branch
./scripts/resolve-merge-conflicts.sh feature/my-branch

Detailed Analysis

# Run comprehensive 8-step analysis before merging
./scripts/analyze-and-merge.sh feature/my-branch origin/main

# Auto-detect branches
./scripts/analyze-and-merge.sh

Status Check Only

# Check current state without making any changes
./scripts/check-merge-status.sh

Simple Merge Helper

# Basic merge workflow (less verbose)
./scripts/simple-merge.sh feature/my-branch origin/main

When to Use This Skill

Perfect For:

• ✅ Resolving merge conflicts in feature branches
• ✅ Pre-merge analysis to detect potential conflicts
• ✅ Understanding branch divergence before creating PRs
• ✅ Teaching merge conflict resolution workflows
• ✅ Automated merge workflows in CI/CD pipelines
• ✅ Multi-developer teams with frequent branch conflicts

Not Suitable For:

• ❌ Automated conflict resolution (requires human judgment)
• ❌ Rebasing workflows (use git rebase instead)
• ❌ Interactive conflict resolution (use git mergetool)
• ❌ Cherry-picking specific commits (use git cherry-pick)

Output Examples

Success Case (No Conflicts)

==================================================================
✓ SUCCESS: Merge completed without conflicts!
==================================================================

New HEAD:
abc1234 Merge origin/main into feature/my-branch
def5678 Latest feature commit
...

Next steps:
1. Review the merge: git log --oneline -10
2. Push to remote: git push origin feature/my-branch

Conflict Case (Manual Resolution Needed)

=================================================
✗ MERGE CONFLICTS DETECTED
=================================================

Conflicting files:
UU src/main.py
UU config/settings.json

⚠ Files changed in both branches:
src/main.py
config/settings.json

Resolution steps:
1. Review conflicts in the files listed above
2. Edit each file to resolve conflicts (look for <<<<<<< markers)
3. git add <resolved-file>
4. Repeat for all files
5. git merge --continue

Or to abort:
git merge --abort

Pre-Merge Analysis

[Step 7] Checking for potential conflicts...
✓ No overlapping file changes detected
Merge should be clean!

Files changed in our branch:
  src/feature.py
  tests/test_feature.py

Files changed in origin/main:
  src/unrelated.py
  docs/README.md

Configuration

Environment Variables

# Override default target branch
export DEFAULT_TARGET_BRANCH="origin/develop"

# Disable color output (for CI/CD logs)
export NO_COLOR=1

# Auto-abort on conflicts (for automation)
export AUTO_ABORT_ON_CONFLICT=1

Script Parameters

All scripts accept optional parameters:

./scripts/resolve-merge-conflicts.sh [source-branch] [target-branch]

Parameter Defaults:

• source-branch: $(git branch --show-current) (current branch)
• target-branch: origin/main (or $DEFAULT_TARGET_BRANCH)

Error Handling

Common Errors

Not in a Git repository:

ERROR: Not in a Git repository
Run this script from inside a Git repository

Branch doesn't exist:

ERROR: Branch 'feature/nonexistent' not found
Available branches: git branch -a

Already up to date:

✓ Already up to date with origin/main
No merge needed.

Dirty working directory:

ERROR: Working directory has uncommitted changes
Commit or stash changes before merging:
  git stash
  git commit -am "Save work"

Rollback and Recovery

Abort Merge in Progress

# Cancel merge and return to pre-merge state
git merge --abort

Reset to Before Merge

# Reset to previous state (ORIG_HEAD)
git reset --hard ORIG_HEAD

# Or reset to remote branch
git reset --hard origin/feature/my-branch

Preserve Work Before Resetting

# Save current work
git stash

# Reset to clean state
git reset --hard origin/feature/my-branch

# Restore work
git stash pop

Integration Examples

CI/CD Pipeline (GitHub Actions)

name: Check Merge Conflicts

on:
  pull_request:
    branches: [main]

jobs:
  check-merge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for merge-base

      - name: Check for conflicts
        run: |
          ./skills/merge-conflict-resolver/scripts/check-merge-status.sh

      - name: Analyze merge
        run: |
          export NO_COLOR=1  # Disable colors in CI logs
          ./skills/merge-conflict-resolver/scripts/analyze-and-merge.sh
        continue-on-error: true  # Allow conflicts

Pre-Merge Hook

#!/bin/bash
# .git/hooks/pre-merge-commit

# Run conflict analysis before allowing merge
/path/to/skills/merge-conflict-resolver/scripts/check-merge-status.sh

if [ $? -ne 0 ]; then
  echo "Merge conflict detected. Resolve before committing."
  exit 1
fi

Automated Merge Script

#!/bin/bash
# automated-merge.sh

set -euo pipefail

FEATURE_BRANCH="$1"
TARGET_BRANCH="${2:-origin/main}"

# Check for conflicts first
if ! ./skills/merge-conflict-resolver/scripts/analyze-and-merge.sh "$FEATURE_BRANCH" "$TARGET_BRANCH"; then
  echo "Automatic merge failed - manual intervention required"
  exit 1
fi

# Push if successful
git push origin "$FEATURE_BRANCH"

Troubleshooting

Merge Failed with Many Conflicts

Try rebase instead:

git merge --abort
git rebase origin/main

# Resolve conflicts one commit at a time
git add <resolved-file>
git rebase --continue

Lost Changes After Merge

# Check reflog for lost commits
git reflog

# Restore from reflog
git reset --hard HEAD@{N}  # Replace N with appropriate index

Scripts Not Executable

# Make scripts executable
chmod +x skills/merge-conflict-resolver/scripts/*.sh

Best Practices

Before Merging

1. ✅ Always fetch first: git fetch origin
2. ✅ Check branch status: Run check-merge-status.sh
3. ✅ Analyze potential conflicts: Run analyze-and-merge.sh first
4. ✅ Commit or stash changes: Clean working directory before merge
5. ✅ Review recent commits: Understand what you're merging

During Conflict Resolution

1. ✅ Read conflict markers carefully: <<<<<<<, =======, >>>>>>>
2. ✅ Test after each resolution: Don't resolve all at once
3. ✅ Keep both changes when possible: Merge functionality, don't just delete
4. ✅ Preserve security fixes: Don't accidentally revert critical changes
5. ✅ Document complex resolutions: Add comments explaining why

After Merging

1. ✅ Review the merge commit: git show HEAD
2. ✅ Run tests: Ensure nothing broke
3. ✅ Check for unintended changes: git diff HEAD~1
4. ✅ Update documentation: Note conflicts resolved
5. ✅ Push promptly: Don't leave resolved merges unpushed

File Structure

skills/merge-conflict-resolver/
├── SKILL.md                          # This file
├── README.md                         # Usage guide
└── scripts/
    ├── resolve-merge-conflicts.sh    # Main orchestrator
    ├── analyze-and-merge.sh          # Detailed 8-step analysis
    ├── simple-merge.sh               # Basic merge helper
    └── check-merge-status.sh         # Status checker

Contributing

Adding Features

1. Keep auto-detection logic in all scripts
2. Maintain color-coded output conventions
3. Provide clear error messages with actionable steps
4. Test with multiple Git repository types
5. Update both SKILL.md and README.md

Testing

# Test in various scenarios
cd /tmp
git init test-repo
cd test-repo
git remote add origin <test-repo-url>

# Test auto-detection
/path/to/scripts/check-merge-status.sh

# Test with parameters
/path/to/scripts/analyze-and-merge.sh feature/test origin/main

Version History

• v1.0.0 (2025-11-17) - Initial release
  • 8-step analysis workflow
  • Auto-detection of branches and repository
  • Color-coded output
  • Multiple resolution strategies
  • Comprehensive error handling

License

MIT License - Use freely in any Git workflow

Support

For issues or questions:

1. Check this documentation first
2. Review example outputs in README.md
3. Examine script comments for implementation details
4. Test in a safe repository before production use

---

Remember: Merge conflict resolution requires human judgment. These scripts analyze and guide, but you make the final decisions about which changes to keep.