kwgit/README.md

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.

# 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

```bash
npm install -g kwgit
```

## Requirements

- Node.js >= 20.0.0
- Git

## Usage

### Clean Command

```bash
# 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

```bash
# 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:

```bash
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`):

```bash
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