We’ve all had this Friday afternoon.
You’ve been deep in "flow state" for four hours. You’ve fixed a nagging bug in the auth middleware, refactored a messy utility function, and added a new endpoint for the user profile. Your terminal shows 15 files changed across four different concerns.
Now comes the part every developer hates: The Administrative Overhead.
You have to manually stage the files, write a commit, stage the refactor, link the Linear ticket, and eventually write a Pull Request description that doesn’t just say "see commits". In that moment, you aren't an engineer. You are middleware—the manual glue between your IDE, your Git history, and your issue tracker.
I got tired of being the glue, so I built git-ship.
The Invisible Cost of "Commit Hygiene Debt"
We’re often told that "clean commits" are an aesthetic choice. They aren't. They are a functional requirement for high-velocity teams. When we default to git commit -am "update stuff", we accrue "Commit Hygiene Debt":
- Reviewer Fatigue: A single PR with one massive commit is impossible to digest. Reviewers end up reviewing line-by-line instead of logic-by-logic.
- The Revert Risk: If a feature breaks production, but the commit includes an unrelated refactor, you can't safely undo it. You're forced into high-stress "surgical" hotfixing while the site is down.
-
Broken Debugging: Powerful tools like
git bisectonly work if commits represent atomic, functional states.
The Solution: A Context-Aware Pipeline
git-ship is an AI-powered CLI that replaces twenty minutes of manual labor with a single command: gs. It orchestrates an 8-step pipeline that connects the Why (your issue tracker) with the What (your code).
How AI Grouping Actually Works
The hardest part of this was the grouping logic. How do you decide which files belong together? I developed a dual-heuristic model:
- The Revert Test (Safety Floor): "If this commit were reverted, would the codebase still compile?". Files with hard dependencies (like a database migration and the code using it) must stay together.
- The Review Test (Quality Goal): "Can a reviewer understand this commit in isolation?". We strive for focus—separating tests from implementation and config from features.
The Elephant in the Room: Why not just use a Claude Skill?
An honest question I get often is: If I'm already using Claude Code, why do I need a separate package? If you are living inside a chat-based assistant, a /commit skill might actually be better for your personal flow. It already has the context of your entire conversation. But for professional engineering teams, a dedicated CLI offers advantages that an integrated assistant cannot:
| Aspect | git-ship CLI | AI Assistant Skill (e.g., Claude Code) |
|---|---|---|
| Context | Reads diffs + fetches tracker data | Knows the "Why" from your active chat history |
| Accessibility | Works for everyone on the team | Only works for those with a specific subscription |
| Portability | Can run in any terminal or CI/CD pipeline | Locked to the specific AI environment |
| Agnosticism | Choose OpenAI, Anthropic, or Gemini | Locked to one provider's ecosystem |
| Reliability | Degrades gracefully (e.g., works offline) | Requires active API/Socket connection |
The Honest Take: If you're in the middle of a deep conversation with Claude, use the skill. But if you want a repeatable, team-wide standard that works across any editor and integrates with your CI/CD, a specialized CLI is the way to go.
Let the AI Handle the Paperwork
The goal of git-ship isn't to replace your judgment; it's to automate the mechanical work so you can keep the judgment calls. By making the "right way" to ship also the "fastest way" to ship, we eliminate the trade-off between speed and quality.
Try it today:
npm install -g git-ship
Open Source:
github.com/thisismayank/git-ship
I would love to hear your thoughts on what your commit pipeline looks like today 👇
Top comments (0)