branch-scanner

A CLI utility that lists and cleans non-standard git branches and worktrees across your local repositories.

Table of Contents

• Installation and Usage
  • Options
  • Commands
    • scan
    • clean

Installation and Usage

Run directly with npx — no install needed:

npx branch-scanner

Options

| Option | Alias | What it does | Default | |--------|-------|--------------|---------| | -v | --version | Output the program's version number. | - | | -d | --directory | Specify a directory to target. | Current directory | | -r | --recursive | Recursively scan subdirectories. | false | | -h | --help | Output usage information. | - |

By default, commands operate on the specified directory itself. Use --children to scan its subdirectories instead.

Commands

scan

Lists all non-standard branches and linked worktrees for the target directory.

Worktrees are displayed with a 🌿 icon and their disk path.

# scan the current directory
npx branch-scanner scan

# scan a specific repo
npx branch-scanner -d ~/dev/myrepo scan

# scan all repos under a directory
npx branch-scanner -d ~/dev scan --children

# scan recursively
npx branch-scanner -d ~/dev scan --children -r

| Option | What it does | |--------|--------------| | -c, --children | Scan subdirectories instead of the directory itself. |

clean

Interactive UI to select and delete branches and/or worktrees.

Branches checked out in a worktree are shown only as worktrees (not duplicated).

# interactive clean on a specific repo
npx branch-scanner -d ~/dev/myrepo clean

# remove all worktrees non-interactively
npx branch-scanner -d ~/dev/myrepo clean --worktrees

# interactive clean across all repos in a directory
npx branch-scanner -d ~/dev clean --children

| Option | What it does | |--------|--------------| | -c, --children | Target subdirectories instead of the directory itself. | | --worktrees | Non-interactive: remove all linked worktrees without prompting. | | --debug | Print debug information during execution. |

Note: Removing a worktree deletes its directory and prunes the git metadata. For large repos with node_modules, this can take a moment.