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

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
bash
```
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

bash

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

Git Configuration Best Practices

Useful Aliases

bash

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

bash

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.

git-workflow

NPX Install

Tags

SKILL.md Content

Git Workflow Best Practices

Core Principles

Conventional Commits Format

Commit Types

Commit Message Guidelines

Examples

Branching Strategy

Branch Naming Conventions

Workflow Guidelines

Git Configuration Best Practices

Useful Aliases

Recommended Settings

Collaboration Guidelines

Code Review Process

Merge Strategies

Conflict Resolution

Security Best Practices

Integration with Semantic Versioning