Git is the backbone of modern software development, enabling teams to collaborate on codebases reliably, track changes over time, and roll back mistakes when they occur. But while most teams use Git, not all commits, the basic unit of change, are created equal. A commit can be “good” or “bad,” dramatically affecting team productivity, code quality, and long-term maintainability.
This guide explains what makes a good commit versus a bad commit, illustrated with real Git examples, best practices, tools, and workflows. We’ll also cover how to audit commit quality and build healthy commit discipline in your team.
Why Commit Quality Matters
Quality Git commits matter for developers, teams, and organizations because commits are:
The official history of your codebase,
A source of truth for debugging and auditing changes,
A baseline for automated tools (CI/CD, linters, deploys),
The unit of teamwork for merges and pull requests.
Poor commit practices lead to long code reviews, brittle releases, merge conflicts, technical debt, and wasted time.
What Is a Commit in Git?
A commit in Git represents a snapshot of your project at a point in time. It includes:
A unique ID (SHA),
Author and timestamp,
A commit message,
A tree of file changes.
When done right, each commit explains why a change was made, not just what was changed.
From the official Git documentation:
“The commit command creates a new commit containing the current contents of the index and a message from the user describing the changes.”
Source: Git Book , https://git-scm.com/book/en/v2
Good Commit Characteristics
A “good commit” has:
Logical scope: Each commit changes only one thing (one feature, one bug fix).
Clean diffs: Code changes are readable, minimal, and relevant.
Clear messages: The commit message explains why, not just what.
Test coverage: The commit includes added or updated tests where applicable.
Reversibility: Each commit stands alone and can be rolled back safely.
Let’s look at each in more detail.
- Logical Scope
Commits should be small and focused.
Example of a Good Logical Scope
Instead of:
commit 3f9a7b
- Added full user management feature
- Updated CI config
- Changed CSS framework
Split into multiple commits:
commit f41a2c3
feat: Add user registration API
commit a93c8d2
ci: Update CI pipeline to include integration tests
commit c3d1e4f
style: Replace Bootstrap with Tailwind CSS
This practice makes it easier to review, revert, and understand context.
- Clean Diffs
"Clean diffs" means that changed lines reflect intent, not noise like formatting changes, debug statements, or unrelated edits.
Example of Clean vs. Messy Diff
Messy commit:
- console.log("debug user id", userId)
- // Removed debug code
Cleaner alternative:
Keep debug logs out of commits entirely. If needed, use conditional debug flags or logging frameworks.
- Clear Messages
Commit messages should follow a consistent style. A popular approach is the Conventional Commits standard:
Format: ():
Examples:
feat(auth): add JWT token refresh endpoint
fix(ui): correct button alignment in settings page
refactor(utils): simplify date parsing logic
Use imperative voice like a command:
Fix typo
Add tests
Remove redundant code
Useful references:
Conventional Commits , https://www.conventionalcommits.org
Angular Commit Message Guidelines , https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commit
- Test Coverage
A good commit should include or update tests that validate changes:
Example of adding a unit test
git add tests/userService.test.js
git commit -m "test(user): add tests for user login failure states"
If you change behavior without tests, future changes may regress functionality.
- Reversibility
Each commit should be able to stand alone , meaning that if you revert it, the system still builds and runs.
Bad Practice:
Committing half of a feature across multiple unrelated commits:
commit a1 Add half of new API
commit b2 Break tests by updating config
This makes it hard to revert without affecting other parts.
Bad Commit Characteristics
A “bad commit” typically has:
Unrelated changes bundled together,
Non-descriptive messages like “fix” or “update”,
Large size with hundreds of changed lines,
No tests,
WIP (Work In Progress) commits merged into main branches.
Let’s explore examples.
- Large, Unfocused Commits
Bad commit example:
commit e8b99a
- Updated login API
- Refactored UI components
- Fixed typo in README
This mixes multiple logical concerns, a major anti-pattern.
Why it’s bad:
Hard to review,
Hard to revert,
Muddies history.
- Poor Messages
Examples of insufficient commit messages:
commit 91a3f4
"fix stuff"
commit 4b2d1c
"changes"
These messages don’t provide context.
Better:
fix(auth): handle missing JWT token scenario
- Including Temporary Debug Code
Example of a bad diff:
- console.log("check user id:", userId)
Debug code should be removed before commit.
- Committing Generated Files
Avoid committing files that are:
Machine generated (e.g., build output),
IDE specific (e.g., .vscode/ folders),
Binary libraries you don’t own.
Use .gitignore:
Node
node_modules/
Build output
dist/
Commit Message Templates
Using a commit message template ensures consistent structure:
():
Example:
feat(auth): add OAuth support
Added support for Google and GitHub OAuth flows.
Updated documentation in /docs/auth.md
Closes #321
Git Workflow Best Practices
Feature Branches
Use feature branches:
git checkout -b feature/user-profiles
This isolates work until ready to merge.
Pull Requests (PRs) and Reviews
Never push directly to main or production branches. Always require reviews.
Example PR title:
[FEATURE] Add cascading dropdown for countries -> cities
CI/CD Integration
Build tools (GitHub Actions, GitLab CI, Jenkins) can run tests on each commit.
Sample GitHub Actions step:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run tests
run: npm test
Tools to Improve Commit Quality
Linters
ESLint for JavaScript
RuboCop for Ruby
Pylint for Python
These help avoid commit noise (formatting, syntax errors).
Pre-commit Hooks
Use Husky or Git hooks to enforce standards:
npx husky add .husky/pre-commit "npm test"
This prevents commits that break tests.
Rewriting History, When Is It Okay?
Interactive rebase (git rebase -i) can clean up messy local commits before pushing:
git rebase -i HEAD~4
Be cautious: never rebase public history others depend on.
Real-World Commit Examples (Good vs. Bad)
Bad Commit (Dumping Work)
commit 2bf3a4
misc changes
The title is vague, and commit contains unrelated content:
- fixed button
- added navbar
- updated CSS framework
Analysis: Too many independent changes.
Good Commit (Focused)
feat(ui): improve navbar responsiveness
Updated navbar layout and CSS to support mobile widths
down to 320px. Added toggle button for small screens.
Closes #242
Automating Quality
Tools like GitCop, Commitlint, and Semantic Release enforce rules.
Example Commitlint rule:
{
"rules": {
"header-max-length": [2, "always", 72],
"type-enum": [2, "always", ["feat", "fix", "docs", "style", "refactor", "test"]]
}
}
This ensures commit headers are descriptive and limited to 72 characters.
How to Audit Commits
Run the following to see commit history:
git log --oneline --graph --decorate
Use visual tools like GitKraken, SourceTree, or GitHub insights to inspect patterns.
Commit Metrics Teams Should Track
Average commit size (lines changed),
Number of PRs per week,
Lead time from commit to merge,
Percentage of commits with tests.
High quality usually correlates with lower bug rates.
Integrating with Jira, Trello, or GitHub Projects
Include issue IDs in commits:
feat(profile): add upload avatar (JIRA-123)
This links commit to project tickets and improves traceability.
Common Mistakes and How to Avoid Them
MistakeHow to FixVague commit messagesUse Conventional CommitsBig commitsCommit smaller, focused changesNo testsAdd tests before commitIncluding debug codeClean code before stagingCommitting build filesUse .gitignore
Frequently Asked Questions (FAQ)
Q: Should I amend commits?
A: Only on local branches before pushing.
Q: What size should a commit be?
A: As small as possible while still meaningful.
Q: How often should I commit?
A: Commit after each logical unit of work, not necessarily after every line.
Conclusion
Good commit practices are a foundational competency in software development, and going from a bad commit culture to a good one yields measurable gains in quality, velocity, and team morale.
Key Takeaways:
Write focused commits,
Use clear, structured messages,
Include tests and meaningful diffs,
Automate where possible.
If you invest in commit quality, your codebase becomes easier to maintain, review, and extend.
External References
Below are recommended authoritative resources to learn more about Git best practices:
Official Git documentation https://git-scm.com/doc
Pro Git book (free online) https://git-scm.com/book/en/v2
Conventional Commits specification https://www.conventionalcommits.org
Atlassian Git tutorials https://www.atlassian.com/git
How Nile Bits Can Help
At Nile Bits, we specialize in helping teams build high-quality software with professional Git workflows, CI/CD integration, and team training:
Our Services Include:
Git Workflow Design and Audit: We help you establish and enforce enterprise-grade Git commit standards.
DevOps & CI/CD Setup: From GitHub Actions to Jenkins pipelines, we automate your testing and deployments.
Team Training and Onboarding: Workshops on Git best practices, branching strategies, and collaboration.
If your team struggles with commit discipline, long code reviews, or chaotic releases, Nile Bits can help you stabilize and scale your development processes.
Contact us today to learn how we can elevate your software engineering practices.
Top comments (0)