Let’s be honest: we’ve all been there. It’s 5:00 PM on a Friday, your code finally works, you just want to log off, and your commit message looks like this:
git commit -m "update"
Now, imagine returning to that same repository after six months or collaborating with a team of ten engineers on a large-scale project. That single word tells nobody nothing. It hides context, breaks Git history archaeology, and makes debugging a nightmare.
Writing great commit messages isn't just about being neat—it's an act of respect for your future self and your teammates. Here is your ultimate guide to mastering Git commits for large teams, long-dormant projects, and everything in between.
The Golden Rules of Professional Git Commits
Before looking at formats, keep these core principles in mind every time you stage your code:
Atomic Commits: One commit should represent one logical change. Don't mix a bug fix, a refactoring session, and a new feature into one single commit.
Write in the Imperative Mood: Phrase your message as a command (e.g., Add payment gateway, not Added payment gateway). Think of it as: If applied, this commit will...
Keep Titles Short: Aim for under 50 characters for the commit title. If you need to explain more, use a blank line and add a detailed body.
Never Use Vague Words: Ban filler words like update, fix, stuff, or changes. Be specific about what changed and why.
Conventional Commits
Type: A prefix categorizing the intent of the change.
feat: A new feature for the user.
fix: A bug fix for the user.
docs: Changes strictly to documentation.
style: Formatting, missing semi-colons, or white-space changes (no logic changes).
refactor: Restructuring code without changing behavior or fixing bugs.
perf: Code changes that improve performance.
test: Adding or correcting tests.
build: Changes modifying build systems or external dependencies.
ci: Changes to CI configuration files and scripts.
chore: Routine database updates, .gitignore alterations, or auxiliary tools
Real-World Scenarios
1. Working in a Large Team Project
2. Returning to an Old Project After Months
When you open an abandoned codebase months later, titles alone aren't enough; you need context on why choices were made.
Top comments (0)