Git Workflow Best Practices

This skill provides guidance for effective Git usage, commit conventions, and team collaboration patterns.

When This Skill Applies

• Writing commit messages
• Creating or managing branches
• Resolving merge conflicts
• Setting up team Git workflows
• Reviewing pull requests

Commit Message Conventions

Follow the Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

Examples

feat(auth): add OAuth2 login support

Implements Google and GitHub OAuth2 providers.
Users can now link social accounts to their profile.

Closes #123

fix(api): handle null response from payment gateway

The payment API occasionally returns null instead of
an error object. Added defensive check to prevent crash.

Commit Message Rules

• Use imperative mood: "add feature" not "added feature"
• Keep subject line under 50 characters
• Capitalize the subject line
• Don't end subject with a period
• Separate subject from body with blank line
• Wrap body at 72 characters
• Explain what and why, not how

Branching Strategies

GitHub Flow (Recommended for most teams)

Simple and effective:

1. main is always deployable
2. Create feature branches from main
3. Open PR when ready for review
4. Merge to main after approval
5. Deploy from main

Branch Naming

<type>/<ticket-id>-<short-description>

Examples:

• feat/AUTH-123-oauth-login
• fix/BUG-456-null-pointer-crash
• refactor/TECH-789-extract-utils

Pull Request Best Practices

Creating PRs

• Write a clear title summarizing the change
• Include context: what, why, and how to test
• Link related issues
• Keep PRs focused and reasonably sized (<400 lines ideal)
• Add screenshots for UI changes

Reviewing PRs

• Review promptly (aim for <24 hours)
• Be constructive and specific
• Approve when "good enough"—don't block on style preferences
• Use suggestions for small changes

Conflict Resolution

When resolving merge conflicts:

1. Understand both sides of the conflict
2. Communicate with the other author if unclear
3. Test the merged result
4. Don't blindly accept "ours" or "theirs"

Git Hygiene

Do

• Commit early and often (can squash later)
• Write meaningful commit messages
• Keep commits atomic (one logical change)
• Pull/rebase frequently to stay current
• Use .gitignore for generated files

Don't

• Commit secrets, credentials, or API keys
• Force push to shared branches
• Commit large binary files
• Leave WIP commits in final PRs
• Commit broken code to main

Useful Commands

# Interactive rebase to clean up commits
git rebase -i HEAD~5

# Amend the last commit
git commit --amend

# Stash changes temporarily
git stash push -m "description"

# Cherry-pick a specific commit
git cherry-pick <commit-hash>

# View commit history as graph
git log --oneline --graph --all