{"_id":"@axiom-experiment/git-tidy","name":"@axiom-experiment/git-tidy","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@axiom-experiment/git-tidy","version":"1.0.0","description":"Clean up stale local git branches. Zero dependencies. Works on all platforms.","main":"index.js","bin":{"git-tidy":"bin/git-tidy.js"},"scripts":{"test":"jest --coverage","test:watch":"jest --watch"},"keywords":["git","branch","cleanup","cli","developer-tools","stale-branches","git-branch"],"author":{"name":"axiom-agent"},"license":"MIT","devDependencies":{"jest":"^29.0.0"},"engines":{"node":">=14.0.0"},"repository":{"type":"git","url":"git+https://github.com/axiom-agent/git-tidy.git"},"homepage":"https://github.com/axiom-agent/git-tidy#readme","bugs":{"url":"https://github.com/axiom-agent/git-tidy/issues"},"_id":"@axiom-experiment/git-tidy@1.0.0","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-Y5xQBIyX4NovdTYm6SIDCYo6KauneNoLzeZSt+2zib5BaGad4spbouE9NisIMVC68NMh27x6wscYjZ5vGAoUlA==","shasum":"2d79216cb247a72ec8e158397b23a967b44e3a53","tarball":"https://registry.npmjs.org/@axiom-experiment/git-tidy/-/git-tidy-1.0.0.tgz","fileCount":31,"unpackedSize":354809,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAx+oFqqGVYWttVHM5hFB6E8uiKleWkoY10kwGeytaZuAiAcM8hcX2S7WDNRfVxWE0INl8k8o42+Tl6BOBtGodAyDQ=="}]},"_npmUser":{"name":"axiom-experiment","email":"axiom.experiment@gmail.com"},"directories":{},"maintainers":[{"name":"axiom-experiment","email":"axiom.experiment@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/git-tidy_1.0.0_1774178087514_0.7366453298517679"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-22T11:14:47.429Z","1.0.0":"2026-03-22T11:14:47.686Z","modified":"2026-03-22T11:14:47.874Z"},"maintainers":[{"name":"axiom-experiment","email":"axiom.experiment@gmail.com"}],"description":"Clean up stale local git branches. Zero dependencies. Works on all platforms.","homepage":"https://github.com/axiom-agent/git-tidy#readme","keywords":["git","branch","cleanup","cli","developer-tools","stale-branches","git-branch"],"repository":{"type":"git","url":"git+https://github.com/axiom-agent/git-tidy.git"},"author":{"name":"axiom-agent"},"bugs":{"url":"https://github.com/axiom-agent/git-tidy/issues"},"license":"MIT","readme":"# git-tidy\n\n[![npm version](https://img.shields.io/npm/v/git-tidy.svg)](https://www.npmjs.com/package/git-tidy)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](https://www.npmjs.com/package/git-tidy)\n[![Node.js >=14](https://img.shields.io/badge/node-%3E%3D14.0.0-blue.svg)](https://nodejs.org/)\n\n**Clean up stale local git branches. Zero dependencies. Works on Windows, macOS, and Linux.**\n\n---\n\n## The Problem\n\nYou clone a repo, start a sprint, and three months later:\n\n```\n$ git branch\n  feature/auth-refactor\n  feature/button-fix-v2\n  feature/button-fix-v3-final\n  fix/login-page\n  hotfix/critical-bug-jan\n  hotfix/critical-bug-jan-ACTUALLY-FIXED\n  main\n* feature/current-work\n  release/1.2.0\n  release/1.3.0\n  wip/experiment-that-never-shipped\n```\n\nMost of those branches are dead. They were merged months ago, the remote was deleted, or they were abandoned experiments. But `git branch -d` requires you to know which ones are safe to delete — and doing it one by one is tedious.\n\n`git-tidy` finds them all and cleans them up in one shot.\n\n---\n\n## Quick Demo\n\n```\n$ git-tidy status\n\n  12 stale branches found out of 18 total (8 merged, 4 old)\n\n  Run git-tidy list to see stale branches, or git-tidy clean to remove them.\n\n$ git-tidy list\n\n  BRANCH                                    LAST COMMIT         STATUS\n  --------------------------------------------------------\n  hotfix/critical-bug-jan                   1 year 35 days ago  merged\n  release/1.2.0                             11 months ago       merged\n  feature/auth-refactor                     8 months ago        merged\n  fix/login-page                            7 months ago        merged\n  feature/button-fix-v2                     6 months ago        merged\n  feature/button-fix-v3-final              5 months ago        merged\n  wip/experiment-that-never-shipped         4 months ago        old\n  release/1.3.0                             3 months ago        merged\n\n$ git-tidy clean --dry-run\n\n  DRY RUN — the following branches would be deleted:\n\n  - hotfix/critical-bug-jan                   1 year 35 days ago    [merged]\n  - release/1.2.0                             11 months ago         [merged]\n  - feature/auth-refactor                     8 months ago          [merged]\n  ... (8 total)\n\n  8 branches would be deleted.\n  Run without --dry-run to delete them.\n\n$ git-tidy clean --force\n\n  ✓ Deleted hotfix/critical-bug-jan\n  ✓ Deleted release/1.2.0\n  ✓ Deleted feature/auth-refactor\n  ... (8 total)\n\n  8 branches deleted successfully.\n```\n\n---\n\n## Install\n\n```bash\n# Global install (recommended for CLI use)\nnpm install -g git-tidy\n\n# Or use without installing\nnpx git-tidy list\n```\n\n---\n\n## CLI Reference\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `git-tidy list` | List stale branches |\n| `git-tidy clean` | Delete stale branches (interactive prompt) |\n| `git-tidy status` | Quick summary of branch health |\n| `git-tidy --version` | Show version |\n| `git-tidy --help` | Show help |\n\n### Flags\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--merged` | Only include branches merged into base | false |\n| `--older-than <n>` | Only include branches older than N days | 90 |\n| `--base <branch>` | Base branch for merge detection | auto (main/master) |\n| `--dry-run` | Preview — show what would be deleted without deleting | false |\n| `--force` | Skip the confirmation prompt | false |\n| `--json` | Output results as JSON (list command) | false |\n\n### Usage Examples\n\n```bash\n# List all stale branches (merged or older than 90 days)\ngit-tidy list\n\n# List only merged branches\ngit-tidy list --merged\n\n# List branches with last commit older than 30 days\ngit-tidy list --older-than 30\n\n# Get JSON output for scripting\ngit-tidy list --json\n\n# Preview what would be deleted (safe — does not delete anything)\ngit-tidy clean --dry-run\n\n# Clean merged branches only, no prompt\ngit-tidy clean --force --merged\n\n# Clean branches merged into 'develop' that are 60+ days old\ngit-tidy clean --base develop --older-than 60\n\n# Quick health check\ngit-tidy status\n```\n\n---\n\n## Programmatic API\n\nInstall as a library:\n\n```bash\nnpm install git-tidy\n```\n\n```javascript\nconst gitTidy = require('git-tidy');\n\n// Check if git is available on PATH\nconst available = await gitTidy.isGitAvailable();\n// => true\n\n// Get the currently checked-out branch\nconst current = await gitTidy.getCurrentBranch();\n// => 'feature/my-branch'\n\n// Get all local branches (annotated with age, merge status, etc.)\nconst branches = await gitTidy.getBranches();\n// => [\n//   { name: 'main', ageInDays: 0, isCurrent: true, ... },\n//   { name: 'feature/old', ageInDays: 120, isCurrent: false, ... },\n//   ...\n// ]\n\n// Get stale branches (merged or old), excluding protected ones\nconst stale = await gitTidy.getStaleBranches({\n  olderThan: 30,       // branches with last commit > 30 days ago\n  mergedInto: 'main',  // check merges against this branch\n  exclude: ['release'] // additional branch names to protect\n});\n\n// Get stale merged branches only\nconst mergedOnly = await gitTidy.getStaleBranches({ mergedOnly: true });\n\n// Get detailed info about a specific branch\nconst info = await gitTidy.getBranchInfo('feature/my-branch', { base: 'main' });\n// => {\n//   name: 'feature/my-branch',\n//   lastCommit: Date,\n//   ageInDays: 45,\n//   upstreamGone: false,\n//   isCurrent: false,\n//   merged: true\n// }\n\n// Delete a single branch (returns result object, never throws)\nconst result = await gitTidy.deleteBranch('feature/old-thing');\n// => { branch: 'feature/old-thing', deleted: true, error: null }\n\n// Delete multiple branches\nconst results = await gitTidy.deleteBranches(['feature/a', 'feature/b']);\n// => [\n//   { branch: 'feature/a', deleted: true, error: null },\n//   { branch: 'feature/b', deleted: false, error: Error('not merged') }\n// ]\n```\n\n### API Reference\n\n#### `isGitAvailable() → Promise<boolean>`\nReturns `true` if git is installed and accessible on the system PATH.\n\n#### `getCurrentBranch(options?) → Promise<string>`\nReturns the name of the currently checked-out branch. Returns an empty string in detached HEAD state.\n\n#### `getBranches(options?) → Promise<Branch[]>`\nReturns all local branches, annotated with age and metadata.\n\n**Options:**\n- `olderThan` *(number)* — Days threshold for the `isOld` annotation (default: 90)\n- `cwd` *(string)* — Working directory (default: `process.cwd()`)\n\n#### `getStaleBranches(options?) → Promise<Branch[]>`\nReturns branches that are stale (merged, old, or with deleted remote tracking). Protected and current branches are always excluded. Results are sorted oldest-first.\n\n**Options:**\n- `olderThan` *(number)* — Age threshold in days (default: 90)\n- `mergedInto` *(string)* — Base branch for merge detection (default: auto-detects main/master)\n- `exclude` *(string[])* — Additional branch names to protect from deletion\n- `mergedOnly` *(boolean)* — If true, only return merged branches\n- `cwd` *(string)* — Working directory\n\n#### `getBranchInfo(branchName, options?) → Promise<BranchInfo>`\nReturns detailed info about a single branch. Throws if the branch does not exist.\n\n**Options:**\n- `base` *(string)* — Base branch to check merge status against\n- `cwd` *(string)* — Working directory\n\n#### `deleteBranch(branchName, options?) → Promise<DeleteResult>`\nDeletes a local branch. Returns a result object — never throws. Protected and current branches return `{ deleted: false, error: ... }`.\n\n**Options:**\n- `force` *(boolean)* — Use `-D` (force delete) instead of `-d` (default: false)\n- `cwd` *(string)* — Working directory\n\n#### `deleteBranches(branchNames[], options?) → Promise<DeleteResult[]>`\nDeletes multiple branches and returns results for each. Throws `TypeError` if input is not an array.\n\n### Branch Object Shape\n\n```typescript\n{\n  name: string;          // branch name\n  lastCommit: Date|null; // date of last commit\n  ageInDays: number;     // days since last commit (Infinity if unknown)\n  upstreamGone: boolean; // true if remote tracking branch was deleted\n  isCurrent: boolean;    // true if currently checked out\n  merged: boolean;       // true if merged into base branch\n  isOld: boolean;        // true if ageInDays > olderThan threshold\n}\n```\n\n---\n\n## Configuration\n\n### Protected Branches\n\nThe following branches are **always** protected and will never be deleted, regardless of age or merge status:\n\n```\nmain, master, develop, dev, staging, production, release\n```\n\nTo protect additional branches when using the API, pass them in the `exclude` option:\n\n```javascript\nconst stale = await gitTidy.getStaleBranches({\n  exclude: ['my-long-running-branch', 'qa']\n});\n```\n\n### Default Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `olderThan` | `90` | Branches older than 90 days are considered stale |\n| `base` | `null` | Auto-detects `main` or `master` |\n| `json` | `false` | Plain text output |\n| `dryRun` | `false` | Actually deletes |\n| `force` | `false` | Asks for confirmation |\n\n---\n\n## How It Works\n\n1. Runs `git branch --format='...'` to get all local branches with metadata\n2. Filters out protected branches (main, master, develop, etc.) and the current branch\n3. Runs `git branch --merged <base>` to find merged branches\n4. Identifies old branches by comparing last commit date to the threshold\n5. Identifies branches with deleted remote tracking (`[gone]` in upstream status)\n6. Deletes with `git branch -d` (merged) or `git branch -D` (unmerged old branches)\n\n---\n\n## Platform Support\n\ngit-tidy uses only Node.js built-ins (`child_process`, `readline`, `os`, `path`, `fs`) and has zero runtime dependencies. It works on:\n\n- macOS\n- Linux\n- Windows (PowerShell, CMD, Git Bash)\n\n---\n\n## Sponsorship\n\nIf git-tidy saves you time, consider sponsoring its development:\n\n[https://github.com/sponsors/axiom-agent](https://github.com/sponsors/axiom-agent)\n\n---\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/my-improvement`\n3. Make your changes and add tests\n4. Run the test suite: `npm test`\n5. Submit a pull request\n\n### Development\n\n```bash\ngit clone https://github.com/axiom-agent/git-tidy.git\ncd git-tidy\nnpm install\nnpm test\n```\n\n### Running Tests\n\n```bash\nnpm test              # run all tests with coverage\nnpm run test:watch    # watch mode for development\n```\n\n---\n\n## Links\n\n- [npm package](https://www.npmjs.com/package/git-tidy)\n- [GitHub repository](https://github.com/axiom-agent/git-tidy)\n- [Issue tracker](https://github.com/axiom-agent/git-tidy/issues)\n\n---\n\n## License\n\nMIT © axiom-agent\n\n```\nMIT License\n\nCopyright (c) 2024 axiom-agent\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n","readmeFilename":"README.md","_rev":"1-db3d5653cea013482c0d2235a5697aaa"}