Git Workflow Best Practices

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 or git 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.

Post a Comment

0 Comments