# Git Workflow

> Git workflow best practices, branch management, semantic commits, and collaboration strategies

- Skill: `lodetomasi/git-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lodetomasi/git-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lodetomasi/git-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: lodetomasi (https://skillmd.com/u/lodetomasi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/lodetomasi/git-workflow

---


# Git Workflow Skill

## Overview
Comprehensive Git workflow skill covering branching strategies, semantic commits, pull request management, conflict resolution, and team collaboration best practices.

## Capabilities

### 1. Branching Strategies
- GitFlow workflow
- GitHub Flow
- Trunk-based development
- Feature branch workflow
- Release management

### 2. Commit Management
- Semantic commit messages
- Conventional commits
- Atomic commits
- Interactive rebasing
- Commit squashing

### 3. Collaboration
- Pull request workflows
- Code review integration
- Conflict resolution
- Fork management
- Team synchronization

### 4. Release Management
- Version tagging
- Changelog generation
- Semantic versioning
- Release branches
- Hotfix workflows

## Branching Strategies

### GitFlow

**Branch Types**:
- `main` - Production-ready code
- `develop` - Integration branch
- `feature/*` - New features
- `release/*` - Release preparation
- `hotfix/*` - Production fixes

**Workflow**:
```bash
# Start new feature
git checkout develop
git checkout -b feature/user-authentication

# Work on feature...
git add .
git commit -m "feat: add login form"

# Complete feature
git checkout develop
git merge --no-ff feature/user-authentication
git branch -d feature/user-authentication

# Prepare release
git checkout -b release/1.2.0 develop
# Bug fixes only...
git checkout main
git merge --no-ff release/1.2.0
git tag -a v1.2.0 -m "Release version 1.2.0"
git checkout develop
git merge --no-ff release/1.2.0
git branch -d release/1.2.0

# Hotfix
git checkout -b hotfix/1.2.1 main
# Fix critical bug...
git checkout main
git merge --no-ff hotfix/1.2.1
git tag -a v1.2.1 -m "Hotfix version 1.2.1"
git checkout develop
git merge --no-ff hotfix/1.2.1
git branch -d hotfix/1.2.1
```

### GitHub Flow

**Simpler workflow for continuous deployment**:

```bash
# Create feature branch from main
git checkout main
git pull origin main
git checkout -b feature/add-search

# Make changes and commit
git add .
git commit -m "feat: implement search functionality"

# Push and create PR
git push -u origin feature/add-search
gh pr create --title "Add search functionality" --body "..."

# After review and CI passes
gh pr merge --squash

# Delete branch
git branch -d feature/add-search
```

### Trunk-Based Development

**For teams with strong CI/CD**:

```bash
# Always work on main (or short-lived branches)
git checkout main
git pull origin main

# Short-lived branch (< 1 day)
git checkout -b improvement/optimize-query

# Small, frequent commits
git add .
git commit -m "perf: optimize user query with indexing"

# Merge quickly
git push origin improvement/optimize-query
# Create PR, get quick review, merge
```

## Semantic Commit Messages

### Conventional Commits Format

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

<body>

<footer>
```

### Types

- **feat**: New feature
- **fix**: Bug fix
- **docs**: Documentation only
- **style**: Code style (formatting, missing semicolons)
- **refactor**: Code change that neither fixes bug nor adds feature
- **perf**: Performance improvement
- **test**: Adding or updating tests
- **chore**: Maintenance (dependencies, build config)
- **ci**: CI/CD changes
- **revert**: Reverting previous commit

### Examples

**Feature**:
```bash
git commit -m "feat(auth): add JWT token authentication

Implement JWT-based authentication system with refresh tokens.
Tokens expire after 15 minutes and can be refreshed using the
/api/auth/refresh endpoint.

Closes #123"
```

**Bug Fix**:
```bash
git commit -m "fix(cart): prevent duplicate items in shopping cart

Users could add the same item multiple times. Added check to
increment quantity instead of creating duplicate entries.

Fixes #456"
```

**Breaking Change**:
```bash
git commit -m "feat(api)!: change user endpoint response format

BREAKING CHANGE: User API now returns snake_case instead of camelCase.
Update API clients to handle new format.

{
  'user_id': 1,
  'first_name': 'John'
}

Closes #789"
```

**Performance**:
```bash
git commit -m "perf(database): add index on user_id for orders table

Query time reduced from 2.3s to 0.15s for orders by user.
Added composite index on (user_id, created_at).

Closes #234"
```

## Interactive Rebasing

### Clean Up Commit History

```bash
# View last 5 commits
git log --oneline -5

# Interactive rebase
git rebase -i HEAD~5

# Editor opens:
pick a1b2c3d feat: add user model
pick e4f5g6h fix: typo in user model
pick i7j8k9l feat: add user validation
pick m0n1o2p refactor: improve validation
pick q3r4s5t docs: update user model docs

# Change to:
pick a1b2c3d feat: add user model
fixup e4f5g6h fix: typo in user model  # Squash into previous
pick i7j8k9l feat: add user validation
fixup m0n1o2p refactor: improve validation
pick q3r4s5t docs: update user model docs

# Save and close editor
```

### Reorder Commits

```bash
git rebase -i HEAD~3

# Change order in editor:
pick commit1
pick commit2
pick commit3

# To:
pick commit3  # Now first
pick commit1
pick commit2
```

### Edit Commit Messages

```bash
git rebase -i HEAD~3

# Change 'pick' to 'reword':
reword a1b2c3d Old commit message
pick e4f5g6h Another commit

# Editor will open for each 'reword' commit
```

## Pull Request Workflow

### Creating a Pull Request

```bash
# 1. Create feature branch
git checkout -b feature/user-dashboard main

# 2. Make changes
git add .
git commit -m "feat(dashboard): add user statistics widget"

# 3. Push branch
git push -u origin feature/user-dashboard

# 4. Create PR (using GitHub CLI)
gh pr create \
  --title "Add user dashboard with statistics" \
  --body "$(cat <<'EOF'
## Summary
Implements user dashboard with statistics widget showing:
- Total orders
- Revenue
- Active sessions

## Changes
- New DashboardController
- Statistics calculation service
- Frontend components

## Testing
- Unit tests added
- Manual testing completed
- Screenshot attached

## Checklist
- [x] Tests added/updated
- [x] Documentation updated
- [x] No breaking changes
- [x] Follows code style

Closes #567
EOF
)"

# 5. Address review comments
git add .
git commit -m "fix(dashboard): address review comments"
git push

# 6. Merge after approval
gh pr merge --squash --delete-branch
```

### Review Pull Requests

```bash
# Check out PR locally
gh pr checkout 123

# Run tests
npm test

# Review changes
git diff main...feature/user-dashboard

# Comment on PR
gh pr comment 123 --body "LGTM! Great work on the error handling."

# Request changes
gh pr review 123 --request-changes --body "Please add tests for error cases"

# Approve
gh pr review 123 --approve --body "Approved! Ready to merge."
```

## Conflict Resolution

### Merge Conflicts

```bash
# Attempt merge
git merge feature/new-feature

# Conflict!
# Auto-merging src/app.js
# CONFLICT (content): Merge conflict in src/app.js

# View conflicted files
git status

# Open file and resolve:
<<<<<<< HEAD
function oldImplementation() {
=======
function newImplementation() {
>>>>>>> feature/new-feature

# Choose one or combine:
function combinedImplementation() {
    // Best of both
}

# Mark as resolved
git add src/app.js

# Complete merge
git commit -m "merge: resolve conflicts in app.js"
```

### Rebase Conflicts

```bash
# Rebase onto main
git rebase main

# Conflict! Resolve file...
git add resolved-file.js

# Continue rebase
git rebase --continue

# Or abort if needed
git rebase --abort
```

## Advanced Git Techniques

### Cherry-Pick

```bash
# Apply specific commit from another branch
git cherry-pick a1b2c3d

# Cherry-pick without committing
git cherry-pick -n a1b2c3d

# Cherry-pick range
git cherry-pick a1b2c3d..e4f5g6h
```

### Stash

```bash
# Save work in progress
git stash save "WIP: working on feature X"

# List stashes
git stash list

# Apply stash
git stash apply stash@{0}

# Apply and remove
git stash pop

# Create branch from stash
git stash branch feature/from-stash stash@{0}
```

### Bisect

```bash
# Find commit that introduced bug
git bisect start
git bisect bad  # Current commit is bad
git bisect good v1.0.0  # This version was good

# Git checks out middle commit
# Test and mark:
git bisect good  # or git bisect bad

# Repeat until found
# Git will identify the bad commit

# End bisect
git bisect reset
```

### Reflog

```bash
# View all ref changes (even after reset)
git reflog

# Recover lost commit
git reset --hard HEAD@{2}

# Recover deleted branch
git checkout -b recovered-branch HEAD@{5}
```

## Integration Scripts

### git_workflow_helper.sh
Git workflow automation:
```bash
#!/bin/bash
# Git workflow helper

ACTION=$1
BRANCH_NAME=$2

case $ACTION in
  "feature")
    if [ -z "$BRANCH_NAME" ]; then
      echo "Usage: $0 feature <feature-name>"
      exit 1
    fi
    git checkout main
    git pull origin main
    git checkout -b "feature/$BRANCH_NAME"
    echo "Created feature branch: feature/$BRANCH_NAME"
    ;;

  "pr")
    CURRENT_BRANCH=$(git branch --show-current)
    echo "Creating PR for $CURRENT_BRANCH..."

    # Get commit messages for PR description
    COMMITS=$(git log --oneline main..HEAD)

    gh pr create \
      --title "$(echo $CURRENT_BRANCH | sed 's/-/ /g' | sed 's/feature\///')" \
      --body "$(cat <<EOF
## Changes
$COMMITS

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No breaking changes
- [ ] Code review completed
EOF
)"
    ;;

  "sync")
    CURRENT_BRANCH=$(git branch --show-current)
    echo "Syncing $CURRENT_BRANCH with main..."
    git fetch origin
    git merge origin/main
    echo "Merged main into $CURRENT_BRANCH"
    ;;

  "cleanup")
    echo "Cleaning up merged branches..."
    git fetch -p
    git branch --merged main | grep -v "main\|master\|develop" | xargs git branch -d
    echo "Cleanup complete"
    ;;

  "status")
    echo "=== Git Status Overview ==="
    echo "Current branch: $(git branch --show-current)"
    echo "Commits ahead of main: $(git rev-list --count main..HEAD)"
    echo "Modified files: $(git status --short | wc -l)"
    echo "Unpushed commits:"
    git log --oneline @{u}..HEAD
    ;;

  *)
    echo "Usage: $0 {feature|pr|sync|cleanup|status} [args]"
    echo ""
    echo "Commands:"
    echo "  feature <name>  - Create new feature branch"
    echo "  pr              - Create pull request"
    echo "  sync            - Sync current branch with main"
    echo "  cleanup         - Delete merged branches"
    echo "  status          - Show git status overview"
    ;;
esac
```

### commit_validator.sh
Validate commit messages:
```bash
#!/bin/bash
# Commit message validator (Git hook)

commit_msg_file=$1
commit_msg=$(cat "$commit_msg_file")

# Conventional commit pattern
pattern="^(feat|fix|docs|style|refactor|perf|test|chore|ci|revert)(\(.+\))?: .{1,50}"

if ! echo "$commit_msg" | grep -qE "$pattern"; then
    echo "❌ Invalid commit message format!"
    echo ""
    echo "Format: <type>(<scope>): <subject>"
    echo ""
    echo "Types: feat, fix, docs, style, refactor, perf, test, chore, ci, revert"
    echo ""
    echo "Example: feat(auth): add JWT authentication"
    exit 1
fi

echo "✅ Commit message valid"
exit 0
```

### Install Git Hooks

```bash
# Copy to .git/hooks/commit-msg
cp commit_validator.sh .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg

# Or use husky (Node.js)
npm install --save-dev husky
npx husky install
npx husky add .git/hooks/commit-msg 'npx --no -- commitlint --edit $1'
```

## Best Practices

1. **Commit Often**: Small, atomic commits
2. **Write Clear Messages**: Follow conventional commits
3. **Pull Before Push**: Avoid conflicts
4. **Review Before Merging**: Always use PRs
5. **Keep Branches Short-Lived**: Merge within days
6. **Don't Commit Secrets**: Use .gitignore
7. **Tag Releases**: Use semantic versioning
8. **Clean History**: Rebase/squash before merging
9. **Test Before Pushing**: Run tests locally
10. **Document Decisions**: Use commit messages

## .gitignore Best Practices

```gitignore
# Environment
.env
.env.local
.env.*.local

# Dependencies
node_modules/
venv/
__pycache__/
*.pyc

# Build output
dist/
build/
*.log

# IDE
.vscode/
.idea/
*.swp

# OS
.DS_Store
Thumbs.db

# Secrets
*.pem
*.key
config/secrets.json

# Test coverage
coverage/
.coverage
htmlcov/
```

## Requirements

```bash
# GitHub CLI
brew install gh
# Or: https://cli.github.com/

# Commitlint (Node.js)
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# Git extras
brew install git-extras
```

## Metrics to Track

- **Commit frequency**: Daily commits
- **PR merge time**: < 2 days
- **Branch lifetime**: < 1 week
- **Conflict rate**: Minimize
- **Code review coverage**: 100%
- **CI/CD success rate**: > 95%

