gh poi

A GitHub CLI extension to safely clean up local branches you no longer need.

Motivation

Daily development makes it difficult to know which branch is active when there are many unnecessary branches left locally, which causes a small amount of stress. If you squash merge a pull request, there is no history of the merge to the default branch, so you have to force delete the branch to clean it up, and you have to be careful not to accidentally delete the active branch.

We have made it possible to automatically determine which branches have been merged and clean up the local environment without worry.

Installation

gh extension install seachicken/gh-poi

Usage

• gh poi Delete the merged local branches
• gh poi --state (closed|merged) Specify the PR state to delete (default merged)
• gh poi --scan (quick|deep) Specify the scan mode (default quick)
  • quick: Fast; checks "origin" and "upstream" remotes. Identifies PRs using only the latest commit on each branch
  • deep: Comprehensive; scans all registered remotes. Performs a deeper history check to link branches to PRs, ensuring no potential matches are missed across multiple forks
  • Note: poi ensures safe deletion in both modes
• gh poi --dry-run Show branches to delete without actually deleting it
• gh poi --debug Enable debug logs
• gh poi lock <branchname>... Lock branches to prevent them from being deleted
• gh poi unlock <branchname>... Unlock branches to allow them to be deleted

FAQ

How does gh poi compare with other branch cleanup tools?

gh poi is built for GitHub pull-request workflows. Its GitHub integration considers each PR's state and the commits associated with a local branch, allowing it to clean up squash-merged PRs safely.

Scenario	gh poi	git branch --delete-merged
Merged into the upstream branch, with an associated GitHub PR	✅	✅
Merged into the upstream branch, without an associated GitHub PR	❌	✅
Squash-merged with an associated GitHub PR	✅	❌
Squash-merged locally, without an associated GitHub PR	❌	❌
PR closed without merging	✅ --state closed	❌
Merged branch in a clean, inactive linked worktree	✅	❌
Keep a merged branch	✅ gh poi lock <name>	✅ branch.<name>.deleteMerged=false

Why the name "poi"?

"poi" means "feel free to throw it away" in Japanese.
If you prefer an alias, you can change it with gh alias set. (e.g. gh alias set clean-branches poi)