git-workflow
Git workflow patterns for branching, commits, and pull requests following project conventions.
When & Why to Use This Skill
This Claude skill streamlines the software development lifecycle by enforcing standardized Git workflow patterns. It provides structured guidance on branching strategies, semantic commit conventions, and comprehensive pull request templates, ensuring repository consistency and improving team collaboration efficiency through best practices in version control.
Use Cases
- Standardizing Team Workflows: Enforce consistent branching and naming conventions across the development team to maintain a clean and navigable repository history.
- Semantic Commit Compliance: Assist developers in crafting clear, standardized commit messages (e.g., feat, fix, refactor) that facilitate automated changelog generation and easier debugging.
- Structured Pull Request Creation: Utilize predefined templates to ensure all PRs include necessary context, testing details, and checklists, leading to faster and more effective code reviews.
- Release Management: Guide the team through the complex process of creating release branches, tagging versions, and merging changes back to main and develop branches safely.
- Workflow Troubleshooting: Provide immediate assistance for common Git challenges such as resolving merge conflicts, performing interactive rebases, or recovering deleted branches.
| name | git-workflow |
|---|---|
| description | Git workflow patterns for branching, commits, and pull requests following project conventions. |
Git Workflow Skill
Overview
This skill defines the git workflow patterns for the project, including branching strategies, commit conventions, and pull request guidelines.
Branching Strategy
Branch Types
| Branch | Purpose | Naming |
|---|---|---|
main |
Production-ready code | Protected |
develop |
Integration branch | Protected |
feature/* |
New features | feature/description |
bugfix/* |
Bug fixes | bugfix/issue-description |
hotfix/* |
Production fixes | hotfix/critical-fix |
release/* |
Release preparation | release/v1.2.0 |
Branch Naming Convention
type/short-description
Examples:
feature/user-authentication
bugfix/login-validation
hotfix/security-patch
release/v2.0.0
Commit Conventions
Commit Message Format
type(scope): subject
body (optional)
footer (optional)
Types
| Type | Description |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation |
style |
Formatting (no code change) |
refactor |
Code refactoring |
test |
Adding tests |
chore |
Maintenance |
perf |
Performance improvement |
ci |
CI/CD changes |
Examples
# Feature
feat(auth): add JWT token validation
# Bug fix
fix(api): resolve null pointer in user lookup
# Documentation
docs(readme): update installation instructions
# Refactor
refactor(utils): simplify date formatting logic
Commit Guidelines
- Keep commits atomic: One logical change per commit
- Use present tense: "add feature" not "added feature"
- Keep subject under 50 characters
- Wrap body at 72 characters
- Reference issues:
Closes #123orFixes #456
Workflow Steps
Starting New Work
# 1. Start from develop
git checkout develop
git pull origin develop
# 2. Create feature branch
git checkout -b feature/my-feature
# 3. Make changes and commit
git add .
git commit -m "feat(scope): description"
# 4. Push branch
git push -u origin feature/my-feature
Creating Pull Request
# 1. Ensure up to date with develop
git checkout develop
git pull origin develop
git checkout feature/my-feature
git rebase develop
# 2. Push final changes
git push origin feature/my-feature
# 3. Create PR via GitHub/CLI
gh pr create --base develop --title "feat: description" --body "..."
PR Description Template
## Summary
[Brief description of changes]
## Changes Made
- [Change 1]
- [Change 2]
## Testing Done
- [Test 1]
- [Test 2]
## Checklist
- [ ] Tests pass
- [ ] Code reviewed
- [ ] Documentation updated
- [ ] No breaking changes (or documented)
## Related Issues
Closes #XXX
Merging
# Squash merge for features
git checkout develop
git merge --squash feature/my-feature
git commit -m "feat(scope): complete feature description"
git push origin develop
# Delete feature branch
git branch -d feature/my-feature
git push origin --delete feature/my-feature
Common Tasks
Sync with Upstream
git fetch origin
git checkout develop
git pull origin develop
git checkout feature/my-feature
git rebase develop
Fix Merge Conflicts
# During rebase
git status # See conflicted files
# Edit files to resolve conflicts
git add <resolved-files>
git rebase --continue
Amend Last Commit
# Change message
git commit --amend -m "new message"
# Add forgotten files
git add forgotten-file.js
git commit --amend --no-edit
Interactive Rebase (Clean History)
# Squash last 3 commits
git rebase -i HEAD~3
# In editor, change 'pick' to 'squash' for commits to combine
Protected Branch Rules
main Branch
- Requires PR with 1+ approval
- Requires passing CI
- No direct pushes
- Linear history (squash merge)
develop Branch
- Requires PR
- Requires passing CI
- No force push
Release Process
# 1. Create release branch
git checkout develop
git checkout -b release/v1.2.0
# 2. Update version numbers, changelog
# ... make release preparations ...
# 3. Merge to main
git checkout main
git merge release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags
# 4. Merge back to develop
git checkout develop
git merge release/v1.2.0
git push origin develop
# 5. Clean up
git branch -d release/v1.2.0
Troubleshooting
Undo Last Commit (Keep Changes)
git reset --soft HEAD~1
Undo Last Commit (Discard Changes)
git reset --hard HEAD~1
Recover Deleted Branch
git reflog # Find commit hash
git checkout -b recovered-branch <hash>
Clean Untracked Files
git clean -fd # Remove untracked files and directories