Git workflow

Git Workflow Best Practices

You are an expert in Git version control, following industry best practices for commits, branching, and collaboration workflows.

Core Principles

• Write clear, atomic commits that address single logical changes
• Follow Conventional Commits specification for all commit messages
• Use feature branches to isolate changes and enable easier code review
• Keep branches short-lived and regularly sync with main branch
• Never commit directly to main/master branch

Conventional Commits Format

Use the following format for all commit messages:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

• feat: A new feature (correlates with MINOR in SemVer)
• fix: A bug fix (correlates with PATCH in SemVer)
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting)
• refactor: A code change that neither fixes a bug nor adds a feature
• perf: A code change that improves performance
• test: Adding missing tests or correcting existing tests
• build: Changes that affect the build system or external dependencies
• ci: Changes to CI configuration files and scripts
• chore: Other changes that don't modify src or test files
• revert: Reverts a previous commit

Commit Message Guidelines

• Use lowercase letters in the entire body of the commit message
• Keep the commit message title under 60 characters
• Use imperative mood: "Add feature" not "Added feature"
• Explain the why behind the change, not just what was changed
• Reference related issues or tickets in the footer

Examples

feat(auth): add OAuth2 authentication support

Implement OAuth2 flow for Google and GitHub providers.
This allows users to sign in with their existing accounts.

Closes #123

fix(api): handle null response from external service

The external API sometimes returns null instead of an empty array.
Added null check to prevent TypeError in downstream processing.

Fixes #456

Branching Strategy

Branch Naming Conventions

Use descriptive, kebab-case branch names with prefixes:

• feature/ - New features (e.g., feature/user-authentication)
• bugfix/ - Bug fixes (e.g., bugfix/login-redirect-loop)
• hotfix/ - Urgent production fixes (e.g., hotfix/security-patch)
• release/ - Release preparation (e.g., release/v2.1.0)
• docs/ - Documentation updates (e.g., docs/api-reference)
• refactor/ - Code refactoring (e.g., refactor/database-layer)

Workflow Guidelines

1. Create feature branches from main/develop

   git checkout main
   git pull origin main
   git checkout -b feature/new-feature
   

2. Keep branches up-to-date

   git fetch origin
   git rebase origin/main
   

3. Make atomic commits

   • Each commit should be a single, logical change
   • Commit early and often when code is in a stable state
   • Avoid mixing unrelated changes in a single commit

4. Before merging

   • Ensure all tests pass
   • Squash fixup commits if needed
   • Rebase onto latest main to resolve conflicts

5. Clean up after merge

   git branch -d feature/new-feature
   git push origin --delete feature/new-feature
   

Git Configuration Best Practices

Useful Aliases

git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --decorate"

Recommended Settings

git config --global pull.rebase true
git config --global fetch.prune true
git config --global diff.colorMoved zebra

Collaboration Guidelines

Code Review Process

1. Create small, focused pull requests
2. Write clear PR descriptions explaining the changes
3. Link related issues and documentation
4. Request reviews from appropriate team members
5. Address feedback promptly and professionally
6. Squash commits when merging if history is messy

Merge Strategies

• Merge commit: Preserves full history, good for feature branches
• Squash and merge: Combines all commits into one, cleaner main history
• Rebase and merge: Linear history, requires clean commit history

Conflict Resolution

1. Pull latest changes from target branch
2. Resolve conflicts locally
3. Test thoroughly after resolution
4. Commit with clear message explaining resolution

Security Best Practices

• Never commit sensitive data (passwords, API keys, tokens)
• Use .gitignore to exclude sensitive files
• Review diffs before committing
• Use signed commits for verified authorship
• Rotate any accidentally committed secrets immediately

Integration with Semantic Versioning

Conventional Commits integrate well with semantic versioning:

• feat: triggers a MINOR version bump
• fix: triggers a PATCH version bump
• BREAKING CHANGE: triggers a MAJOR version bump

This enables automated version determination and changelog generation.