Git-Cleaner: Automated Node.js Branch Cleanup
An interactive CLI tool designed to maintain Git repository hygiene by identifying and safely removing old branches.
Problem Statement
In active development teams, feature, fix, and chore branches accumulate rapidly. Git doesn't automatically clean them up after a merge, and doing so manually is tedious and prone to error.
Accumulating hundreds of stale branches creates visual noise, hinders autocompletion, and causes confusion about the actual state of pending work.
Solution: Git-Cleaner
Git-Cleaner is an interactive CLI tool designed to maintain the hygiene of your Git repositories. It helps identify and safely remove stale branches by applying smart filters for author, date, and merge status.
Features
Easy-to-use CLI menu (no need to remember complex flags).
Visualize which branches would be deleted before touching anything.
TARGET_USERS) or everyone's EXCEPT certain users (EXCLUDE_USERS).main/master or review all old ones. List of protected branches that will never be deleted (e.g., main, dev).
Installation
The process is simple. First clone the repository and then install the dependencies.
Configuration
Before using it, create your configuration file based on the provided example.
Edit the .env file with your preferences:
| Variable | Description | Example |
|---|---|---|
TARGET_USERS | List of authors to clean (separated by |) | jdoe|asmith |
EXCLUDE_USERS | Users to exclude. Ignores TARGET_USERS if defined | admin|bot |
PROTECTED_BRANCHES | Branches that will never be deleted | main,master,release |
GIT_PATH | Absolute path to the repo (optional) | /Users/me/repo |
Usage
Run the script directly with Node.js:
The interactive assistant will guide you through two main steps:
1. Select Mode
Lists candidate branches without deleting anything. (Recommended to start)
Proceeds to delete selected branches (requires final confirmation).
2. Select Filter
Applies date and author filters, regardless of whether Git knows they are merged.
Additionally verifies if the branch exists in origin/main or origin/master.
In Action Mode, the tool will always ask for an explicit final confirmation before executing git push origin :branch. It will never delete anything without your final "YES".
Execution Example
Here is how a typical run looks in your terminal:
Security First
Security is not an optional feature; it is the absolute priority of Git-Cleaner. We have designed every step to be non-destructive by default.
Triple Layer Protection
The system strictly respects your PROTECTED_BRANCHES configuration. Branches like main, master, dev, or release/* are invisible to the deletion process. They will never be suggested.
"Test Mode" is the default. You can see a complete audit of:
Nothing is deleted until you see it clearly.
Even in "Action Mode", the system pauses before executing the final command.
Are you sure you want to delete these X branches? (y/n)
Without your explicit final confirmation, the git push --delete command never runs.