git-shrink

Semantic git history compressor — intelligently squashes bloated commit histories by analyzing message similarity, file proximity, directory overlap, and time windows.

  git-shrink v1.0.0  — semantic commit history compressor

  ✔ Loaded 47 commits
  ✔ Found 9 squash group(s) — history shrinks 47 → 18 commits (62% reduction)

  Group 1/9 — touch the same file(s): src/auth/middleware.js · committed within 14min
  Suggested message: "feat: implement OAuth2 PKCE flow with refresh token rotation"
  Similarity score:  ████████████████░░░░  80/100

The problem

Every long-running codebase has this:

abc1234  fix
def5678  fix again
fff0001  wip
aaa9999  temp
bbb1111  ok now it works
ccc2222  actually works now

git rebase -i helps, but it requires you to manually identify which commits belong together — across dozens or hundreds of entries. That doesn't scale.

git-shrink automates the grouping. It scores every pair of commits across four dimensions and suggests squash groups you can approve, edit, or skip — then writes a ready-to-apply rebase script.

Install

npm install -g git-shrink

Requires Node.js ≥ 18.

Usage

Analyze (interactive)

git-shrink analyze

Analyzes the last 50 commits, scores pairs, and walks you through each suggested group interactively.

Analyze (auto mode)

git-shrink analyze --auto --count 100

Skips the interactive prompt — auto-approves all groups above the similarity threshold.

Dry run

git-shrink analyze --dry-run

Shows what would be grouped without writing any files. Safe to run on any repo.

Commit health stats

git-shrink stats

Prints a health report: noisy commit ratio, oversized commits, hot directories, and an overall history health score.

Apply a saved plan

git-shrink apply git-shrink-plan-1706123456789.txt

Executes a previously generated rebase plan after a final confirmation prompt.

# Force apply on a feature/fix branch that has already been pushed
git-shrink apply git-shrink-plan-1706123456789.txt --force

Options

git-shrink analyze

| Flag | Default | Description | |------|---------|-------------| | --count <n> | 50 | Number of commits to analyze from HEAD | | --from <hash> | — | Start of commit range | | --to <hash> | HEAD | End of commit range | | --branch <name> | — | Analyze a specific branch | | --auto | false | Skip interactive prompts, approve all groups | | --dry-run | false | Preview only, no files written | | --threshold <0-100> | 50 | Minimum similarity score to form a group | | --min-group <n> | 2 | Minimum commits required to form a group |

git-shrink apply

| Flag | Default | Description | |------|---------|-------------| | --dry-run | false | Validate the plan without executing the rebase | | -f, --force | false | Skip the pushed-commit guardrail — use on feature/fix branches |

git-shrink stats

| Flag | Default | Description | |------|---------|-------------| | --count <n> | 100 | Number of commits to include in the health report |

How the scoring works

Every pair of commits is scored across four dimensions, then combined into a weighted composite:

| Dimension | Weight | Method | |-----------|--------|--------| | Message similarity | 55% | Levenshtein distance on normalized messages — strips conventional commit prefixes (fix:, feat:) and noise words (wip, temp, minor) before comparing | | File proximity | 30% | Jaccard similarity of changed file sets — commits touching the same files score high regardless of message wording | | Directory overlap | 15% | Jaccard similarity of parent directories — weaker structural signal, useful when file names differ but work is in the same area |

Time proximity and branch origin are intentionally excluded. They group commits that happen to be close in time or on the same branch, not commits that are semantically related — which is the wrong heuristic for history cleanup.

Pairs scoring above --threshold are clustered using union-find. The suggested squash message is the most semantically meaningful message within the group (longest after noise removal).

Config file

Place a .gitshrinkrc in your project root (or add a gitshrink key to package.json):

{
  "threshold": 65,
  "timeWindow": 20,
  "minGroup": 2,
  "count": 75
}

Safety

git-shrink analyze and git-shrink stats are read-only. They never touch your git history.

git-shrink apply rewrites history via interactive rebase. It will:

• Show a full preview of the rebase plan
• Warn you explicitly that history will be rewritten
• Require a confirmation prompt before executing
• Print git rebase --abort instructions if anything goes wrong

Pushed-commit guardrail — apply will refuse to run if any commit in the plan has already been pushed to a remote, and will tell you exactly which ones. To bypass this on a feature or fix branch where force-pushing is acceptable, use --force.

Empty-commit detection — if a squash group's commits cancel each other out (e.g. "add logs" followed by "remove logs"), analyze warns you at plan-generation time and apply automatically drops the empty result rather than halting mid-rebase.

Never run on shared branches that other developers have pulled without coordinating first. Always use git push --force-with-lease (not --force) after applying on a pushed branch.

Example workflow

# 1. Check your repo health first
git-shrink stats

# 2. Preview what would be grouped (no files written)
git-shrink analyze --dry-run --count 80

# 3. Run interactively and approve/edit/skip groups
git-shrink analyze --count 80

# 4. Review the generated plan
cat git-shrink-plan-*.txt

# 5. Apply it
git-shrink apply git-shrink-plan-*.txt

# 6. Verify
git log --oneline

Limitations

• Analyzes up to ~200 commits efficiently (O(n²) pair scoring). For larger ranges, use --from/--to to target specific ranges.
• Merge commits are automatically excluded from analysis.
• Rebase rewrites history — coordinate with your team before running on shared branches.

Local development

Prerequisites

• Node.js ≥ 18
• npm ≥ 9

Setup

git clone https://github.com/santoshkumar-in/git-shrink.git
cd git-shrink
npm install

Run locally without installing globally

# Run directly
node src/index.js analyze

# Or link it so `git-shrink` resolves as a command globally on your machine
npm link
git-shrink analyze

npm link creates a symlink from your global bin to src/index.js. Run npm unlink -g git-shrink to remove it.

Project structure

src/
├── index.js              # CLI entry point — wires Commander commands
├── commands/
│   ├── analyze.js        # `git-shrink analyze` — fetch, score, prompt, write plan
│   ├── apply.js          # `git-shrink apply`   — validate plan, run rebase
│   └── stats.js          # `git-shrink stats`   — commit health report
├── core/
│   ├── git.js            # simple-git wrapper — getCommits(), generateRebaseScript()
│   └── grouper.js        # scoring engine — scorePair(), groupCommits(), union-find
└── utils/
    ├── config.js          # cosmiconfig loader for .gitshrinkrc
    └── render.js          # terminal rendering — tables, score bars, summary box

Key modules to know

src/core/grouper.js is the heart of the tool. scorePair(commitA, commitB) returns a weighted composite score across message similarity (Levenshtein), file proximity (Jaccard), and directory overlap (Jaccard). groupCommits() runs union-find over all pairs to produce clusters. This is the right place to add new scoring dimensions or tune weights.

src/core/git.js wraps simple-git. getCommits() fetches the log with per-commit file diffs. generateRebaseScript() serializes groups into a git rebase -i todo format.

src/commands/analyze.js is the main user-facing flow — it calls both modules above, handles interactive prompts via inquirer, and writes the plan file.

Running tests

npm test

Tests use Jest with --experimental-vm-modules for ESM support. Test files live in __tests__/ (create this directory if adding new tests).

To test a specific file:

node --experimental-vm-modules node_modules/.bin/jest grouper

Linting

npm run lint

Uses ESLint. The config is expected at .eslintrc.json or eslint.config.js in the root — add one if you're setting up a fresh clone for contribution.

Testing against a real repo

The most useful local test is running it against an actual repository with a noisy history:

# Point it at any git repo on your machine
cd /path/to/some/other/repo
node /path/to/git-shrink/src/index.js analyze --dry-run --count 30

--dry-run makes this completely safe — it scores and renders groups but writes nothing.

Config for development

Create a .gitshrinkrc in any test repo to override defaults without flags:

{
  "threshold": 50,
  "minGroup": 2,
  "count": 30,
  "cleanupPlan": true
}

Contributing

Bug reports and pull requests are welcome. For significant changes, open an issue first to discuss what you'd like to change.

When contributing:

• Keep new scoring dimensions in src/core/grouper.js and update the weights table in this README
• All write operations must remain behind --dry-run support
• The apply command must always require explicit confirmation — don't remove or default it to true

License

MIT © Santosh Kumar