| 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 featurefix: Bug fixdocs: Documentation changesstyle: Formatting, missing semicolons, etc.refactor: Code restructuring without behavior changesperf: Performance improvementstest: Adding or updating testschore: Build process, dependencies, toolingci: 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 codedevelop: Integration branch for featuresfeature/*: New featuresrelease/*: Release preparationhotfix/*: Emergency production fixes
Workflow:
git checkout develop
git checkout -b feature/user-authentication
git checkout develop
git merge feature/user-authentication
git branch -d feature/user-authentication
git checkout -b release/1.2.0
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 deployablefeature/*: All changes
Workflow:
git checkout -b feature/add-dark-mode
git commit -m "feat(ui): add dark mode toggle"
git push origin feature/add-dark-mode
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:
git checkout feature/my-feature
git fetch origin
git merge origin/main
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:
npm run lint
npm run format
npm run test:unit
commit-msg:
pre-push:
npm run test
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:
git log
git cherry-pick <commit-hash>
Interactive Rebase
Clean up commit history before pushing:
git rebase -i HEAD~3
Common Scenarios
Undo Last Commit (Not Pushed)
git reset --soft HEAD~1
git reset HEAD~1
git reset --hard HEAD~1
Undo Pushed Commit
git revert <commit-hash>
git push origin main
Stash Changes
git stash save "WIP: feature description"
git stash list
git stash apply stash@{0}
git stash pop
Update Commit Message
git commit --amend -m "new message"
git rebase -i HEAD~n
Worktrees
Git worktrees let you work on multiple branches simultaneously without stashing or switching.
When to Use Worktrees vs Branches
| Scenario | Use Branch | Use Worktree |
|---|
| Sequential feature work | Yes | No |
| Parallel features (simultaneous) | No | Yes |
| Quick hotfix while mid-feature | Stash + branch | Yes (cleaner) |
| Risky experiment | Maybe | Yes (isolated) |
| Code review while coding | No | Yes |
Using EnterWorktree/ExitWorktree
Claude Code provides built-in worktree tools:
- EnterWorktree — Creates an isolated worktree with a new branch from HEAD. Provide an optional
name for the worktree.
- ExitWorktree — Leave the worktree. Choose
keep (preserve for later) or remove (clean up).
Common Patterns
Experiment safely:
EnterWorktree with name experiment-X- Try the risky approach
- If it works: commit,
ExitWorktree(keep), merge later
- If it fails:
ExitWorktree(remove) — no mess
Hotfix while mid-feature:
EnterWorktree with name hotfix-Y- Fix the bug, commit, push
ExitWorktree(remove) — back to feature work
See the worktree-workflow skill for detailed patterns and best practices.
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
git add <file>
git commit -m "message"
git push origin <branch>
git pull origin <branch>
git checkout -b <branch>
git merge <branch>
Inspection:
git log --oneline --graph
git diff
git diff --staged
git show <commit>
git blame <file>
Cleanup:
git branch -d <branch>
git push origin :<branch>
git clean -fd
git gc
