git-workflow

name	git-workflow
description	Git and GitHub workflow best practices. Use for commits, branches, PRs, merging, and version control operations. Use when this capability is needed.
metadata	{"author":"aiyuekuang"}

Git Workflow Skill

Git best practices for version control, branching strategies, and GitHub collaboration.

When to Use This Skill

• Creating commits with proper messages
• Managing branches
• Creating and reviewing pull requests
• Resolving merge conflicts
• Git history management

---

📝 Commit Messages

Conventional Commits Format

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

[optional body]

[optional footer(s)]

Commit Types

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation only
style	Formatting, no code change
refactor	Code restructuring
perf	Performance improvement
test	Adding/updating tests
chore	Maintenance tasks
ci	CI/CD changes
build	Build system changes

Examples

# Feature
feat(auth): add JWT token refresh mechanism

# Bug fix
fix(proxy): resolve connection leak in upstream handler

# With body
feat(api): add rate limiting for /v1/chat endpoint

Implements token bucket algorithm with configurable
rate and burst size. Limits are per API key.

Closes #123

# Breaking change
feat(config)!: change yaml config structure

BREAKING CHANGE: config.yaml format changed.
See migration guide in docs/migration-v2.md

---

🌳 Branching Strategy

Git Flow

main (production)
  │
  └── develop (integration)
        │
        ├── feature/user-auth
        ├── feature/dashboard
        ├── fix/login-bug
        └── release/v1.2.0
              │
              └── hotfix/critical-fix → main

Branch Naming

# Features
feature/add-user-authentication
feature/JIRA-123-dashboard-charts

# Bug fixes
fix/login-validation-error
fix/JIRA-456-memory-leak

# Releases
release/v1.2.0
release/2024-01-sprint

# Hotfixes
hotfix/critical-security-patch

---

🔄 Pull Request Workflow

Creating a PR

# 1. Create feature branch
git checkout -b feature/my-feature develop

# 2. Make commits
git add .
git commit -m "feat: implement feature"

# 3. Push and create PR
git push -u origin feature/my-feature

# 4. Create PR via GitHub CLI
gh pr create --title "feat: implement feature" \
  --body "Description of changes" \
  --base develop

PR Template

## Summary
Brief description of changes

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

## Changes Made
- Change 1
- Change 2

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

## Screenshots (if UI changes)

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-reviewed
- [ ] Comments added for complex logic
- [ ] Documentation updated

Merging Strategies

# Squash merge (recommended for features)
# Combines all commits into one clean commit
gh pr merge --squash

# Merge commit (for releases)
# Preserves full history
gh pr merge --merge

# Rebase (for small changes)
# Linear history, no merge commit
gh pr merge --rebase

---

🔧 Common Git Operations

Stashing Changes

# Save current work
git stash save "WIP: feature description"

# List stashes
git stash list

# Apply most recent stash
git stash pop

# Apply specific stash
git stash apply stash@{2}

# Clear all stashes
git stash clear

Rebasing

# Interactive rebase last 5 commits
git rebase -i HEAD~5

# Rebase onto main
git rebase main

# Continue after resolving conflicts
git rebase --continue

# Abort rebase
git rebase --abort

Cherry-picking

# Apply specific commit to current branch
git cherry-pick abc123

# Cherry-pick without committing
git cherry-pick --no-commit abc123

# Cherry-pick range
git cherry-pick abc123..def456

Undoing Changes

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Revert a commit (creates new commit)
git revert abc123

# Restore file to last commit
git checkout -- filename

# Unstage file
git reset HEAD filename

---

🔀 Merge Conflict Resolution

Process

# 1. Update your branch
git fetch origin
git rebase origin/main

# 2. If conflicts occur, resolve them
# Edit conflicting files, then:
git add resolved-file.go
git rebase --continue

# 3. Force push (if rebased)
git push --force-with-lease

Conflict Markers

<<<<<<< HEAD
Your changes
=======
Their changes
>>>>>>> feature-branch

Tips

• Keep changes focused and PRs small
• Rebase frequently to avoid large conflicts
• Use git mergetool for complex conflicts
• Communicate with team before force pushing

---

📊 Git History Management

Viewing History

# Pretty log
git log --oneline --graph --all

# Show changes in commits
git log -p -3

# Search commits by message
git log --grep="fix"

# Show commits by author
git log --author="name"

# Show files changed
git log --stat

Finding Bugs with Bisect

# Start bisect
git bisect start

# Mark current as bad
git bisect bad

# Mark known good commit
git bisect good v1.0.0

# Git checks out middle commit, test it, then:
git bisect good  # or git bisect bad

# When done
git bisect reset

---

🏷️ Tagging Releases

# Create annotated tag
git tag -a v1.2.0 -m "Release version 1.2.0"

# Push tags
git push origin v1.2.0
git push --tags

# List tags
git tag -l "v1.*"

# Delete tag
git tag -d v1.2.0
git push origin --delete v1.2.0

---

📚 References

• Conventional Commits
• Git Flow
• fvadicamo/dev-agent-skills
• obra/finishing-a-development-branch
• obra/using-git-worktrees

---

Source: aiyuekuang/LLMProxy — distributed by TomeVault.