git-prune-branches

Review and delete stale branches using an interactive prompt

Addresses common use cases, such as:

• Remove tracking branches no longer on remote
• How to prune local tracking branches that do not exist on remote anymore?

What does it do?

This command will automatically fetch and prune from your remote, then display an interactive selection of branches to delete organized into three groups:

1. Safe to delete (pre-selected) - Merged branches that were deleted from remote, or local merged branches that were never pushed
2. Requires force delete (not pre-selected) - Unmerged branches with commits that need --force to delete
3. Info only - Renamed branches that still exist on remote (shown for context, cannot be deleted)

After selecting branches, you'll see a preview of the exact git commands that will be executed before confirming the deletion.

The tool automatically fetches and prunes from your remote before showing branches, ensuring you always have up-to-date information. A working network connection to your remote is required. If no connection can be established, cached local information will be used instead.

Installation

npm install -g git-prune-branches

Recommended: install the package globally with -g flag so that you can use it directly as a sub command of git, like this:

git prune-branches

Usage

It's possible to use the package via npx without installing:

npx git-prune-branches

When installed globally with npm install -g git-prune-branches, you can use this git alias:

git prune-branches

Custom remote

If you have configured remote alias to something different than 'origin', you can use --remote or -r flag to specify the name of the remote. For example, to specify remote to be upstream, you can use:

git prune-branches --remote upstream

Custom protected branches

If you want to completely avoid deleting certain branches, you can define the branch names using the --protected flag. For example, to skip the develop and release branches, you can use:

git prune-branches --protected develop,release

If --protected is not specified, git-prune-branches will assume that branches named main, master, develop, and development should be protected.

Version

To print the version:

git prune-branches --version

Troubleshooting

If you encounter error ERR_CHILD_PROCESS_STDIO_MAXBUFFER it is possible that your repository contains too many branches (more than 3382—see discussion).

You can fix this by specifying NODE_MAX_BUFFER environment variable. For example:

NODE_MAX_BUFFER=1048576 git prune-branches

Development

Note that pnpm is recommended for development since some scripts us pnpx internally.

Running

Run the source code using tsx, e.g. to test it on another local repo

pnpx tsx ~/code/git-prune-branches/src/index.ts

You can also run the app against a fake git repo in a temporary folder

pnpm demo

Testing

This project uses Vitest for testing. The tests create a temporary git repository and verify the behavior of the tool in different scenarios.

pnpm test # watch mode
pnpm test:once # run all tests once

Building

Build the TypeScript source:

pnpm build

Breaking changes

Version 2.0.0

• Removed flags: --dry-run, --prune-all, --force, and --yes
  • git-prune-branches is meant to be a visual, interactive app. If you're looking for that kind of automation, consider another package such as git-removed-branches

Credit

Forked from git-removed-branches by Maks Nemisj @nemisj