iTranslated by AI
Easily Write Well-Formed Commit Messages: I Built 'commit-wand', a CLI That Lints and Rewrites Them
Nice to meet you. I'm Ziba, currently diving deep into TypeScript.
This is my first time writing an article on Zenn, so I'll give a brief self-introduction.
- Hobbies: Gaming (Minecraft, etc.), coding (vibe coding[1]), Discord
- Programming Language: TypeScript (currently learning) - mainly developing bots with discord.js and CLI tools. React etc. are still in progress.
Enough preamble—let's get straight to the point.
Everyone, are you confident you're writing commit messages properly?
I'm guessing most of you aren't.
I'm certainly one of them.
One day, while struggling with how to write commit messages, I came across a commit message convention.
That convention is Conventional Commits.
Most developers are probably familiar with it, but to summarize simply:
<type>[optional scope]: <description>
This is the rule that tells you to write commit messages in this format.
Indeed, following this rule might help you write clearer commit messages.
But manually writing commit messages that comply with this rule is tedious.
That's when I discovered an npm package called "commitlint" that can lint commit messages.
However, it also has a problem.
commitlint only points out rule violations, it doesn't guide you on how to write correctly.
Having a linter is better than nothing, but of course, it's much better if it also fixes things for you.
So I developed a CLI called commit-wand.
What kind of CLI is this?
commit-wand is a CLI built with TypeScript that lints commit messages and, if the message violates the rules, interactively rewrites it to comply with the rules.
Furthermore, it uses the parser provided by commitlint for linting, so even if you've been using commitlint before, you can create commit messages with the same feel.
For example, let's say you want to make a commit like "Added a send button."
git commit -m "hogehoge"
If a commit message that violates the rules is passed from git via husky, you'll see:
⚠ WARN The commit message is not compliant with Conventional Commits.
Current message: hogehoge
Please create a new commit message.
? Choose a commit type: ...
> feat
fix
docs
...
It detects the violation and prompts you to create a new commit message.
This prompt can be navigated using only keyboard arrow keys and text input, so you can intuitively create a commit message.
Additionally, it supports adding message body, breaking changes (BREAKING CHANGE), and issue-closing syntax (Closes #123), so you don't have to check the rules every time you commit—you can easily create commit messages.
How to Use
commit-wand activates the prompt automatically when committing, utilizing Husky's Git hook feature.
Setting up Husky usually requires running husky init, writing scripts, and so on—a bit of a hassle.
But to reduce the effort for many developers, just running:
# Use your package manager's script execution command
# The execution command is the abbreviation "cw" for commit-wand
npx cw init
will automatically perform everything from husky init to configuring the hook for this CLI.
ℹ INFO Setting up the magic...
Husky is not initialized. Initializing now...
✔ Husky initialized successfully.
✔ Successfully created .husky/commit-msg hook!
✔ SUCCESS You are all set! Just run 'git commit' or 'git commit -m ""' normally, and the wand will appear!
After that, you just write your commit message as usual.
When you commit, commit-wand automatically lints the message; if it violates the rules, it interactively helps you create a new commit message.
If you close the editor displayed by git commit without entering anything, or execute a commit without specifying a message like git commit -m "", you can create a message from scratch.

Installation Guide
Install the package using your preferred package manager.
# If you use npm
npm i -D commit-wand
# Can also be installed with other package managers
For more detailed installation instructions, please see the GitHub repository.
System Requirements
| Item | Environment |
|---|---|
| Node.js Version | v22[2] or higher |
| Supported Package Managers | All |
Development Environment (Tech Stack)
Core Technologies
- TypeScript / Node.js v22
- Package Manager: pnpm
UI Construction
Core Logic/Git Integration
Development Tools
Closing Remarks
I have fixed known bugs as much as possible, but if you encounter any unknown bugs or have feature requests, issues and PRs are always welcome.
Development Backstory
- The default regular expression of @commitlint/parse didn't properly recognize the breaking change marker (
!) in the header- ⇒ Resolved by providing a custom regular expression
- Had some trouble publishing the npm package 🤔
Thank you for reading this far.
This tool is highly recommended for anyone who wants to make the daily task of writing commit messages a little easier.
npm i -D commit-wand
npx cw init
Please give this magic that lets you easily create commit messages with just two commands a try.
-
A style of rapidly generating and modifying software by giving instructions to AI using natural language. ↩︎
-
The recommended version is v22. It also works with v23 or higher, but in that case, we have confirmed an issue where canceling the prompt midway (Ctrl+C) is not processed as a SIGINT event, resulting in an error. However, this has no major impact. If you encounter any problems, please report them via Issues etc. — your feedback would be greatly appreciated. ↩︎
Discussion