A well-crafted Git commit message is essential for communicating the context behind changes to both current and future developers, including your future self. Clear, concise commit messages make it easier to track the project’s evolution, understand decisions, and resolve issues later on. While small commits may seem insignificant at the moment, they build the project’s history, and every developer contributes to that story.
AI tools (like in GitKraken) have started making writing message faster, and more verbose, but they’re more focused on “what happened” rather than “why did I make the changes to our code base”…
Best Practices for Commit Messages
To standardize our approach, I advice putting the best practices outlined in the project’s readme.md. This includes using descriptive commit messages that clearly communicate the purpose of a change. Avoid vague messages like “fixed bug” or “updated files.” Instead, provide context: “Fix homepage carousel image overflow on mobile devices” or “Update contact form to include file upload option”.
By being explicit in your commit messages, you save others (and yourself) from having to dig through code to understand what was changed and why. Good commit messages are especially valuable during code reviews, debugging, and when auditing project history.
Commit Message Format
We recommend structuring commit messages with the following format:
- Subject line (max 50 characters): A concise description of the change, written in the imperative mood (e.g., “Add new social media buttons”).
- Blank line: Leave a blank line between the subject line and the body of the message for clarity.
- Message body (wrap at 72 characters): Provide more detailed context about the change, including why the change was made, any potential side effects, and references to related tickets or issues (if applicable).
Example
Add feature to upload profile images
- Enable users to upload and edit their profile pictures
- Images are cropped and resized on upload for consistency
- Update user model to store profile image URLs
- Closes issue #42Ensuring compliance with expected format by Using a Commit Message Template
To ensure you and your team adhere to these best practices consistently, create a commit message template. This can serve as a reminder to include key information, even for smaller commits.
For example, you can move this template to a convenient location on your local machine. Personally, I keep mine in the root of my “local sites” folder. Set up your global Git configuration to reference this template by running:
git config --global commit.template ../../../gitmessage.txtThis way, every time you start a commit, Git will automatically populate the template, ensuring you don’t forget to include vital information. Using a template ensures consistent, meaningful commit messages across the entire team.
This approach not only improves communication and collaboration but also ensures a clean and navigable project history
Here’s my gitmessage.txt file
Replace this title (<- imperative), <= 50 chars, answers "WHAT" no period
Keep the blank line above but replace this line and below
with your body message explaining *why*, *what* (not *how*).
No more than 100 chars. Make sure to include a note about WHY
a particular solution was chosen.
#### "type" must be one of the following mentioned below!
* `build`: Build related changes (eg: npm related/ adding external dependencies)
* `chore`: A code change that external user won't see (eg: change to .gitignore file or .prettierrc file)
* `feat`: A new feature
* `fix`: A bug fix
* `docs`: Documentation related changes
* `refactor`: A code that neither fix bug nor adds a feature. (eg: You can use this when there is semantic changes like renaming a variable/ function name)
* `perf`: A code that improves performance
* `style`: A code that is related to styling
* `test`: Adding new test or making changes to existing test
* `update`: Software update to plugins, unmodified parent theme, or WordPress core