github-merge-stack

name	github-merge-stack
description	Merge stacked feature branches from Ralph into main, preserving full feature history. Handles PR base updates, sequential squash merges, and branch cleanup. Use when this capability is needed.
metadata	{"author":"edfenton"}

Purpose

After Ralph completes with RALPH_CREATE_PR=true, merge all stacked PRs into main while preserving visibility of when and why each feature was implemented.

Arguments

• --dry-run — Show what would be merged without making changes
• --no-cleanup — Skip local branch cleanup after merging

Prerequisites

• gh CLI authenticated (gh auth status)
• On a branch in the repo with open PRs
• PRs created by Ralph with stacked branches

Template

The merge logic is implemented in templates/merge-stack.sh. This script can be:

1. Run directly from the skill's templates folder
2. Copied to a project's scripts/ directory for convenience

Workflow

1. Copy Script to Project (Optional)

cp /path/to/skills/shared/github-merge-stack/templates/github-merge-stack.sh scripts/
chmod +x scripts/github-merge-stack.sh

2. Run the Script

# Preview what will happen
./scripts/github-merge-stack.sh --dry-run

# Execute merges
./scripts/github-merge-stack.sh

# Execute without local cleanup
./scripts/github-merge-stack.sh --no-cleanup

What the Script Does

1. Checks prerequisites — Verifies gh CLI is authenticated
2. Lists open PRs — Sorted by number (oldest first = merge order)
3. Dry run (if --dry-run) — Shows plan without executing
4. Merges PRs sequentially — For each PR:
   • Updates base to main (previous base may be deleted)
   • Squash merges with gh pr merge --squash --delete-branch
5. Syncs local — Pulls main, prunes remote refs
6. Cleans up (unless --no-cleanup) — Deletes local feat/* branches
7. Reports results — Shows merged commits and any remaining branches

Understanding the Stack

Ralph creates stacked branches where each PR's base is the previous feature branch:

main
 └── feat/story-001  →  PR #1 (base: main)
      └── feat/story-002  →  PR #2 (base: feat/story-001)
           └── feat/story-003  →  PR #3 (base: feat/story-002)

Why Squash Merge

• One commit per feature — Clean main history
• Full context preserved — Ralph's detailed commit messages (description, acceptance criteria, files) become the squash commit body
• Traceability — git blame traces to originating story, git log --grep finds features

Output

The script reports:

• Number of PRs merged
• Commits now in main (with hashes and titles)
• Branches cleaned up
• Any failed PRs (conflicts to resolve manually)
• Commands for viewing history

Viewing History Later

# See all features
git log --oneline

# Full details of a feature  
git show <commit-hash>

# Find specific story
git log --grep="story-003"

# Why was this line changed?
git blame path/to/file.ts

Error Handling

• PR has conflicts: Skipped, reported at end for manual resolution
• gh not authenticated: Exits with instructions to run gh auth login
• No open PRs: Reports nothing to merge
• Branch delete fails: Continues, reports at end

Reference

See reference/github-merge-stack-reference.md for troubleshooting and manual procedures.

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.