I’ve always said there’s no better way to learn anything than to build something… and the second-best is reviewing someone else’s code.
Recently, at VirtusLab, we had a sobering realization – our “collection” of starred projects had grown to gigantic proportions, without bringing any real value either to us at VirtusLab or to the wider community. So we decided to change our approach: introduce a bit of regularity and become chroniclers of these open-source gems. That way, we’ll understand them better and discover where we can actually help.
Every other Wednesday, we’ll pick one trending repository from the previous week and give it some focused attention by preparing a tutorial, article, or code review – learning from its creators in the process. We’ll focus on whatever caught our eye: it could be a tool, a library, or anything the community deemed worth publishing. There’s just one simple rule – these have to be new or lesser-known projects, not the household names that suddenly get a flood of stars after a big update (because let’s be honest – who really wants to hear yet another breakdown of Angular’s architecture).
Today, we’re taking a look at a project that tackles one of the most embarrassing yet universal problems in our industry: f/git-rewrite-commits.
The Problem of a Neglected Git History
Let’s start with a small hot take: your Git commit history is one of the most important, and at the same time one of the most chronically neglected, artifacts in software engineering.
We all know the pain. You open a project’s git log to understand why a given change was introduced, and you’re greeted by chaos that looks like a rushed shopping list: “fix”, “update”, “wip”, “works”, “another fix”. These messages are informational noise. They’re worthless.
This problem is exactly what motivated today’s project, which takes aim at messy commit histories. As the author put it: “My Git history was full of ‘update’ and ‘fix’, so I built a tool to fix it using AI.”
And this is not just an aesthetic issue. It’s a cost issue. A neglected commit history makes git bisect - one of the most powerful debugging tools out there, if you don’t know it yet, you should - is practically useless. It slows down onboarding for new developers, who can’t reconstruct how the code evolved on their own. It turns understanding the context of a six-month-old change into an archeological nightmare worthy of Indiana Jones.
We treat Git history like a digital dumpster when it should really be a precise, readable captain’s log for the project. But what if we could hire an intelligent assistant to clean up that mess for us? That’s exactly what f/git-rewrite-commits promises to do.
Who and Why? The Philosophy of a “Rescue Tool”
In line with the tradition of this series, to understand the project, we first need to understand its creator and their motivation. The project was created by Fatih Kadir Akın, better known on GitHub as f.
Appreciating the minimalistic approach to the online identity.
At first glance, the idea of automatically rewriting commit history with AI seems… well, like heresy. A commit message is supposed to represent the author’s intent. How can a machine possibly reconstruct that intent? Isn’t that just falsifying history?
The Hacker News crowd immediately raised this objection, but Fatih’s response is key to understanding the real purpose of this project. When he was accused of “falsifying intent,” he explained the tool’s philosophy:
The goal of git-rewrite-commits is not to “polish” history or rewrite meaning; it’s more of a rescue tool for those chaotic early stages of side projects (like mine), where commits are basically just “update again” for months. In those cases, there was never any real “intent” captured in the first place, so the AI is simply adding structure and readability to something that has already lost its context.
That statement completely reframes how you see the project. This isn’t a tool for faking history. It’s a tool for creating a readable history where previously there was only chaos.
It’s not about replacing good, human intent with fake, machine intent. It’s about replacing the total absence of intent (e.g., “update”) with an inferred, structured intent. That’s a fundamental difference - and the key to understanding what problem git-rewrite-commits is actually solving.
Architecture: How grec Turns Chaos into Order
Let’s take a look at how it works under the hood.
The architecture of git-rewrite-commits is built on three elegant pillars.
Pillar 1: CLI Facade and History Rewrite Orchestrator
You interact with the tool through a simple command, e.g. npx grec (which is an alias for git-rewrite-commits). But beneath that simple surface, some dangerous magic is happening. The tool explicitly uses the powerful, slightly terrifying git filter-branch command to actually rewrite the repository’s history.
The architecture is designed defensively. The tool automatically:
- Creates a backup of the current branch before starting any destructive operation.
- Offers a crucial feature
--dry-run mode, which lets you preview the proposed changes without actually applying them. - Clearly instructs the user to run
git push \--force-with-leaseinstead of a plaingit push \--force, which helps prevent overwriting other people’s work.
Pillar 2: Decentralised Brain - Pluggable AI Providers
The tool’s “brain” – the language model that generates commit messages – is not a monolith. The architecture supports both remote APIs (OpenAI GPT by default) and, crucially, local models via Ollama.
Support for Ollama addresses the main adoption barrier for this kind of tool in corporate environments: privacy. Nobody wants to send diffs of their potentially sensitive source code to an external API.
By allowing the developer to run a local server and process all data 100% on their own machine, the architecture enables an “air-gapped” mode of operation. This shows a deep understanding of developers’ concerns.
Pillar 3: Git Hooks as the Gateway to Workflow (The Tool’s Dual Nature)
git-rewrite-commits offers powerful integration with your Git workflow via a single command: npx grec --install-hooks. This installer configures the prepare-commit-msg and pre-commit hooks.
This reveals that grec is actually two tools in one, sharing the same AI core:
- Batch Processor: grec run manually to rewrite an already existing, messy history (e.g.
grec --max-commits 10). - Real-time Assistant: grec integrated with hooks, generating new, clean commits at the moment they’re created (
git commit), before the chaos even appears.
This second role is architecturally different and potentially even more powerful. Instead of cleaning up after the fact, it treats the problem at the source.
Patterns and Techniques: The Good Stuff for Engineers
Pattern 1: AI Prompt as a Declarative Rewrite Rule
The developer doesn’t have to “program” in TypeScript to change the logic of message generation. Instead, they “program” the AI model declaratively, using simple templates and configuration. It’s the same pattern we saw in the LangExtract analysis – “declarative programming through prompts”.
grec lets you define your own template, for example, to integrate with a JIRA-based workflow:
You can also do this ad hoc from the command line during a rewrite:
All the complexity of natural language generation is hidden away. The developer only needs to define the expected structure (schema) of the output.
Pattern 2: CLI as a Surgical Risk-Control Tool
The CLI interface is designed not as a blunt hammer (“do everything”), but as a precise scalpel. It gives the user full control over the blast radius of this dangerous operation.
A key safety feature – preview without applying:
Switching context from history rewriting to generating messages for new changes (in the “staging area”):
And most importantly, limiting the operation to only the last N commits to avoid accidentally rewriting the entire project history:
The project shows a deep understanding of developer psychology. The fear of git rewrite is real. These flags are designed to build trust and minimise risk, which is absolutely crucial for tool adoption.
Pattern 3: Environment Configuration as a Safety Pattern
This is a repetition of what we saw in Pillar 2, but it’s worth framing it as a pattern. The tool uses Git configuration (git config) and environment variables to control key aspects, especially security and AI provider choice.
Choosing a local, secure provider (Ollama) instead of the default (OpenAI):
Starting a local server:
Alternatively, configuring a remote provider via an environment variable:
This pattern lets the tool run in any environment – from a developer’s private laptop (with Ollama) to a locked-down CI/CD system – without changing a single line of code, only by adjusting environment configuration.
Pattern 4: Extending DX (Developer Experience) with Shell/Git Aliases
The author doesn’t stop at shipping a CLI tool. They actively encourage plugging it into the native developer workflow via aliases, making the tool “disappear” and become part of Git itself.
Creating a new, “native” Git command:
Or creating shell aliases for repetitive tasks:
This shows the author’s maturity as a tool designer. They understand that the lowest friction is achieved when the tool becomes an invisible part of existing habits (like git commit or git push).
Conclusions: A Razor-Sharp (but essential) Tool
f/git-rewrite-commits is much more than a clever script. It’s a bold, pragmatic, and, let’s be honest, slightly dangerous tool that perfectly captures the spirit of our times. It harnesses the raw power of AI to tackle one of the most annoying and ubiquitous engineering problems.
The architecture is elegant: a façade hiding the underlying complexity, pluggable AI backends (with key support for Ollama), and a dual nature (batch processing and real-time assistant). The design patterns it uses (declarative configuration, safety via --dry-run, DX-focused extensibility through aliases) are a great example to follow for anyone building developer tools.
This tool is like a chainsaw. It demands respect, awareness, and you definitely shouldn’t run around the office with it. But in the right hands, with the right safeguards (--dry-run is your friend), it lets you do work that would take days to accomplish manually. Fatih Kadir Akın didn’t just give us a cleanup tool; he gave us a reason to have an important conversation about what “history” in our projects really is.
A very well-deserved star on GitHub. 😉
