kwgit

A command-line utility to help with cleaning up git branches. This tool provides a safe and efficient way to manage your git branches, helping you keep your repository clean and organized.

Features

• Clean Command: Remove local and remote branches that match specific patterns

  • Filter branches using regex patterns
  • Option to only delete merged branches
  • Dry run mode for previewing changes
  • Interactive confirmation prompts
  • Support for remote branch cleanup

• Stale Command: Find and remove stale branches

  • Configurable time thresholds for stale branches
  • Interactive review process
  • Dry run mode for safety
  • Exclude specific branches (e.g., main)
  • Support for remote branch cleanup with confirmation

Installation

npm install -g kwgit

Requirements

• Node.js >= 20.0.0
• Git

Usage

Clean Command

# Clean all merged branches (dry run by default)
kwgit clean

# Clean branches matching a pattern
kwgit clean "feature/*"

# Clean and delete remote branches
kwgit clean --remote

# Force delete without prompts
kwgit clean --force

# Clean branches merged into a specific base branch
kwgit clean --base develop

Stale Command

# Find branches older than 30 days
kwgit stale

# Customize the stale threshold
kwgit stale --days 60

# Set maximum age for branches
kwgit stale --max-days 180

# Preview changes without deleting
kwgit stale --dry-run

# Remove stale branches including remote (with confirmation)
kwgit stale --remote

Using with NPX

You can run kwgit directly without installation using:

npx kwgit clean "feature/*"
npx kwgit stale --remote

This is useful for one-off usage or running in CI/CD pipelines.

Options

Clean Command Options

• [pattern]: Regex pattern to match branch names (default: '.*')
• --dry-run, -d: Preview branches that would be deleted (default: true)
• --merged, -m: Only delete branches merged into the base branch (default: true)
• --force, -f: Force deletion without prompt (default: false)
• --base, -b: Base branch to check merged status against (default: 'main')
• --remote, -r: Also delete matching remote tracking branches (default: false)

Stale Command Options

• --days, -d: Minimum days since last commit to consider a branch stale (default: 30)
• --max-days, -m: Maximum days since last commit (default: 365)
• --base, -b: Branch to exclude from evaluation (default: 'main')
• --dry-run: Preview stale branches without deleting (default: false)
• --force, -f: Delete matching branches without prompt (default: false)
• --remote, -r: Also delete matching remote tracking branches (with prompt unless --force)

Environment Variables

KWGIT_PROTECTED_BRANCHES

Use this environment variable to define a comma-separated list of branch names that should never be deleted, even if they match your cleanup criteria.

If not specified, the default protected branches are:

main, master

You can set this in your shell configuration file (e.g., .zprofile, .bashrc, or .zshrc):

export KWGIT_PROTECTED_BRANCHES="main,master,develop,staging"

When running kwgit, these branches will always be excluded from deletion. You will see a warning message indicating they were skipped.

License

MIT

Author

Kevin Warnock