| name | git-workflow |
| description | Git workflow best practices including commit messages, branching strategies, pull requests, and collaboration patterns. Use when working with Git version control. |
Git Workflow Best Practices
Purpose
This skill provides guidance on Git workflow best practices to ensure clean commit history, effective collaboration, and maintainable version control in your projects.
When to Use This Skill
Auto-activates when:
- Mentions of "git", "commit", "branch", "merge", "pull request"
- Working with version control operations
- Creating or reviewing commits
- Managing branches and releases
Commit Messages
Conventional Commits Format
Follow the Conventional Commits specification:
<type>(<scope>): <subject>
<body>
<footer>
Types:
feat: New featurefix: Bug fixdocs: Documentation onlystyle: Code style changes (formatting, no logic change)refactor: Code refactoring (no feature or bug fix)perf: Performance improvementstest: Adding or updating testsbuild: Build system or dependency changesci: CI/CD configuration changeschore: Other changes (tooling, maintenance)
Examples:
feat(auth): add OAuth2 authentication support
Implement OAuth2 authentication flow using the authorization
code grant type. Supports Google and GitHub providers.
Closes #123
fix(api): handle null response from database query
Previously, null responses would cause the API to crash.
Now returns 404 with appropriate error message.
Fixes #456
Commit Message Best Practices
- Use imperative mood in subject line: "Add feature" not "Added feature"
- Keep subject line under 50 characters
- Capitalize subject line
- No period at end of subject line
- Separate subject from body with blank line
- Wrap body at 72 characters
- Explain what and why, not how
- Reference issues/tickets in footer
Branching Strategy
Branch Naming Convention
Use descriptive, hierarchical branch names:
<type>/<issue-number>-<short-description>
Examples:
feature/123-oauth-authenticationfix/456-null-pointer-crashdocs/789-api-documentationrefactor/321-simplify-parserhotfix/999-security-vulnerability
Git Flow Strategy
Common branching model:
main (production)
├── develop (integration)
│ ├── feature/123-new-feature
│ ├── feature/456-another-feature
│ └── fix/789-bug-fix
├── release/1.2.0
└── hotfix/critical-security-fix
Branch purposes:
main: Production-ready codedevelop: Integration branch for featuresfeature/*: New featuresfix/*: Bug fixesrelease/*: Release preparationhotfix/*: Critical production fixes
Branch Management
Creating a feature branch:
git checkout develop
git pull origin develop
git checkout -b feature/123-new-feature
Keeping branch up to date:
git checkout develop
git pull origin develop
git checkout feature/123-new-feature
git rebase develop
Cleaning up merged branches:
git branch -d feature/123-new-feature
git push origin --delete feature/123-new-feature
Pull Requests
Pull Request Description Template
## Summary
Brief description of what this PR does and why.
## Changes
- Add new authentication module
- Update user model with OAuth fields
- Add tests for OAuth flow
## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
## Related Issues
Closes #123
Relates to #456
## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] All tests passing
PR Best Practices
- Keep PRs small and focused: One feature/fix per PR
- Write clear descriptions: Explain what, why, and how
- Self-review before requesting review: Catch obvious issues
- Add tests: Every PR should include relevant tests
- Update documentation: Keep docs in sync with code
- Respond to feedback promptly: Address review comments quickly
Common Operations
Amending Last Commit
git add .
git commit --amend --no-edit
git commit --amend -m "Updated commit message"
Warning: Only amend commits that haven't been pushed!
Interactive Rebase
Clean up commit history:
git rebase -i HEAD~3
Commands:
pick: Keep commit as-isreword: Change commit messagesquash: Combine with previous commitfixup: Like squash, but discard messagedrop: Remove commit
Stashing Changes
git stash push -m "WIP: working on feature"
git stash list
git stash pop
git stash apply stash@{0}
Cherry-Picking Commits
git cherry-pick <commit-hash>
git cherry-pick <commit-hash1> <commit-hash2>
git cherry-pick <start-hash>^..<end-hash>
Undoing Changes
Discard uncommitted changes:
git restore <file>
git restore --staged <file>
git reset --hard HEAD
Undo commits:
git reset --soft HEAD~1
git reset HEAD~1
git reset --hard HEAD~1
Revert commit (safe for shared branches):
git revert <commit-hash>
Collaboration Patterns
Keeping Fork Updated
git remote add upstream <original-repo-url>
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
Resolving Merge Conflicts
git merge develop
git add <resolved-file>
git commit
git rebase --continue
Git Configuration
Essential Git Config
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global init.defaultBranch main
git config --global pull.rebase true
git config --global alias.lg "log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"
Useful Aliases
git config --global alias.st status
git config --global alias.ci commit
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.undo "reset --soft HEAD~1"
git config --global alias.cleanup "!git branch --merged | grep -v '\\*\\|main\\|develop' | xargs -n 1 git branch -d"
Security Best Practices
Avoiding Sensitive Data
- Never commit secrets: API keys, passwords, tokens
- Use .gitignore: Exclude sensitive files
- Use environment variables: Store secrets outside repo
- Use git-secrets: Tool to prevent committing secrets
brew install git-secrets
git secrets --install
git secrets --register-aws
git secrets --scan-history
Signing Commits
gpg --gen-key
git config --global user.signingkey <key-id>
git config --global commit.gpgsign true
git commit -S -m "Signed commit message"
.gitignore Best Practices
Common Patterns
# Operating System
.DS_Store
Thumbs.db
# IDE/Editor
.vscode/
.idea/
*.swp
# Language-specific
__pycache__/
*.pyc
node_modules/
*.class
target/
# Build artifacts
dist/
build/
*.egg-info/
# Environment
.env
.env.local
venv/
env/
# Logs
*.log
logs/
# Temporary files
*.tmp
.cache/
gitignore Tips
- Use
** for recursive directory matching
- Use
! to negate patterns (whitelist files)
- Use
# for comments
- Test patterns:
git check-ignore -v <file>
Key Takeaways
- Write clear, conventional commit messages
- Use descriptive branch names with type prefixes
- Keep pull requests small and focused
- Rebase feature branches to keep history clean
- Never commit sensitive data
- Use
.gitignore effectively
- Review code thoughtfully and constructively
- Keep branches up to date with main/develop
- Sign commits for security
- Configure Git aliases for efficiency
