Commit Best Practices: Crafting a Clean History
A well-maintained commit history is like a good story - it should be clear, logical, and easy to follow.
The Art of Commit Messages
Good Commit Message Structure:
Summarize changes in 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about
72 characters. The blank line separating the summary from the
body is critical.
- Bullet points are okay too
- Typically a hyphen or asterisk is used for the bullet
Commit Guidelines
- Atomic commits: Each commit should represent a single logical change
- Frequent commits: Small, focused commits are easier to review and revert
- Separate concerns: Don't mix formatting changes with functional changes
- Use present tense: "Add feature" not "Added feature"
Tools to Help
# Review changes before committing
git add -p
# Amend last commit (before pushing)
git commit --amend
# Rebase interactively to clean up
git rebase -i HEAD~5
Code Review Process: Quality Through Collaboration
Effective code reviews catch bugs early and spread knowledge across the team.
Pull Request Best Practices
Creating Effective PRs:
- Small and focused: Limit to 200-400 lines of code when possible
- Clear description: Explain what and why (screenshots for UI changes)
- Linked issues: Reference relevant tickets (e.g., "Fixes #123")
- Ready for review: Ensure tests pass and CI builds succeed
Reviewing Effectively:
- 24-hour rule: Aim to review within one business day
- Constructive feedback: Focus on code, not coder
- Checklist:
- Does the code work as intended?
- Is it readable and maintainable?
- Are there appropriate tests?
- Does it follow team standards?
GitHub/GitLab Setup
# Sample .github/pull_request_template.md
## Description
What does this PR change? Why?
## Related Issues
Fixes #123, Related to #456
## Checklist
- [ ] Tests added
- [ ] Documentation updated
- [ ] Ready for review
Pro Tip: Use protected branches to enforce:
- Required approvals (typically 2)
- Required status checks (CI, linting)
- Linear history (no merge commits)
Handling Conflicts: Prevention and Resolution
Merge conflicts are inevitable, but good practices minimize their frequency and impact.
Conflict Prevention
- Small, frequent merges: The less code, the fewer conflicts
- Team communication: Coordinate on who's working on what files
- Regular updates: Rebase/merge from main branch often
- Clear architecture: Reduce file contention through good separation
Conflict Resolution Workflow
# When you encounter a conflict during merge/rebase:
1. Identify conflicting files (git status)
2. Open each file and look for conflict markers:
<<<<<<< HEAD
your changes
=======
incoming changes
>>>>>>> branch-name
3. Edit to keep the correct changes (or a combination)
4. Remove conflict markers
5. Add resolved files: git add filename
6. Continue the operation: git rebase --continue (or git commit)
Advanced Tools
- Visual diff tools:
git mergetool
(configure VS Code, Beyond Compare, etc.) - Partial resolution:
git checkout --ours/--theirs filename
to pick one side - Abort options:
git rebase --abort
orgit merge --abort
to start over
Warning: Never commit conflict markers! Always verify resolved files compile and tests pass.
Building a Smooth Git Workflow
Implementing these practices will lead to:
- Readable history that helps with debugging and onboarding
- Effective reviews that improve code quality and share knowledge
- Minimal conflicts that are easier to resolve when they occur
Remember: Good workflows balance individual productivity with team collaboration. Regularly revisit and refine your process as your team grows.
0 Comments