Commit Best Practices
Last Updated: January 3, 2026
Understanding how to create effective commits in Git is crucial for maintaining a clean and manageable project history. Well-crafted commits not only make it easier to understand the evolution of a codebase, but they also facilitate collaboration among team members. In this chapter, we'll explore best practices for writing commits that enhance clarity, context, and collaboration.
Meaningful Commit Messages
A commit message serves as a log entry that describes changes made in a project. A good message should explain why the changes were made, not just what was changed. Here are some best practices for writing effective commit messages:
Structure of a Commit Message
A well-structured commit message typically consists of three parts: a summary line, a body, and a footer.
- Summary Line: This should be a concise description of the change, limited to about 50 characters. Use the imperative mood (“fix bug” instead of “fixed bug”).
- Body: This section offers a more detailed explanation of the changes and the reasoning behind them. Aim for around 72 characters per line. Use this space to describe:
- The motivation for the change
- Any side effects or potential issues
- References to issues or tickets (e.g., “Fixes #123”)
- Footer: If applicable, you can include references to related issues, breaking changes, or metadata.
Example
Commit Granularity
The size and scope of a commit are critical. Strive for atomic commits that encapsulate a single logical change. This makes it easier to review changes, revert specific features, or identify the source of bugs.
Why Atomic Commits Matter
Atomic commits enhance code review efficiency. When a commit contains multiple unrelated changes, it becomes difficult to understand the intent and context. This can confuse reviewers and complicate the process of bisecting commits to find the source of a bug.
Guidelines for Atomic Commits
- Each commit should represent one complete, logical change.
- Avoid combining multiple features or fixes in a single commit.
- If you find a commit has grown too large, consider splitting it into multiple smaller commits.
Example
Instead of a commit combining multiple changes:
You should have three separate commits:
- Fix bug in user login
- Update documentation for user login
- Refactor user login code
Use of Commit Hooks
Git offers hooks that can automate tasks and enforce standards. By leveraging commit hooks, you can validate commit messages, enforce coding standards, or even run tests before allowing a commit.
Setting Up a Commit Hook
To set up a commit message hook, create a file named commit-msg in the .git/hooks/ directory. Here’s a simple example that ensures commit messages follow a specific format.
Example Hook Script
Make the script executable:
This hook checks that every commit message begins with a JIRA ticket reference. It helps ensure that messages are informative and contextually relevant.
Consider using tools like husky to manage Git hooks more conveniently, especially in collaborative projects.
Avoiding WIP Commits
Work-in-progress (WIP) commits can clutter your history and confuse collaborators. While it's tempting to commit frequently for backup, these interim commits can obscure the final product's clarity.
Strategies for Managing WIP
Instead of committing unfinished work, consider using the following strategies:
Stashing: Use git stash to temporarily save changes without committing. This allows you to switch branches or pull updates without losing your current progress.
Feature Branches: Develop new features or fixes in a separate branch. This keeps your main branch clean while you work on changes.
By keeping your main branch free of WIP commits, you maintain a clear and understandable history.
Leveraging Amend and Squash
Sometimes, you may find that a commit needs to be adjusted or combined with others. Git provides commands like git commit --amend and git rebase -i for modifying commit history.
Using git commit --amend
This command allows you to modify the most recent commit. You can change the commit message or add additional changes.
Example
This is useful for quickly correcting mistakes without creating additional commits.
Squashing Commits
During a rebase, you can squash multiple commits into one, which is beneficial for cleaning up commit history before merging.
Example
In the interactive rebase interface, change the word “pick” to “squash” for the commits you want to combine. This results in a single commit that encapsulates the changes from those squashed commits.
Be cautious when amending or squashing commits that have been pushed to a shared repository; it can rewrite history and cause confusion.
Consistent Commit Practices Across Teams
When working in a team, adopting a consistent commit message style and strategy is vital. Establishing team conventions can improve collaboration and maintain clarity in the project's history.
Establishing Guidelines
Create a document that outlines your team's commit message conventions, encompassing:
- Formatting rules (e.g., imperative mood, structure)
- Prefixes for categorizing commits (e.g., feat, fix, docs)
- Guidelines on commit frequency and granularity
Encourage team members to review each other's commits regularly. Code reviews can help maintain these standards and provide an opportunity to discuss best practices.
Now that you understand how to create meaningful and effective commits, you are ready to explore branching strategies. In the next chapter, we will look at how to structure your branches for optimal collaboration and project management.