Wallace FreitasClearly written commit messages are essential to keeping a project history organized and intelligible. Adhering to recommended methods for crafting quality commits can greatly enhance teamwork and code quality, regardless of the scale of your project—it could be a tiny personal project or a massive team-based application. This post will discuss how to make good commits and how your development process can benefit from them.
Why Good Commit Messages Matter
✓ Clarity: They provide a clear description of what changes were made and why.
✓ Collaboration: They make it easier for team members to understand the changes and the reasoning behind them.
✓ History: They create a detailed and understandable project history, making it easier to trace bugs, review code, and understand the evolution of the project.
✓ Reverts: They simplify the process of reverting specific changes if something goes wrong.
1. Keep Commits Small and Focused
Remaining committed to a single goal and making tiny commitments is one of the most crucial habits. Every commit ought to indicate a unique, rational modification to the codebase. This makes it simpler to check modifications and find the root of problems in the event that something goes wrong.
Practice: Make Atomic Commits
↳ One Change per Commit: Avoid bundling multiple changes into a single commit. For example, if you're fixing a bug and also refactoring code, these should be two separate commits.
↳ Frequent Commits: Commit frequently to ensure that each change is well-documented and easy to understand.
Example:
Commit 1: "Fix off-by-one error in pagination logic."
Commit 2: "Refactor user authentication module to improve readability."
2. Write Descriptive Commit Messages
A good commit message is clear and descriptive. It should convey what was changed and, if necessary, why the change was made. This helps others (and your future self) understand the purpose of the commit without having to read through the code.
Practice: Follow the Conventional Commit Format
↳ A widely accepted format for writing commit messages is:
Header: A short summary of the change (50 characters or less).
Body (Optional): A more detailed explanation of the change, why it was made, and any potential side effects.
Footer (Optional): Additional information, such as references to issue trackers, links, or notes on breaking changes.
Example:
feat: add user login functionality
This commit adds the ability for users to log in to the system. The
authentication module was updated to handle login requests and generate
JWT tokens.
Fixes #42
3. Use Imperative Mood in Commit Messages
When writing the header of a commit message, it's a good practice to use the imperative mood. This style describes what the commit does, rather than what you did, and it aligns with how commands are typically phrased.
Practice: Start Commit Messages with an Action Verb
✅ Do: "Fix bug in payment processing"
❌ Don't: "Fixed bug in payment processing"
Examples:
"Update README to include installation instructions"
"Remove deprecated API endpoints"
"Refactor authentication service for clarity"
4. Reference Issues and Pull Requests
Referencing issues or pull requests in your commit messages can provide additional context and make it easier to track changes related to specific features or bugs. This is particularly useful in collaborative projects where multiple people might be working on the same issue.
Practice: Include Issue Numbers in the Footer
↳ Format: Use keywords like "Fixes," "Closes," or "Resolves" followed by the issue number.
Examples:
"Fixes #123: Resolve null pointer exception in user profile"
"Closes #45: Add support for multi-language content"
5. Use Branches for Specific Features or Fixes
Working on a specific feature or bug fix in a separate branch ensures that your commits are focused and relevant. Once the feature or fix is complete, you can merge the branch into the main branch with a clear commit history.
Practice: Create Descriptive Branch Names
↳ Feature Branch: feature/user-authentication
↳ Bug Fix Branch: fix/payment-gateway-timeout
↳ Improvement Branch: improvement/ui-refresh
Example Workflow:
Create a branch: git checkout -b feature/user-authentication
Make and commit changes.
Push to the repository: git push origin feature/user-authentication
Open a pull request to merge the branch into the main branch.
6. Avoid Committing Generated Files
Generated files, such as compiled binaries or minified JavaScript files, should typically be excluded from commits. These files can clutter the commit history and make it harder to review changes. Instead, add them to your .gitignore file to prevent them from being tracked.
Practice: Update Your .gitignore
↳ Ensure that your .gitignore file includes entries for generated files and directories that don't need to be versioned.
Example .gitignore:
# Node.js dependencies
node_modules/
# Compiled JavaScript
dist/
build/
# Logs
*.log
7. Review Commits Before Pushing
Before pushing your commits to the repository, take a moment to review them. This ensures that your commit history is clean, your messages are descriptive, and that you've followed best practices.
Practice: Use git log and git diff
↳ git log: Review your commit history to ensure that your commits are well-structured and logically organized.
↳ git diff: Review the changes you've made before committing to catch any mistakes or unintended modifications.
Example:
git log --oneline
git diff HEAD^
Conclusion
The ability to write quality commits greatly improves both the productivity of your team and the maintainability of your codebase. You may produce a clear, intelligible, and helpful project history by adhering to these best practices, writing descriptive messages, utilizing the imperative mood, mentioning pertinent issues, and keeping commits modest and focused.
Effective contributions promote improved teamwork, simpler code reviews, and an all-around more maintainable project. Whether you're working alone or in a group, implementing these techniques will improve the efficiency of your version control procedure and the outcome of your project.
