name	git-workflow
description	Git workflow best practices and patterns. Use this skill when working with git operations, creating commits, managing branches, handling pull requests, or establishing team git workflows. Provides guidance on commit messages, branching strategies, and collaboration patterns.

Git Workflow

Overview

This skill provides comprehensive git workflow best practices, branching strategies, and collaboration patterns. Use it to ensure consistent, professional git usage across your projects.

When to Use This Skill

Creating commits with proper messages
Establishing branching strategies (Git Flow, GitHub Flow, Trunk-Based)
Handling pull requests and code reviews
Managing releases and hotfixes
Resolving merge conflicts
Setting up git hooks and automation

Core Workflows

Commit Message Guidelines

Follow the Conventional Commits specification for clear, semantic commit messages:

Format:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Formatting, missing semicolons, etc.
refactor: Code restructuring without behavior changes
perf: Performance improvements
test: Adding or updating tests
chore: Build process, dependencies, tooling
ci: CI/CD pipeline changes

Examples:

feat(auth): add JWT token refresh mechanism

Implement automatic token refresh before expiration.
Tokens are refreshed 5 minutes before expiry.

Closes #123

fix(api): handle null responses in user service

Add defensive null checks to prevent NPE when
external API returns unexpected null values.

Fixes #456

Branching Strategies

Git Flow (Traditional)

Best for: Scheduled releases, multiple version support

Branches:

main: Production-ready code
develop: Integration branch for features
feature/*: New features
release/*: Release preparation
hotfix/*: Emergency production fixes

Workflow:

# Start new feature
git checkout develop
git checkout -b feature/user-authentication

# Finish feature
git checkout develop
git merge feature/user-authentication
git branch -d feature/user-authentication

# Create release
git checkout -b release/1.2.0
# Bump version, final testing
git checkout main
git merge release/1.2.0
git tag -a v1.2.0 -m "Release 1.2.0"
git checkout develop
git merge release/1.2.0

GitHub Flow (Simplified)

Best for: Continuous deployment, web applications

Branches:

main: Always deployable
feature/*: All changes

Workflow:

# Start work
git checkout -b feature/add-dark-mode

# Make changes, commit often
git commit -m "feat(ui): add dark mode toggle"

# Push and create PR
git push origin feature/add-dark-mode
# Create pull request on GitHub
# After review and CI passes, merge to main
# Deploy from main

Trunk-Based Development

Best for: High-frequency releases, mature CI/CD

Key principles:

All work on main or very short-lived feature branches (<1 day)
Feature flags for incomplete features
Rigorous automated testing

Pull Request Best Practices

PR Description Template:

## Summary
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing Done
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed

## Screenshots (if applicable)

## Related Issues
Closes #123

Review Checklist:

Code follows project conventions
Tests cover new functionality
Documentation is updated
No sensitive data committed
CI/CD pipeline passes
Performance impact considered

Handling Merge Conflicts

Process:

# Update your branch with latest main
git checkout feature/my-feature
git fetch origin
git merge origin/main

# If conflicts occur
# 1. Open conflicted files
# 2. Look for conflict markers: <<<<<<< ======= >>>>>>>
# 3. Resolve manually, keeping appropriate changes
# 4. Remove conflict markers
# 5. Test the resolved code
git add <resolved-files>
git commit -m "chore: resolve merge conflicts with main"

Conflict Resolution Tips:

Communicate with the other developer if unsure
Prefer rebasing for cleaner history (if branch not shared)
Use git mergetool for complex conflicts
Always test after resolution

Git Hooks and Automation

Common hooks to consider:

pre-commit:

# Run linters, formatters
npm run lint
npm run format

# Run fast tests
npm run test:unit

commit-msg:

# Validate commit message format
# Ensure conventional commits compliance

pre-push:

# Run full test suite
npm run test

# Run build
npm run build

Advanced Patterns

Rebasing vs Merging

Use Rebase When:

Working on personal feature branch
Want linear history
Need to incorporate upstream changes

git fetch origin
git rebase origin/main

Use Merge When:

Working on shared branches
Want to preserve complete history
Merging pull requests

git merge origin/main

Cherry-Picking

Use to apply specific commits to another branch:

# Find commit hash
git log

# Apply to current branch
git cherry-pick <commit-hash>

Interactive Rebase

Clean up commit history before pushing:

# Rebase last 3 commits
git rebase -i HEAD~3

# Options: pick, reword, squash, fixup, drop

Common Scenarios

Undo Last Commit (Not Pushed)

git reset --soft HEAD~1  # Keep changes staged
git reset HEAD~1         # Keep changes unstaged
git reset --hard HEAD~1  # Discard changes

Undo Pushed Commit

# Create new commit that reverses changes
git revert <commit-hash>
git push origin main

Stash Changes

# Save work in progress
git stash save "WIP: feature description"

# List stashes
git stash list

# Apply stash
git stash apply stash@{0}

# Apply and remove
git stash pop

Update Commit Message

# Last commit (not pushed)
git commit --amend -m "new message"

# Older commit
git rebase -i HEAD~n  # Use 'reword'

Resources

references/

This skill includes reference documentation for deeper dives:

git-best-practices.md: Comprehensive git guidelines
branching-models.md: Detailed branching strategy comparisons
conflict-resolution.md: Advanced merge conflict patterns

Quick Reference

Daily Commands:

git status                    # Check status
git add <file>               # Stage file
git commit -m "message"      # Commit with message
git push origin <branch>     # Push to remote
git pull origin <branch>     # Pull from remote
git checkout -b <branch>     # Create and switch branch
git merge <branch>           # Merge branch

Inspection:

git log --oneline --graph    # Visual commit history
git diff                     # See unstaged changes
git diff --staged            # See staged changes
git show <commit>            # Show commit details
git blame <file>             # See who changed each line

Cleanup:

git branch -d <branch>       # Delete local branch
git push origin :<branch>    # Delete remote branch
git clean -fd                # Remove untracked files
git gc                       # Garbage collection

git-workflow

Install Skill

SKILL.md