CLI Merge Branch¶

The cli-merge-branch command automates GitHub merge workflows with pre-flight checks and test validation. It supports two modes:

Feature Mode: Squash merge feature branches to develop
Release Mode: Merge commit from develop to main (auto-detected)

Installation¶

The CLI tool is available after activating the Poetry shell in the backend directory:

cd backend
poetry shell

Once in the Poetry shell, the cli-merge-branch command is available.

Usage¶

cli-merge-branch [OPTIONS]

Options¶

Option	Default	Description
`--base`	`develop`	Target branch for merge (ignored in release mode)
`--skip-tests`	`false`	Skip running frontend and backend tests
`--no-confirm`	`false`	Skip confirmation prompt before merge
`--dry-run`	`false`	Show what would happen without executing

Examples¶

# Standard merge to develop with all checks (squash merge)
cli-merge-branch

# Merge to main instead of develop
cli-merge-branch --base main

# Skip tests (use with caution)
cli-merge-branch --skip-tests

# Preview what would happen
cli-merge-branch --dry-run

# Automated merge without confirmation
cli-merge-branch --no-confirm

Release Mode Examples¶

# Checkout develop branch
git checkout develop

# Preview release merge (develop → main)
cli-merge-branch --dry-run

# Execute release merge
cli-merge-branch

Merge Modes¶

Behavior Matrix¶

Current Branch	Target	Merge Type	PR Handling
Feature branch	`develop`	Squash merge	Must exist
`develop`	`main`	Merge commit	Auto-created if missing

Feature Mode (Default)¶

When running from a feature branch:

Target: develop (or specified via --base)
Merge Type: Squash merge (combines all commits into one)
PR: Must already exist

Release Mode (Auto-detected)¶

When running from the develop branch:

Target: main (ignores --base option)
Merge Type: Merge commit (preserves commit history)
PR: Auto-created if it doesn't exist

This mode is designed for releasing develop to main while preserving the full commit history.

Workflow Steps¶

The command executes 6 automated steps:

Step 1: Pre-flight Checks¶

Verifies working directory is clean (no uncommitted changes)
Validates current branch is not the target branch or main/master
Fetches latest changes from origin
Pushes any unpushed local commits
Checks if branch needs rebasing on the target branch

Step 2: PR Verification/Creation¶

Feature Mode:

Verifies a Pull Request exists for the current branch
Displays PR number, title, and URL

Release Mode:

Checks if a PR exists for develop → main
Auto-creates the PR if it doesn't exist
Displays PR number, title, and URL

Step 3: Mergeability Check¶

Checks GitHub PR mergeability status
Handles UNKNOWN status with retries (GitHub may take time to compute)
Detects merge conflicts, blocked status, or behind-base-branch issues

Step 4: Test Execution¶

Runs just test in the frontend/ directory
Runs just test in the backend/ directory
Both must pass for merge to proceed

Step 5: Cleanup¶

Kills any dangling vitest processes (from frontend tests)

Step 6: Merge Execution¶

Feature Mode:

Prompts: "Proceed with squash merge to develop?"
Executes gh pr merge --squash

Release Mode:

Prompts: "Proceed with merge commit to main?"
Executes gh pr merge --merge (preserves history)

Exit Codes¶

Code	Meaning
`0`	Success
`1`	Error (failed checks, tests, or merge)
`2`	Cancelled by user

Prerequisites¶

GitHub CLI (gh): Must be installed and authenticated
Poetry environment: Run poetry shell in the backend directory
Clean working directory: Commit or stash changes before running
Existing PR: Required in feature mode only (release mode auto-creates)

Development Workflow Integration¶

This tool integrates with the Development Workflow:

flowchart LR subgraph Feature Development A[git-add-worktree] --> B[Create PR] B --> C[cli-merge-branch<br/>squash to develop] end subgraph Release C --> D[checkout develop] D --> E[cli-merge-branch<br/>merge to main] end

Why Use This Tool?¶

Consistency: Ensures all merges follow the same process
Safety: Runs tests before merging to prevent breaking changes
Automation: Handles pushing, PR creation (release mode), and cleanup
Feedback: Clear step-by-step progress with colored output
History Preservation: Release mode uses merge commits to preserve full history in main

Troubleshooting¶

"Working directory has uncommitted changes"¶

Commit or stash your changes:

git stash
cli-merge-branch
git stash pop

"Branch is X commit(s) behind origin/develop"¶

Rebase your branch on the base branch:

git fetch origin
git rebase origin/develop
git push --force-with-lease

"No PR found for current branch"¶

This error only occurs in feature mode. Create a PR first:

gh pr create --base develop

Note

In release mode (when on develop branch), the PR is automatically created.

"PR has merge conflicts"¶

Resolve conflicts locally:

git fetch origin
git rebase origin/develop
# Resolve conflicts
git add .
git rebase --continue
git push --force-with-lease

"PR is blocked (check required status checks)"¶

Wait for CI checks to complete or investigate failing checks in the GitHub PR page.