git-pr-helper

# Git PR Helper Expert at managing git workflows for pull requests, merges, and branch management with a focus on safety, quality, and best practices. ## Core Mission Assist with pull request creation, branch management, merge coordination, and conflict resolution while ensuring code quality and preventing data loss. ## When to Use This Skill Use this skill when: - Creating a pull request from a feature branch - Merging branches (feature → main/master) - Resolving merge conflicts - Cleaning up old session or feature branches - Generating PR descriptions from commits - Checking if work is ready to merge - Recovering from git mistakes **Do NOT use this skill for:** - Preventing file deletion (use git hooks + CLAUDE.md instead) - Creating session branches at workflow start (use CLAUDE.md guidance) - Enforcing branch policies (use git hooks instead) ## Skill Capabilities ### 1. Pull Request Creation **Purpose:** Create high-quality pull requests with comprehensive descriptions #### Create PR with Generated Description To create a PR: 1. **Verify we're on a feature branch:** ```bash CURRENT_BRANCH=$(git branch --show-current) if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then echo "❌ ERROR: Cannot create PR from main/master branch" exit 1 fi echo "✓ Current branch: $CURRENT_BRANCH" ``` 2. **Check git status is clean:** ```bash if [ -n "$(git status --porcelain)" ]; then echo "⚠️ WARNING: Uncommitted changes detected" git status --short echo "" echo "Commit these changes before creating PR? (y/n)" # Ask user via AskUserQuestion tool else echo "✓ Working tree clean" fi ``` 3. **Determine base branch:** ```bash # Try to detect default branch BASE_BRANCH=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | cut -d' ' -f5) # Fallback to checking what exists if [ -z "$BASE_BRANCH" ]; then if git show-ref --verify --quiet refs/heads/main; then BASE_BRANCH="main" elif git show-ref --verify --quiet refs/heads/master; then BASE_BRANCH="master" else echo "⚠️ Cannot detect base branch. Please specify manually." fi fi echo "Base branch: $BASE_BRANCH" ``` 4. **Get all commits on this branch:** ```bash # Get commit history since branch diverged from base git log $BASE_BRANCH..HEAD --oneline # Get detailed commit info git log $BASE_BRANCH..HEAD --format="%h %s%n%b" --reverse ``` 5. **Get diff summary:** ```bash # File changes summary git diff $BASE_BRANCH...HEAD --stat # List changed files git diff $BASE_BRANCH...HEAD --name-only ``` 6. **Generate PR description:** Analyze commits and changes to create: ```markdown ## Summary - [Brief bullet points of main changes] - [Focus on WHY, not WHAT] - [User-facing impact] ## Changes Made - [Detailed technical changes] - [Components affected] - [API changes if applicable] ## Testing - [ ] Unit tests added/updated - [ ] Manual testing completed - [ ] Edge cases considered - [ ] Documentation updated ## Related Issues Closes #[issue-number] (if applicable) ## Notes for Reviewers [Any context reviewers should know] [Areas needing special attention] ``` 7. **Check if remote tracking branch exists:** ```bash if git rev-parse --verify --quiet origin/$CURRENT_BRANCH >/dev/null 2>&1; then echo "✓ Remote branch exists" else echo "⚠️ Remote branch does not exist. Need to push first." echo "Push now? (y/n)" # If yes: git push -u origin $CURRENT_BRANCH fi ``` 8. **Create PR using GitHub CLI:** ```bash gh pr create \ --title "[Generated title from commits]" \ --body "$(cat <<'EOF' [Generated PR description] EOF )" \ --base "$BASE_BRANCH" \ --head "$CURRENT_BRANCH" ``` 9. **Update CLAUDE-activeContext.md (if exists):** ```bash if [ -f CLAUDE-activeContext.md ]; then # Add PR link to active context PR_URL=$(gh pr view --json url -q .url) echo "PR created: $PR_URL" >> CLAUDE-activeContext.md fi ``` #### Generate PR Description Only To generate a PR description without creating the PR: 1. Follow steps 1-6 above 2. Output the generated description for user review 3. Ask if user wants to create PR with this description ### 2. Merge Coordination **Purpose:** Safely merge branches with conflict detection and resolution guidance #### Check Merge Readiness To check if branch is ready to merge: ```bash echo "=== MERGE READINESS CHECK ===" echo "" # 1. Check current branch CURRENT_BRANCH=$(git branch --show-current) BASE_BRANCH=${BASE_BRANCH:-main} if [ "$CURRENT_BRANCH" = "$BASE_BRANCH" ]; then echo "❌ ERROR: Already on base branch $BASE_BRANCH" exit 1 fi echo "✓ Feature branch: $CURRENT_BRANCH" echo "" # 2. Check for uncommitted changes if [ -n "$(git status --porcelain)" ]; then echo "❌ Uncommitted changes detected:" git status --short echo "" else echo "✓ Working tree clean" echo "" fi # 3. Fetch latest from remote echo "Fetching latest from remote..." git fetch origin $BASE_BRANCH echo "" # 4. Check if base branch has new commits BEHIND=$(git rev-list --count HEAD..origin/$BASE_BRANCH) if [ "$BEHIND" -gt 0 ]; then echo "⚠️ Base branch has $BEHIND new commits" echo "Consider rebasing: git rebase origin/$BASE_BRANCH" else echo "✓ Up to date with base branch" fi echo "" # 5. Check for conflicts echo "Checking for potential conflicts..." git merge-tree $(git merge-base HEAD origin/$BASE_BRANCH) HEAD origin/$BASE_BRANCH > /tmp/merge-preview.txt if grep -q "changed in both" /tmp/merge-preview.txt; then echo "⚠️ CONFLICTS DETECTED:" grep -A 3 "changed in both" /tmp/merge-preview.txt echo "" else echo "✓ No conflicts detected" echo "" fi # 6. Run tests (if test command exists) if [ -f package.json ] && grep -q "\"test\"" package.json; then echo "Running tests..." npm test elif [ -f pytest.ini ] || [ -d tests ]; then echo "Running tests..." pytest elif [ -f Cargo.toml ]; then echo "Running tests..." cargo test else echo "ℹ️ No test command found (skipped)" fi echo "" # 7. Check CI status (if using GitHub) if command -v gh &> /dev/null; then echo "Checking CI status..." gh pr checks 2>/dev/null || echo "ℹ️ No PR found or CI configured" fi echo "" echo "=== READINESS CHECK COMPLETE ===" ``` #### Merge Branch Safely To merge a feature branch: 1. **Run merge readiness check** (above) 2. **Ask user for merge strategy:** - Regular merge (preserves all commits) - Squash merge (single commit) - Rebase and merge (linear history) 3. **For regular merge:** ```bash git checkout $BASE_BRANCH git merge --no-ff $FEATURE_BRANCH -m "Merge branch '$FEATURE_BRANCH'" ``` 4. **For squash merge:** ```bash git checkout $BASE_BRANCH git merge --squash $FEATURE_BRANCH # Generate commit message from all commits git log $BASE_BRANCH..$FEATURE_BRANCH --format="%s" > /tmp/commit-msg.txt git commit -m "$(cat <<'EOF' [Squashed commit title] Changes included: $(cat /tmp/commit-msg.txt) EOF )" ``` 5. **For rebase and merge:** ```bash git checkout $FEATURE_BRANCH git rebase $BASE_BRANCH git checkout $BASE_BRANCH git merge --ff-only $FEATURE_BRANCH ``` 6. **Push to remote:** ```bash git push origin $BASE_BRANCH ``` 7. **Clean up feature branch (optional):** ```bash # Delete local branch git branch -d $FEATURE_BRANCH # Delete remote branch git push origin --delete $FEATURE_BRANCH ``` ### 3. Conflict Resolution **Purpose:** Guide through merge conflict resolution #### Detect and Analyze Conflicts When conflicts occur: 1. **Show conflicted files:** ```bash git status | grep "both modified" ``` 2. **For each conflicted file, show conflict markers:** ```bash grep -n "<<<<<<< HEAD" $CONFLICTED_FILE ``` 3. **Explain the conflict:** - `<<<<<<< HEAD` = Your current branch changes - `=======` = Separator - `>>>>>>> branch-name` = Incoming branch changes 4. **Provide resolution strategies:** - Accept current changes (ours): `git checkout --ours $FILE` - Accept incoming changes (theirs): `git checkout --theirs $FILE` - Manually resolve: Edit file to keep both/choose wisely 5. **After resolution:** ```bash git add $RESOLVED_FILE git status # Verify all conflicts resolved git merge --continue # or git rebase --continue ``` #### Abort Problematic Merge If merge goes wrong: ```bash # Abort merge git merge --abort # Abort rebase git rebase --abort # Return to clean state git status ``` ### 4. Branch Cleanup **Purpose:** Safely remove old session/feature branches #### List Branches for Cleanup To identify branches that can be cleaned up: ```bash echo "=== BRANCH CLEANUP ANALYSIS ===" echo "" # Get current branch and base branch CURRENT_BRANCH=$(git branch --show-current) BASE_BRANCH=${BASE_BRANCH:-main} # List all local branches echo "Local branches:" git branch -vv echo "" # List merged branches (safe to delete) echo "Merged branches (safe to delete):" git branch --merged $BASE_BRANCH | grep -v "^\*" | grep -v "$BASE_BRANCH" echo "" # List unmerged branches (check before deleting) echo "Unmerged branches (verify before deleting):" git branch --no-merged $BASE_BRANCH | grep -v "^\*" echo "" # Show last commit date for each branch echo "Branch activity (last commit date):" for branch in $(git branch | sed 's/^\*/ /'); do printf "%-30s %s\n" "$branch" "$(git log -1 --format=%cd --date=relative $branch)" done ``` #### Clean Up Merged Branches To delete merged branches: ```bash # Get list of merged branches (excluding current and base) MERGED_BRANCHES=$(git branch --merged $BASE_BRANCH | grep -v "^\*" | grep -v "$BASE_BRANCH" | grep -v "main" | grep -v "master") if [ -z "$MERGED_BRANCHES" ]; then echo "No merged branches to clean up" else echo "The following merged branches will be deleted:" echo "$MERGED_BRANCHES" echo "" echo "Proceed? (requires user confirmation)" # If confirmed: echo "$MERGED_BRANCHES" | xargs git branch -d echo "✓ Local merged branches deleted" echo "" echo "Delete remote branches too? (requires user confirmation)" # If confirmed: echo "$MERGED_BRANCHES" | xargs -I {} git push origin --delete {} fi ``` #### Clean Up Session Branches To clean up old session branches specifically: ```bash # Find session branches (pattern: session/*) SESSION_BRANCHES=$(git branch | grep "session/" | sed 's/^\*/ /' | xargs) if [ -z "$SESSION_BRANCHES" ]; then echo "No session branches found" else echo "Session branches:" for branch in $SESSION_BRANCHES; do MERGED=$(git branch --merged $BASE_BRANCH | grep -q "$branch" && echo "✓ merged" || echo "✗ unmerged") LAST_COMMIT=$(git log -1 --format="%cd" --date=relative $branch) printf "%-40s %-12s %s\n" "$branch" "$MERGED" "$LAST_COMMIT" done echo "" # Ask which to delete echo "Delete merged session branches? (y/n)" # If yes, delete only merged ones fi ``` ### 5. PR Review Assistance **Purpose:** Help review PRs and provide feedback #### Analyze PR Changes To review a PR: ```bash # Get PR number from user or current branch PR_NUMBER=${1:-$(gh pr view --json number -q .number 2>/dev/null)} if [ -z "$PR_NUMBER" ]; then echo "No PR found. Specify PR number or create a PR first." exit 1 fi # Get PR details gh pr view $PR_NUMBER # Get diff gh pr diff $PR_NUMBER # Get file changes summary gh pr diff $PR_NUMBER --name-only # Check CI status gh pr checks $PR_NUMBER # Get review comments