Smithery is now a part of Arcade.dev! Read more in our announcement here
Provides standardized Git workflows, commit message conventions, branching strategies, and collaboration patterns for all agents performing Git operations...
This skill provides comprehensive Git workflow guidance for agents performing version control operations. It covers commit message conventions (Conventional Commits), branching strategies (GitHub Flow, Git Flow, Trunk-based), PR best practices, git operation patterns (merge vs rebase vs squash), collaboration workflows, and security considerations.
Use this skill whenever performing git operations to ensure consistency, maintainability, and professional quality across all projects.
Follow the Conventional Commits specification for all commit messages:
<type>(<scope>): <subject>
<body>
<footer>
Components:
feat: New feature for the user
feat(auth): add OAuth2 login support
Implement OAuth2 authentication flow with Google and GitHub providers.
Includes token refresh mechanism and session management.
Closes #142
fix: Bug fix for the user
fix(api): prevent race condition in user creation
Add database transaction lock to prevent duplicate user records
when multiple requests arrive simultaneously.
Fixes #238
docs: Documentation changes only
docs(readme): add installation instructions for Windows
Include troubleshooting section for common Windows-specific issues.
style: Code formatting, missing semicolons, whitespace (no logic change)
style(components): format with prettier, remove trailing whitespace
refactor: Code change that neither fixes bug nor adds feature
refactor(database): extract query builder into separate class
Improve code organization and testability by separating query
construction from execution logic.
test: Adding or updating tests
test(auth): add integration tests for OAuth flow
chore: Maintenance tasks, dependency updates, build configuration
chore(deps): upgrade React from 18.2.0 to 18.3.0
perf: Performance improvement
perf(api): add database indexes for user queries
Reduce user lookup time from 250ms to 15ms by indexing email column.
ci: CI/CD configuration changes
ci(github): add automated deployment to staging environment
build: Build system or external dependency changes
build(webpack): optimize bundle size with code splitting
revert: Reverts a previous commit
revert: feat(auth): add OAuth2 login support
This reverts commit a1b2c3d4. OAuth implementation needs rework
due to security concerns identified in code review.
Indicate breaking changes with ! after type/scope and in footer:
feat(api)!: change user endpoint response format
BREAKING CHANGE: User API now returns `userId` instead of `id`.
Clients must update to use new field name.
Migration guide: https://docs.example.com/migration-v2
ā Bad Examples:
Update files
Fix bug
WIP
asdf
Changed some stuff
Fixed it
ā Good Examples:
feat(search): add fuzzy matching for product queries
fix(checkout): calculate tax correctly for international orders
docs(api): update authentication examples
refactor(utils): extract date formatting into helper function
Use multi-line messages for non-trivial changes:
feat(notifications): implement real-time notification system
Add WebSocket-based notification delivery for user actions.
Includes:
- WebSocket server with connection pooling
- Client-side notification queue with retry logic
- Notification preferences UI
- Email fallback for offline users
Performance: Handles 10k concurrent connections with <100ms latency.
Closes #156, #187
When agents create commits, always:
git diff to understand changesš¤ Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Choose GitHub Flow (recommended for most projects):
Choose Git Flow:
Choose Trunk-based Development:
Branches:
main: Always deployable, protectedfeature/*: Short-lived feature branchesWorkflow:
main: feature/add-user-searchmain (squash or merge commit)main to productionBranch naming:
feature/add-oauth-login
feature/user-profile-page
bugfix/fix-login-redirect
hotfix/patch-security-vulnerability
docs/update-api-documentation
Example workflow:
# Start feature
git checkout main
git pull origin main
git checkout -b feature/add-search-filter
# Work on feature
git add src/components/SearchFilter.tsx
git commit -m "feat(search): add category filter to search UI"
# Push and create PR
git push -u origin feature/add-search-filter
gh pr create --title "Add category filter to search" --body "..."
# After PR approval
# Merge via GitHub UI (squash recommended)
# Delete branch
git checkout main
git pull origin main
git branch -d feature/add-search-filter
Branches:
main: Production releases onlydevelop: Integration branchfeature/*: Feature developmentrelease/*: Release preparationhotfix/*: Production hotfixesWorkflow:
develop, merge back to developdevelop, merge to main and developmain, merge to main and developUse when: Managing multiple release versions, scheduled releases, complex projects
Example:
# Feature development
git checkout develop
git checkout -b feature/payment-integration
# ... work ...
git checkout develop
git merge --no-ff feature/payment-integration
# Release
git checkout -b release/1.2.0 develop
# ... version bump, changelog ...
git checkout main
git merge --no-ff release/1.2.0
git tag -a v1.2.0
git checkout develop
git merge --no-ff release/1.2.0
Branches:
main: The trunk, always deployablefeature/*: Very short-lived (< 1 day)Workflow:
main within hours/1 daymain frequently (multiple times per day)Requirements:
Use conventional commit format:
feat(auth): add OAuth2 login support
fix(api): prevent race condition in user creation
docs(readme): add installation instructions
## Summary
Brief description of what this PR does and why.
## Changes
- Add OAuth2 authentication with Google and GitHub
- Implement token refresh mechanism
- Add session management
- Update user model to store OAuth tokens
## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
## Testing
- [x] Unit tests added/updated
- [x] Integration tests added/updated
- [x] Manual testing completed
- [ ] Performance testing completed
## Test Plan
1. Test Google OAuth login flow
2. Test GitHub OAuth login flow
3. Verify token refresh after expiry
4. Test session persistence across browser restarts
## Screenshots (if applicable)
[Add screenshots of UI changes]
## Breaking Changes
None
## Related Issues
Closes #142
Related to #156
## Checklist
- [x] Code follows project style guidelines
- [x] Self-review completed
- [x] Comments added for complex logic
- [x] Documentation updated
- [x] No new warnings generated
- [x] Tests pass locally
- [x] Dependent changes merged
Optimal PR size: 200-400 lines changed Maximum recommended: 800 lines changed
When PR is too large:
Create draft PR when:
Mark as "Ready for review" when:
When making changes:
# Make requested changes
git add src/auth/oauth.ts
git commit -m "refactor(auth): extract token validation per review feedback"
git push origin feature/add-oauth-login
When resolving comments:
Merge Commit (git merge --no-ff):
git checkout main
git merge --no-ff feature/add-search
# Creates merge commit
Rebase (git rebase):
# Update feature branch with latest main
git checkout feature/add-search
git rebase main
# Interactive rebase to clean up commits
git rebase -i HEAD~5
Squash Merge (git merge --squash):
git checkout main
git merge --squash feature/add-search
git commit -m "feat(search): add advanced search functionality"
| Scenario | Operation | Reasoning |
|---|---|---|
| Update feature branch with main | Rebase | Keep linear history |
| Merge feature to main (GitHub Flow) | Squash | Clean main history |
| Merge feature to main (Git Flow) | Merge commit | Preserve feature history |
| Clean up local commits before PR | Interactive rebase | Present clean history |
| Integrate long-lived branch | Merge commit | Preserve collaboration history |
| Apply single commit from another branch | Cherry-pick | Selective integration |
Before creating PR:
# Interactive rebase to clean up commits
git rebase -i main
# In editor, squash/fixup WIP commits:
pick a1b2c3d feat(search): add search component
fixup e4f5g6h WIP: fix typo
fixup h7i8j9k WIP: update tests
pick k0l1m2n feat(search): add filters
Commit message guidelines for clean history:
ā Never force push to:
main / masterdevelopā Safe to force push to:
When force push is needed:
# After rebasing/amending on feature branch
git push --force-with-lease origin feature/add-search
--force-with-lease: Safer than --force, prevents overwriting others' work
When to use cherry-pick:
Example:
# Apply specific commit to current branch
git cherry-pick a1b2c3d
# Apply multiple commits
git cherry-pick a1b2c3d..e4f5g6h
# Cherry-pick without committing (for editing)
git cherry-pick -n a1b2c3d
Branch Workflow (recommended for teams):
Fork Workflow:
Method 1: Rebase (clean history):
git checkout feature/add-search
git fetch origin
git rebase origin/main
# If conflicts, resolve and continue
git add .
git rebase --continue
# Force push to update PR
git push --force-with-lease origin feature/add-search
Method 2: Merge (preserve history):
git checkout feature/add-search
git fetch origin
git merge origin/main
# Resolve conflicts if any
git add .
git commit -m "merge: resolve conflicts with main"
git push origin feature/add-search
Recommendation: Use rebase for feature branches, merge for long-lived branches
Workflow:
git status<<<<<<< HEAD
Your changes
=======
Their changes
>>>>>>> branch-name
git add src/conflicted-file.ts
git commit -m "merge: resolve conflicts in user authentication"
Best practices:
git mergetoolWhen multiple people contribute to a commit:
feat(auth): implement OAuth2 authentication
Add Google and GitHub OAuth providers with token refresh.
Co-authored-by: Jane Developer <jane@example.com>
Co-authored-by: Bob Engineer <bob@example.com>
Claude Code integration: Always include Claude as co-author:
Co-authored-by: Claude <noreply@anthropic.com>
Definition: One logical change per commit
ā Good (atomic):
# Commit 1: Add feature
git commit -m "feat(search): add search bar component"
# Commit 2: Add tests
git commit -m "test(search): add search bar component tests"
# Commit 3: Update docs
git commit -m "docs(search): document search bar API"
ā Bad (non-atomic):
# One commit with multiple unrelated changes
git commit -m "Add search, fix login bug, update README"
Benefits of atomic commits:
pre-commit: Run before commit is created
commit-msg: Validate commit message
pre-push: Run before push to remote
Using Husky (JavaScript projects):
{
"husky": {
"hooks": {
"pre-commit": "lint-staged",
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
},
"lint-staged": {
"*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
"*.{json,md}": ["prettier --write"]
}
}
Using pre-commit framework (Python projects):
# .pre-commit-config.yaml
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.4.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-added-large-files
- repo: https://github.com/psf/black
rev: 23.1.0
hooks:
- id: black
- repo: https://github.com/pycqa/flake8
rev: 6.0.0
hooks:
- id: flake8
Using commitlint:
// commitlint.config.js
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [
2,
'always',
['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'perf', 'ci', 'build', 'revert']
],
'subject-max-length': [2, 'always', 50],
'body-max-line-length': [2, 'always', 72]
}
};
Use hooks for:
Use CI/CD for:
Reason: Hooks should be fast to not slow down development workflow
Common secrets to avoid:
.env files with secretsPrevention with .gitignore:
# Environment files
.env
.env.local
.env.*.local
# Credentials
credentials.json
secrets.yaml
*.key
*.pem
# Cloud provider
.aws/credentials
.gcloud/credentials
# IDE
.vscode/settings.json (if contains secrets)
If secret committed but not pushed:
# Remove file from staging
git reset HEAD secrets.env
# Amend last commit
git commit --amend
# Or reset to previous commit
git reset --soft HEAD~1
If secret already pushed:
# Using git filter-repo (recommended)
git filter-repo --path secrets.env --invert-paths
# Or using BFG Repo-Cleaner
bfg --delete-files secrets.env
# Force push (coordinate with team!)
git push --force-with-lease origin main
git log --all --full-history -- secrets.envImportant: Removing from git doesn't invalidate the secret. Always rotate!
Why sign commits:
Setup GPG signing:
# Generate GPG key
gpg --full-generate-key
# List keys
gpg --list-secret-keys --keyid-format=long
# Configure git
git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true
# Sign individual commit
git commit -S -m "feat(auth): add OAuth login"
GitHub verification:
gpg --armor --export YOUR_KEY_IDRecommended protections for main:
GitHub branch protection setup:
Repository Settings ā Branches ā Add rule ā main
Review requirements:
CODEOWNERS file:
# .github/CODEOWNERS
# Require review from team leads
/src/auth/* @auth-team
/src/api/* @backend-team
/src/ui/* @frontend-team
# Require multiple reviews for critical files
/deploy/* @devops-team @tech-leads
Scenario: Add user profile page
# 1. Start from updated main
git checkout main
git pull origin main
# 2. Create feature branch
git checkout -b feature/user-profile-page
# 3. Develop incrementally with atomic commits
git add src/pages/UserProfile.tsx
git commit -m "feat(profile): add user profile page component"
git add src/api/user.ts
git commit -m "feat(profile): add API endpoint for user data"
git add src/pages/UserProfile.test.tsx
git commit -m "test(profile): add user profile component tests"
git add docs/user-profile.md
git commit -m "docs(profile): document user profile feature"
# 4. Keep branch updated with main
git fetch origin
git rebase origin/main
# 5. Push and create PR
git push -u origin feature/user-profile-page
gh pr create \
--title "feat(profile): add user profile page" \
--body "$(cat <<'EOF'
## Summary
Implements user profile page with avatar, bio, and settings.
## Changes
- Add UserProfile component with responsive design
- Add API endpoint for fetching user data
- Add unit and integration tests
- Update documentation
## Test Plan
1. Navigate to /profile
2. Verify profile information displays correctly
3. Test on mobile and desktop viewports
4. Verify edit functionality
Closes #156
EOF
)"
# 6. Address review feedback
git add src/pages/UserProfile.tsx
git commit -m "refactor(profile): extract avatar component per review"
git push origin feature/user-profile-page
# 7. After PR approval and merge
git checkout main
git pull origin main
git branch -d feature/user-profile-page
Scenario: Critical security vulnerability in production
# 1. Create hotfix branch from main
git checkout main
git pull origin main
git checkout -b hotfix/patch-auth-vulnerability
# 2. Fix the issue
git add src/auth/oauth.ts
git commit -m "fix(auth)!: patch token validation vulnerability
BREAKING CHANGE: OAuth tokens now require signature validation.
Invalid tokens will be rejected immediately.
Security: Prevents token forgery attack (CVE-2024-XXXXX)
Closes #489"
# 3. Add tests for the fix
git add src/auth/oauth.test.ts
git commit -m "test(auth): add security tests for token validation"
# 4. Push and create urgent PR
git push -u origin hotfix/patch-auth-vulnerability
gh pr create \
--title "fix(auth)!: patch token validation vulnerability [SECURITY]" \
--label "security,hotfix" \
--body "$(cat <<'EOF'
## Summary
šØ SECURITY: Patches critical token validation vulnerability.
## Vulnerability
OAuth tokens were not properly validated, allowing token forgery.
## Fix
- Add signature validation for all OAuth tokens
- Reject invalid tokens immediately
- Add comprehensive security tests
## Breaking Change
Invalid tokens that were previously accepted will now be rejected.
## Testing
- [x] Security tests added
- [x] Manual testing with valid tokens
- [x] Manual testing with forged tokens
- [x] Backward compatibility verified
## Deployment
Requires immediate deployment to production.
Fixes #489
EOF
)"
# 5. After expedited review and merge
git checkout main
git pull origin main
git branch -d hotfix/patch-auth-vulnerability
# 6. Tag the release
git tag -a v1.2.1 -m "Hotfix: patch auth vulnerability"
git push origin v1.2.1
Scenario: Refactor database layer for better performance
# 1. Create refactoring branch
git checkout main
git pull origin main
git checkout -b refactor/database-layer-optimization
# 2. Make incremental, atomic commits
git add src/db/connection.ts
git commit -m "refactor(db): extract connection pool configuration"
git add src/db/queries/user.ts
git commit -m "refactor(db): optimize user queries with prepared statements"
git add src/db/queries/product.ts
git commit -m "refactor(db): add database indexes for product queries
Performance improvement: Product search reduced from 250ms to 15ms"
git add src/db/transaction.ts
git commit -m "refactor(db): implement transaction helper utility"
# 3. Keep tests passing after each commit
git add src/db/queries/user.test.ts
git commit -m "test(db): update user query tests for new implementation"
# 4. Update integration tests
git add tests/integration/db.test.ts
git commit -m "test(db): add integration tests for transaction handling"
# 5. Document performance improvements
git add docs/database-optimization.md
git commit -m "docs(db): document database optimization approach and results"
# 6. Rebase onto main to stay current
git fetch origin
git rebase origin/main
# 7. Review commits are atomic and well-organized
git log --oneline origin/main..HEAD
# 8. Create PR with detailed context
git push -u origin refactor/database-layer-optimization
gh pr create \
--title "refactor(db): optimize database layer for performance" \
--body "$(cat <<'EOF'
## Summary
Refactors database layer to improve query performance and code organization.
## Changes
- Extract connection pool configuration for better reusability
- Optimize user and product queries with prepared statements
- Add database indexes for common query patterns
- Implement transaction helper utility
- Update all tests for new implementation
## Performance Impact
- User lookup: 180ms ā 12ms (93% improvement)
- Product search: 250ms ā 15ms (94% improvement)
- Checkout flow: 450ms ā 85ms (81% improvement)
## Testing
- [x] All existing tests pass
- [x] Added integration tests for transactions
- [x] Performance benchmarks completed
- [x] Load testing with 1000 concurrent users
## Migration
No database migrations required. Changes are backward compatible.
## Breaking Changes
None
Related to #234
EOF
)"
Scenario: Update API documentation for new endpoints
# 1. Create docs branch
git checkout main
git pull origin main
git checkout -b docs/update-api-documentation
# 2. Update documentation files
git add docs/api/authentication.md
git commit -m "docs(api): update OAuth authentication examples"
git add docs/api/users.md
git commit -m "docs(api): add user profile endpoint documentation"
git add docs/api/search.md
git commit -m "docs(api): document new search filters API"
git add README.md
git commit -m "docs(readme): update API reference links"
# 3. Verify documentation builds correctly
npm run docs:build
# 4. Push and create PR
git push -u origin docs/update-api-documentation
gh pr create \
--title "docs(api): update API documentation for v2.0" \
--body "$(cat <<'EOF'
## Summary
Updates API documentation to reflect v2.0 changes.
## Changes
- Update OAuth authentication examples
- Add user profile endpoint documentation
- Document new search filters API
- Update README with correct API reference links
## Verification
- [x] Documentation builds without errors
- [x] All links are valid
- [x] Code examples tested and working
- [x] Screenshots updated
Related to #298
EOF
)"
# 5. After review and merge
git checkout main
git pull origin main
git branch -d docs/update-api-documentation
Scenario: Implement search functionality (complex feature)
# 1. Create feature branch
git checkout main
git pull origin main
git checkout -b feature/advanced-search
# 2. Build feature incrementally with atomic commits
# Add search infrastructure
git add src/search/index.ts src/search/types.ts
git commit -m "feat(search): add search infrastructure and types"
# Add search parser
git add src/search/parser.ts
git commit -m "feat(search): implement query parser with boolean operators"
# Add search indexer
git add src/search/indexer.ts
git commit -m "feat(search): add document indexer with full-text support"
# Add search API
git add src/api/search.ts
git commit -m "feat(search): add search API endpoints"
# Add search UI component
git add src/components/SearchBar.tsx
git commit -m "feat(search): add search bar component"
# Add filters
git add src/components/SearchFilters.tsx
git commit -m "feat(search): add category and date filters"
# Add tests for each component
git add src/search/parser.test.ts
git commit -m "test(search): add query parser tests"
git add src/search/indexer.test.ts
git commit -m "test(search): add indexer tests"
git add src/components/SearchBar.test.tsx
git commit -m "test(search): add search bar component tests"
# Add integration tests
git add tests/integration/search.test.ts
git commit -m "test(search): add end-to-end search integration tests"
# Add documentation
git add docs/search.md
git commit -m "docs(search): document search API and query syntax"
# 3. Review commit history
git log --oneline origin/main..HEAD
# 4. Optionally clean up history with interactive rebase
git rebase -i origin/main
# Squash related commits if needed
# 5. Create detailed PR
git push -u origin feature/advanced-search
gh pr create \
--title "feat(search): implement advanced search functionality" \
--body "$(cat <<'EOF'
## Summary
Implements advanced search with boolean operators, filters, and full-text indexing.
## Features
- Full-text search with boolean operators (AND, OR, NOT)
- Category and date range filters
- Real-time search suggestions
- Search result highlighting
- Performance: <50ms for typical queries
## Changes
- Add search infrastructure (parser, indexer)
- Add search API endpoints
- Add search UI components (SearchBar, SearchFilters)
- Add comprehensive test coverage (unit + integration)
- Add documentation for search API
## Testing
- [x] Unit tests for all components
- [x] Integration tests for search flow
- [x] Performance benchmarks
- [x] Manual testing with various queries
## Screenshots
[Add screenshots of search UI]
Closes #187, #234
EOF
)"
Agents should create commits when:
Agents should NOT automatically commit when:
Delegate to git-expert agent for:
Use git-workflow-skills (this skill) for:
Workflow for agents creating commits:
Analyze changes:
git status
git diff --cached
Determine commit type:
featfixdocsrefactortestIdentify scope:
src/auth/ ā authSearchBar.tsx ā searchapi/users.ts ā apiWrite subject line:
Add body if needed:
Add footer:
Closes #123BREAKING CHANGE: ...Co-authored-by: Claude <noreply@anthropic.com>Example agent workflow:
# Agent analyzes changes
git diff --cached
# Changes show:
# - New file: src/components/SearchBar.tsx
# - Modified: src/api/search.ts
# - Modified: src/types/search.ts
# Agent determines:
# Type: feat (new component)
# Scope: search (from file paths)
# Subject: add search bar component with autocomplete
# Agent creates commit:
git commit -m "$(cat <<'EOF'
feat(search): add search bar component with autocomplete
Implement search bar with real-time autocomplete suggestions.
Includes debouncing for performance and keyboard navigation support.
š¤ Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
Workflow for agents creating PRs:
Analyze all commits in branch:
git log origin/main..HEAD
git diff origin/main...HEAD
Summarize changes:
Identify related issues:
Create test plan:
Generate PR using template (see PR/MR Best Practices section)
This skill includes validation and generation scripts for git workflows:
See scripts/README.md for usage details.
Additional reference documentation:
These references provide additional context and examples without cluttering the main skill document.
Before completing any git workflow operation, verify:
This skill provides comprehensive guidance for professional git workflows. Key takeaways:
Refer to the reference documents for detailed examples and comparisons.
