deadbranch

Clean up stale git branches safely.

Demo

✨ Features

🔍 List stale branches — Find branches older than N days (default: 30)
🔒 Safe deletion — Only deletes merged branches by default
🛡️ Protected branches — Never touches main, master, develop, staging, or production
🚧 WIP detection — Automatically excludes wip/* and draft/* branches
💾 Backup creation — Saves deleted branch SHAs for easy restoration
👁️ Dry-run mode — Preview what would be deleted without making changes
🌐 Local & remote — Works with both local and remote branches
🖥️ Interactive TUI mode — Full-screen TUI with Vim navigation, fuzzy search, visual range selection, and 6-column sorting

📦 Installation

⚡ Quick Install (macOS/Linux)

curl -sSf https://raw.githubusercontent.com/armgabrielyan/deadbranch/main/install.sh | sh

🍺 Homebrew (macOS/Linux)

brew install armgabrielyan/tap/deadbranch

📦 npm/npx

# Install globally
npm install -g deadbranch

# Or run directly
npx deadbranch list

🦀 Cargo (from source)

cargo install deadbranch

⬇️ Manual Download

Download pre-built binaries from the GitHub Releases page.

Platform	Architecture	Download
Linux	x86_64 (glibc)	`deadbranch-VERSION-x86_64-unknown-linux-gnu.tar.gz`
Linux	x86_64 (musl/static)	`deadbranch-VERSION-x86_64-unknown-linux-musl.tar.gz`
Linux	ARM64	`deadbranch-VERSION-aarch64-unknown-linux-gnu.tar.gz`
macOS	Intel	`deadbranch-VERSION-x86_64-apple-darwin.tar.gz`
macOS	Apple Silicon	`deadbranch-VERSION-aarch64-apple-darwin.tar.gz`
Windows	x86_64	`deadbranch-VERSION-x86_64-pc-windows-msvc.zip`

🔨 Build from Source

git clone https://github.com/armgabrielyan/deadbranch
cd deadbranch
cargo build --release
# Binary will be at target/release/deadbranch

🐚 Shell Completions

deadbranch can generate tab-completion scripts for bash, zsh, and fish.

Bash

mkdir -p ~/.local/share/bash-completion/completions
deadbranch completions bash > ~/.local/share/bash-completion/completions/deadbranch

Requires bash-completion 2.x to be active. On macOS without Homebrew's bash, source the file manually in ~/.bash_profile:

source ~/.local/share/bash-completion/completions/deadbranch

Zsh

mkdir -p ~/.zfunc
deadbranch completions zsh > ~/.zfunc/_deadbranch

Then add the following to your ~/.zshrc before the compinit call (or add it if you don't have one):

fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

Reload your shell or run exec zsh to activate.

Fish

mkdir -p ~/.config/fish/completions
deadbranch completions fish > ~/.config/fish/completions/deadbranch.fish

Fish auto-loads completions from this directory — no extra configuration needed.

🚀 Quick Start

# List all stale branches (older than 30 days)
deadbranch list

# List branches older than 60 days
deadbranch list --days 60

# Preview what would be deleted
deadbranch clean --dry-run

# Delete merged stale branches (with confirmation)
deadbranch clean

# Delete only local branches
deadbranch clean --local

# Show branch health overview
deadbranch stats

🛠️ Usage

📋 List Stale Branches

deadbranch list [OPTIONS]

Option	Description
`-d, --days <N>`	Only show branches older than N days (default: 30)
`--local`	Only show local branches
`--remote`	Only show remote branches
`--merged`	Only show merged branches

Example output:

ℹ Using 'main' as the default branch for merge detection

Local Branches:
┌────┬──────────────────────┬─────────┬────────┬───────┬──────────────┬──────────────┐
│ #  │ Branch               │ Age     │ Status │ Type  │ Last Commit  │ Author       │
├────┼──────────────────────┼─────────┼────────┼───────┼──────────────┼──────────────┤
│ 1  │ feature/old-api      │ 154d    │ merged │ local │ 2024-09-01   │ Jane Doe     │
│ 2  │ bugfix/header-issue  │ 89d     │ merged │ local │ 2024-11-03   │ John Smith   │
└────┴──────────────────────┴─────────┴────────┴───────┴──────────────┴──────────────┘

Remote Branches:
┌────┬─────────────────────────────────┬─────────┬────────┬────────┬──────────────┬──────────────┐
│ #  │ Branch                          │ Age     │ Status │ Type   │ Last Commit  │ Author       │
├────┼─────────────────────────────────┼─────────┼────────┼────────┼──────────────┼──────────────┤
│ 1  │ origin/feature/deprecated       │ 203d    │ merged │ remote │ 2024-07-15   │ Jane Doe     │
└────┴─────────────────────────────────┴─────────┴────────┴────────┴──────────────┴──────────────┘

🗑️ Delete Stale Branches

deadbranch clean [OPTIONS]

Option	Description
`-d, --days <N>`	Only delete branches older than N days (default: 30)
`--merged`	Only delete merged branches (this is the default)
`--force`	Force delete unmerged branches (dangerous!)
`--dry-run`	Show what would be deleted without doing it
`--local`	Only delete local branches
`--remote`	Only delete remote branches
`-y, --yes`	Skip confirmation prompts (useful for scripts)

Safety features:

Only deletes merged branches by default
Requires --force to delete unmerged branches
Shows confirmation prompt before deletion
Extra confirmation for remote branches
Creates backup file with branch SHAs

Example:

$ deadbranch clean

Local Branches to Delete:
┌────┬──────────────────────┬─────────┬────────┬───────┬──────────────┬──────────────┐
│ #  │ Branch               │ Age     │ Status │ Type  │ Last Commit  │ Author       │
├────┼──────────────────────┼─────────┼────────┼───────┼──────────────┼──────────────┤
│ 1  │ feature/old-api      │ 154d    │ merged │ local │ 2024-09-01   │ Jane Doe     │
│ 2  │ bugfix/header-issue  │ 89d     │ merged │ local │ 2024-11-03   │ John Smith   │
└────┴──────────────────────┴─────────┴────────┴───────┴──────────────┴──────────────┘

Delete 2 local branches? [y/N] y

Deleting local branches...
  ✓ feature/old-api
  ✓ bugfix/header-issue

✓ Deleted 2 local branches
  ↪ Backup: ~/.deadbranch/backups/my-repo/backup-20250201-143022.txt

🖥️ Interactive Mode

Open a full-screen TUI for browsing, filtering, and selecting branches to delete:

deadbranch clean -i [OPTIONS]

Option	Description
`-i, --interactive`	Open interactive TUI for branch selection
`-d, --days <N>`	Pre-filter to branches older than N days
`--merged`	Start with merged-only filter active
`--force`	Unlock unmerged branches for selection
`--local`	Start with local-only filter active
`--remote`	Start with remote-only filter active

Key bindings:

Key	Action
`j`/`↓`, `k`/`↑`	Navigate down/up
`gg`, `G`	Jump to top/bottom
`Ctrl+d`/`Ctrl+u`	Half-page down/up
`Ctrl+f`/`Ctrl+b`	Full-page down/up
Mouse scroll	Scroll up/down
`Space`	Toggle selection
`V`	Visual range select (Vim-style)
`a`	Select all merged
`A`	Select all (requires `--force`)
`n`	Deselect all
`i`	Invert selection
`d`	Delete selected
`/`	Fuzzy search by branch name
`s`	Cycle sort (age → branch → status → type → date → author)
`S`	Reverse sort direction
`m`	Toggle merged-only filter
`l`	Toggle local-only filter
`R`	Toggle remote-only filter
`?`	Help
`q`/`Esc`	Quit

TUI features:

Vim-style navigation — gg/G jump, Ctrl+d/Ctrl+u page scrolling, relative line numbers
Visual range selection — Press V to anchor, move cursor to extend range, Space to toggle
Fuzzy search — / opens search with matched characters highlighted
Age coloring — Green (<30d), yellow (31–90d), red (>90d)
Sections — Merged and unmerged branches are visually grouped with section headers
Snap dissolution — Thanos-style particle animation on deletion with a live progress gauge; branches are deleted in the background while the animation plays
Smart confirmation — Simple confirm for safe deletions, typed yes for risky ones (unmerged/remote)

Note: -i cannot be combined with -y (skip confirmation) or --dry-run.

🔍 Dry Run Mode

Preview deletions without making any changes:

$ deadbranch clean --dry-run

Local Branches to Delete:
┌────┬──────────────────────┬─────────┬────────┬───────┬──────────────┬──────────────┐
│ #  │ Branch               │ Age     │ Status │ Type  │ Last Commit  │ Author       │
├────┼──────────────────────┼─────────┼────────┼───────┼──────────────┼──────────────┤
│ 1  │ feature/old-api      │ 154d    │ merged │ local │ 2024-09-01   │ Jane Doe     │
└────┴──────────────────────┴─────────┴────────┴───────┴──────────────┴──────────────┘

[DRY RUN] Commands that would be executed:
  git branch -d feature/old-api

No branches were actually deleted.

⚙️ Configuration

deadbranch stores its configuration in ~/.deadbranch/config.toml.

# Show current configuration
deadbranch config show

# Set default age threshold
deadbranch config set days 45

# Set default branch for merge detection
deadbranch config set default-branch main

# Set protected branches
deadbranch config set protected-branches main master develop

# Set exclude patterns
deadbranch config set exclude-patterns "wip/*" "draft/*" "temp/*"

# Open config in your editor
deadbranch config edit

# Reset to defaults
deadbranch config reset

Default configuration:

[general]
default_days = 30

[branches]
protected = ["main", "master", "develop", "staging", "production"]
exclude_patterns = ["wip/*", "draft/*", "*/wip", "*/draft"]

Config keys

Key	Aliases	Description
`days`	`default-days`, `general.default-days`	Default age threshold in days
`default-branch`	`branches.default-branch`	Branch used for merge detection (auto-detected if unset)
`protected-branches`	`branches.protected`	Branches that are never deleted
`exclude-patterns`	`branches.exclude-patterns`	Glob patterns for branches to skip

💾 Backup Management

Every deadbranch clean run automatically creates a backup. Use deadbranch backup to manage those backups.

List backups

# Show a summary of all repositories with backups
deadbranch backup list

# Show backups for the current repository
deadbranch backup list --current

# Show backups for a specific repository
deadbranch backup list --repo my-repo

Restore a deleted branch

# Restore from the most recent backup
deadbranch backup restore feature/old-api

# Restore from a specific backup file
deadbranch backup restore feature/old-api --from backup-20250201-143022.txt

# Restore with a different name
deadbranch backup restore feature/old-api --as feature/recovered

# Overwrite an existing branch
deadbranch backup restore feature/old-api --force

Backup statistics

# Show storage usage per repository and overall
deadbranch backup stats

Clean up old backups

# Keep the 10 most recent backups for the current repo (default)
deadbranch backup clean --current

# Keep only the 3 most recent backups
deadbranch backup clean --current --keep 3

# Preview what would be removed
deadbranch backup clean --current --dry-run

# Skip confirmation prompt
deadbranch backup clean --current --yes

# Clean backups for a specific repository by name
deadbranch backup clean --repo my-repo

📊 Branch Statistics

Get a health overview of all branches in your repository:

deadbranch stats [OPTIONS]

Option	Description
`-d, --days <N>`	Age threshold for "stale" classification (default: from config or 30)

Example output:

ℹ Using 'main' as the default branch for merge detection

Repository Statistics:
┌────────────────┬───────┬───────┬────────┐
│ Category       │ Total │ Local │ Remote │
├────────────────┼───────┼───────┼────────┤
│ All branches   │ 12    │ 7     │ 5      │
│ Merged         │ 8     │ 5     │ 3      │
│ Unmerged       │ 4     │ 2     │ 2      │
│ Stale (>30d)   │ 6     │ 4     │ 2      │
│ Safe to delete │ 5     │ 3     │ 2      │
└────────────────┴───────┴───────┴────────┘

Age Distribution:
┌─────────────┬───────┬────────┐
│ Age Range   │ Count │ Status │
├─────────────┼───────┼────────┤
│ < 7 days    │ 2     │ fresh  │
│ 7–30 days   │ 4     │ fresh  │
│ 30–90 days  │ 3     │ stale  │
│ > 90 days   │ 3     │ stale  │
└─────────────┴───────┴────────┘

💡 Run 'deadbranch clean' to remove 5 safe-to-delete branches

Stats cover all visible branches (respecting protected and exclude patterns) regardless of age, so --days only shifts the stale/safe-to-delete threshold — it doesn't hide branches.

🛡️ Safety Features

deadbranch is designed to prevent accidental data loss:

Feature	Description
Merged-only default	Only deletes branches already merged to main/master
Protected branches	Never deletes main, master, develop, staging, production
Current branch	Never deletes the branch you're currently on
WIP detection	Excludes branches matching `wip/`, `draft/`, etc.
Confirmation prompts	Always asks before deleting
Remote warning	Extra confirmation for remote deletions
Backup files	Saves SHA of every deleted branch for restoration
Dry-run mode	Preview changes without risk

♻️ Restoring Deleted Branches

Every deletion creates a backup file at ~/.deadbranch/backups/<repo>/backup-<timestamp>.txt.

The backup contains git commands to restore each branch:

# From the backup file:
git branch feature/old-api abc1234def5678
git branch bugfix/header-issue 987654fedcba

You can restore branches manually by running those commands, or use the deadbranch backup restore command.

🔤 Pattern Matching

Exclude patterns support glob-style wildcards:

Pattern	Matches
`wip/*`	`wip/experiment`, `wip/test`
`*/draft`	`feature/draft`, `bugfix/draft`
`feature/*/temp`	`feature/foo/temp`, `feature/bar/temp`
`test`	`test`, `testing`, `my-test-branch`

📋 Requirements

Git (installed and accessible in PATH)
A git repository (run from within a repo)

🗺️ Roadmap

🖥️ Interactive TUI mode
👤 --only-mine flag for personal branches
🔗 GitHub/GitLab PR detection
📊 Multiple output formats (JSON, CSV)
📁 Per-repo configuration

⭐ Star History

📄 License

MIT License — see LICENSE for details.

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup, commit message conventions, testing requirements, and how to submit a pull request.

Name		Name	Last commit message	Last commit date
.github		.github
demo		demo
pkg		pkg
src		src
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.release-please-manifest.json		.release-please-manifest.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
build.rs		build.rs
install.sh		install.sh
release-please-config.json		release-please-config.json

Latest commit

History

Folders and files

Repository files navigation