GitHub Merge Assistant

Interactive CLI tool for creating GitHub pull requests with a delightful terminal UI.

Prerequisites

Before using ghmerge, you need to have the following tools installed:

1. gum - Provides the interactive prompts
``bash
# macOS
brew install gum

# Linux
# See https://github.com/charmbracelet/gum#installation
`

2. gh - GitHub CLI for creating PRs
`bash
# macOS
brew install gh

# Linux/Windows
# See https://cli.github.com/
`

3. Authenticate with GitHub
`bash
gh auth login
`

Installation

$3

`bash
npm install -g ghmerge
`

$3

`bash
npm install ghmerge
`

Then use with npx:
`bash
npx ghmerge
`

Usage

$3

Navigate to your git repository and run:

`bash
ghmerge
`

The tool will prompt you for:
1. PR title (defaults to last commit message)
2. PR description (optional, multiline with Ctrl+D to finish)
3. Destination branch (defaults to "develop")
4. Create as draft? (Yes/No)
5. Labels (comma-separated, optional)
6. Reviewers (comma-separated, optional)
7. Assignees (comma-separated, optional)

Then it will:
- Display your current branch as the source
- Push your branch to origin if not already pushed
- Create the pull request with all the options you selected
- Display the PR URL

$3

`bash
ghmerge [OPTIONS]

OPTIONS:
-h, --help Show help message
-t, --title PR title (default: last commit message)
-d, --description PR description (default: empty)
-b, --base Destination/base branch (default: develop)
-s, --source Source branch (default: current branch)

--draft Create PR as draft
-l, --label Add label (can be used multiple times)
-r, --reviewer Request reviewer (can be used multiple times)
-a, --assignee Assign PR to user (can be used multiple times)

--dry-run Show what would happen without creating PR
-v, --verbose Show verbose output for debugging
-w, --web Open PR in browser after creation
`

$3

Interactive mode (default):
`bash
$ cd my-project
$ git checkout -b feature/new-feature
$ git commit -m "Add amazing feature"
$ ghmerge

📝 Create Pull Request

Source branch: feature/new-feature

Enter PR title (pre-filled with "Add amazing feature")

Enter description (optional)

Enter destination branch (defaults to "develop")

Pushing branch 'feature/new-feature' to origin...

Creating pull request...

✅ Pull request created successfully!
🔗 https://github.com/user/repo/pull/123
`

Non-interactive mode with all flags:
`bash
$ ghmerge -t "Add new feature" -d "This adds X functionality" -b develop

Pushing branch 'feature/new-feature' to origin...

Creating pull request...

✅ Pull request created successfully!
🔗 https://github.com/user/repo/pull/124
`

Mixed mode (some flags, some prompts):
`bash
$ ghmerge -t "Fix critical bug" -b main


Will only prompt for description

$ ghmerge -d "Detailed description here"


Will prompt for title and base branch


`

Create draft PR with labels:
`bash
$ ghmerge --draft -l bug -l urgent -t "Fix critical issue"

Creating pull request...

✅ Pull request created successfully!
📝 Created as draft
🔗 https://github.com/user/repo/pull/125
`

Add reviewers and assignees:
`bash
$ ghmerge -t "New feature" -r alice -r bob -a charlie

Requests review from alice and bob, assigns to charlie


`

Dry run to preview:
`bash
$ ghmerge --dry-run -t "Test PR" -b main

🔍 Dry run mode - no changes will be made

Would create PR with the following details:
Title: Test PR
Description: (empty)
Source: feature/test
Base: main

Would push branch 'feature/test' to origin

No PR created (dry run mode)
`

Open in browser after creation:
`bash
$ ghmerge -t "Review this" --web


Opens the PR in your default browser


`

Verbose mode for debugging:
`bash
$ ghmerge --verbose -t "Debug this"
[verbose] Starting ghmerge...
[verbose] Arguments: {...}
[verbose] Checking GitHub authentication...
[verbose] GitHub authentication verified
...
`

Show help:
`bash
$ ghmerge --help
`

How It Works

1. Smart Defaults: Automatically uses your last commit message as the PR title
2. Branch Detection: Identifies your current branch as the source
3. Auto-Push: Pushes your branch to origin if it doesn't exist remotely
4. PR Creation: Uses gh pr create to create the pull request
5. Success Feedback: Shows you the PR URL immediately

Configuration

The tool uses sensible defaults:
- Default destination branch: develop
- Default title: Last commit message
- Default description: Empty

You can override these during the interactive prompts.

Advanced Usage

$3


Create work-in-progress PRs that can't be merged until marked as ready:
`bash
ghmerge --draft -t "WIP: New feature"
`

$3

Add labels to categorize your PR (labels must exist in your repository):
`bash
ghmerge -l bug -l high-priority -l backend
`

$3

Automatically request reviews and assign the PR:
`bash

Request reviews from multiple people

ghmerge -r alice -r bob -r team/frontend

Assign to someone

ghmerge -a charlie

Combine them

ghmerge -t "Review needed" -r alice -r bob -a charlie
`

$3

Preview what would happen without actually creating the PR:
`bash
ghmerge --dry-run -t "Test" -b main --draft -l bug
`

$3

Debug issues by seeing detailed logging:
`bash
ghmerge --verbose
`

$3

Automatically open the PR in your browser after creation:
`bash
ghmerge --web
`

Troubleshooting

$3

Install gum following the instructions at https://github.com/charmbracelet/gum

$3

Install the GitHub CLI from https://cli.github.com/

$3

Run gh auth login to authenticate with GitHub.

$3

Make sure you're running ghmerge from within a git repository.

$3

You might be in a detached HEAD state. Checkout a branch first.

$3

If something isn't working as expected, run with --verbose to see detailed logs:
`bash
ghmerge --verbose
`

Development

`bash


Clone the repository

git clone
cd ghmerge

Link locally for testing

npm link

Now you can run ghmerge from anywhere

ghmerge

Unlink when done

npm unlink -g ghmerge
``

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.