iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
📝

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.
https://www.conventionalcommits.org/en/v1.0.0/

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.
https://github.com/zibasan/commit-wand

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.

https://github.com/zibasan/commit-wand/

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.

脚注
  1. A style of rapidly generating and modifying software by giving instructions to AI using natural language. ↩︎

  2. 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