Writing Better Commits

Writing better commits with the better-commits CLI

Published in

ITNEXT

3 min readMar 12, 2023

Recently I wrote a lightweight open-source CLI for writing better commits. It helps you follow the Conventional Commit Guideline, while being flexible and configurable.

Source Code on Github

Highly flexible configuration
Easy install with sane defaults
Infers ticket/issue and type from branch
Git status & interactive git add
Color preview and confirm

But, why write better commits?

A good commit history helps others ( and the future you) better understand your code and how it came to be that way.

For myself, writing a good commit is like writing good notes. I want to write it in a way that when I look back I can understand why and how I made the decisions I did.

better-commits and the Conventional Commit Guidelines, provide a way to format commits consistently. Doing so can result in some cool side-effects, aside from making your commits easier to read and understand.

Automate versioning from commits with semantic release
Automate change logs from commits
Automate build processes based on commit
Auto reference & close issues to PRs
Auto populate the title and body of Github PRs and merge commits.

Examples Commits

Below are a few example commits. These follow the Conventional Commit Guidelines, and may provide some inspiration for writing better commits.

New feature

The type of change, scope, github issue, and high-level description are all easily visible.
The body explains what changed. Including the property name to enable.
The ticket is referenced in the footer, which connects the Github issue with its corresponding pull request.

feat(tools): #3 infer ticket/issue from branch

If commit_type.infer_value_from_branch is enabled,
will attempt to infer ticket/issue from branch name.
Updated documentation with details.

Closes: #3

Breaking changes

The breaking change is signified by:
An exclamation point after the type and before the colon, brings attention to the commit
The “BREAKING CHANGE” label explains what the breaking change was.
This could be extended to include an optional body. Explaining a path to migrate from Node 6 and resolve the breaking change.

chore!: drop Node 6 from testing matrix 

BREAKING CHANGE: dropping Node 6 which hits end of life in April

Quick adjustment to documentation

Technically a valid conventional commit. Many of the items in the specification are optional or shouldn’t be forced if not applicable.

docs: Fix tabbing in defaults section of readme

Conclusion

At my job as a software engineer, I’ve always followed branch and git commit guidelines. However, I’ve ignored maintaining a good commit history in my personal close-sourced projects.

As those projects have grown. I’ve realized that the small increased effort upfront, to write a good commit message, is worth the improved developer experience (imo). — And so I created better-commits. To be able to quickly and easily follow good practices across all of my projects.

If you enjoy using the better-commits CLI, ⭐️ star it on github, so I feel like the special little snowflake my mother tells me I am.

Originally published at https://blog.flotes.app.

📺 Check out my Lofi Pomodoro Study Videos on Youtube

☁️ Markdown Note-taking with Flashcard Features — Flotes is how I take notes and efficiently study multiple topics at a time. Try the demo (no login required) or sign up for free.

Writing Better Commits