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**

   ```bash

   git checkout main

   git pull origin main

   git checkout -b feature/new-feature

-

Keep branches up-to-date

git fetch origin

git rebase origin/main

-

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

-

Before merging

• Ensure all tests pass

• Squash fixup commits if needed

• Rebase onto latest main to resolve conflicts

-

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

• Create small, focused pull requests

• Write clear PR descriptions explaining the changes

• Link related issues and documentation

• Request reviews from appropriate team members

• Address feedback promptly and professionally

• 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

• Pull latest changes from target branch

• Resolve conflicts locally

• Test thoroughly after resolution

• 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.