git-branch

# git-branch skill

## When to use

Use this skill when the user needs to:
- Track branch age and staleness across one or more Git repositories
- View open PR/MR status overlaid on branch data
- Delete stale branches safely with a two-step confirmation
- Run scheduled or manual repository scans
- Configure staleness thresholds and API tokens

## Prerequisites

- Node.js 20+
- pnpm
- Git 2.20+ in PATH
- Optional: GitHub personal access token (scope: `read:repo`) for PR status
- Optional: GitLab personal access token (scope: `read_api`) for MR status

## Installation

```
npm install -g git-branch-dashboard
```

Or run from source:

```
git clone https://github.com/your-org/git-branch-dashboard
cd git-branch-dashboard
pnpm install
pnpm build
pnpm link --global
```

## Quick Start

```
# Start the dashboard server (opens http://127.0.0.1:7654)
git-branch-dash start

# Add a local repository
git-branch-dash repo add /path/to/my-repo

# Set GitHub token for PR status
git-branch-dash config set github-token ghp_...

# Trigger a manual scan
git-branch-dash scan
```

## Usage Patterns

### Tracking a monorepo workspace

Add each sub-package as a separate repository path if they are independent Git clones. If they share a single `.git` directory, add the root once.

```
git-branch-dash repo add /workspace/packages/api
git-branch-dash repo add /workspace/packages/web
git-branch-dash repo add /workspace/packages/shared
```

### Pruning stale branches across all repos

The `prune` command deletes local branches classified as stale or very stale. It never touches remote branches.

```
# Dry run first to preview what would be deleted
git-branch-dash prune --dry-run

# Prune a specific repo
git-branch-dash prune --repo my-app

# Prune all repos (prompts for confirmation per repo)
git-branch-dash prune --all
```

### Scanning on a schedule

The dashboard server runs a background scanner on a configurable interval. The default is every 15 minutes. Change it in Settings or via environment variable:

```
GBDASH_SCAN_INTERVAL=5 git-branch-dash start
```

Set to `0` to disable automatic scanning.

### Reading branch data from the API

All branch data is available via the REST API at `http://127.0.0.1:7654/api/`:

```
# All stale branches
curl http://127.0.0.1:7654/api/branches/stale

# Branches for a specific repo
curl http://127.0.0.1:7654/api/repos/{id}/branches
```

## CLI Reference

| Command | Description |
|---|---|
| `git-branch-dash start` | Start the dashboard server |
| `git-branch-dash start --port 8080` | Start on a custom port |
| `git-branch-dash scan` | Scan all configured repositories immediately |
| `git-branch-dash scan --repo <name>` | Scan a single repository |
| `git-branch-dash prune` | Interactive stale branch pruning |
| `git-branch-dash prune --repo <name>` | Prune a specific repository |
| `git-branch-dash prune --dry-run` | Preview branches to be pruned |
| `git-branch-dash prune --all` | Prune all repos without prompting per-repo |
| `git-branch-dash repo add <path>` | Add a local Git repository |
| `git-branch-dash repo list` | List all tracked repositories |
| `git-branch-dash repo remove <name>` | Remove a tracked repository |
| `git-branch-dash config set <key> <value>` | Set a config value |
| `git-branch-dash config show` | Show current configuration |
| `git-branch-dash --help` | Show help |
| `git-branch-dash --version` | Show version |

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| `GBDASH_PORT` | Dashboard port | `7654` |
| `GBDASH_HOST` | Bind address | `127.0.0.1` |
| `GBDASH_DATA_DIR` | SQLite and config directory | `~/.git-branch-dashboard` |
| `GBDASH_GITHUB_TOKEN` | GitHub token (overrides config file) | (from config) |
| `GBDASH_GITLAB_TOKEN` | GitLab token (overrides config file) | (from config) |
| `GBDASH_SCAN_INTERVAL` | Auto-scan interval in minutes | `15` |
| `GBDASH_STALE_DAYS` | Days until a branch is stale | `31` |
| `GBDASH_VERY_STALE_DAYS` | Days until a branch is very stale | `90` |
| `GBDASH_LOG_LEVEL` | Log level: debug, info, warn, error | `info` |

## Staleness Tiers

| Tier | Age | Color |
|---|---|---|
| Fresh | 0-7 days | Green |
| Aging | 8-30 days | Yellow |
| Stale | 31-90 days | Orange |
| Very stale | 90+ days | Red |

Thresholds are configurable per-instance via Settings or environment variables. The default branch (main/master) is never classified as stale regardless of last commit date.

## Troubleshooting

**"No repositories tracked"** - Add at least one repository with `git-branch-dash repo add <path>`. The path must be an absolute path to a local Git clone.

**PR badges not showing** - Configure a GitHub token: `git-branch-dash config set github-token ghp_...`. Verify the token has `read:repo` scope and the repository owner/slug are correct in the repository settings.

**Scan fails with "not a git repository"** - Verify the path passed to `repo add` contains a `.git` directory. Submodules must be added individually if they have separate remotes.

**Stale thresholds not updating** - After changing thresholds in Settings, trigger a manual scan with `git-branch-dash scan` so all branches are reclassified against the new values.

**Port 7654 already in use** - Start on a different port: `GBDASH_PORT=7655 git-branch-dash start` or set it in the config file.

**Database locked error** - Only one instance of git-branch-dash should run at a time. Stop any existing instance before starting a new one.