Writing Better Commits

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