Guides git workflows, branching strategies, commit conventions, and version control best practices. Use when managing repositories, creating branches, or handling merges.
Guides git workflows, branching strategies, commit conventions, and version control best practices. Use when managing repositories, creating branches, or handling merges.
license
MIT
compatibility
opencode
metadata
{"category":"workflow","audience":"developers"}
Managing Git
Best practices for version control, branching strategies, and collaborative development.
fix(payment): prevent double charge on retry
The payment gateway timeout was causing the retry logic to submit
duplicate charges. Added idempotency key to prevent double-processing.
Closes #1234
First line: 50 chars max, imperative mood
Body: Wrap at 72 chars, explain why, not what
Footer: Reference issues, breaking changes
Branch Naming Conventions
Pattern
<type>/<ticket>-<short-description>
Examples
Type
Example
Feature
feature/AUTH-123-add-oauth-login
Bugfix
fix/CART-456-quantity-validation
Hotfix
hotfix/PROD-789-memory-leak
Chore
chore/update-dependencies
Docs
docs/api-documentation
Branch Rules
Lowercase with hyphens
Include ticket number when available
Keep short but descriptive
Delete after merge
Git Workflow Commands
Daily Workflow
# Start new feature
git checkout main
git pull origin main
git checkout -b feature/AUTH-123-add-login
# Work on feature
git add -p # Stage hunks interactively
git commit -m "feat(auth): add login form"# Keep up to date
git fetch origin
git rebase origin/main # Preferred: clean history# OR
git merge origin/main # Alternative: preserves context# Push and create PR
git push -u origin feature/AUTH-123-add-login
1. Identify conflicts
git status
2. Open conflicted files
<<<<<<< HEAD
your changes
=======
their changes
>>>>>>> feature-branch
3. Resolve (keep one, combine, or rewrite)
4. Mark resolved
git add <resolved-file>
5. Continue
git rebase --continue # if rebasing
git commit # if merging
Prevention Strategies
Small, frequent merges - Reduce conflict scope
Communication - Coordinate on shared files
Feature flags - Reduce long-lived branches
Clear ownership - Minimize overlapping work
Pull Request Best Practices
PR Checklist
Branch is up to date with main
Tests pass locally
Linting passes
Self-review completed
Documentation updated
Ticket/issue linked
Screenshots for UI changes
PR Size Guidelines
Size
Lines Changed
Review Time
Recommendation
Small
1-100
15 min
Ideal
Medium
100-400
30-60 min
Acceptable
Large
400+
1+ hour
Split if possible
PR Description Template
## Summary
Brief description of changes
## Changes- Added X
- Modified Y
- Removed Z
## Testing- [ ] Unit tests added
- [ ] Manual testing done
## Screenshots (if applicable)
[Before/After images]
## Related Issues
Closes #123
Release Management
Semantic Versioning
MAJOR.MINOR.PATCH
│ │ │
│ │ └── Bug fixes (backward compatible)
│ └── New features (backward compatible)
└── Breaking changes
Release Process
# Create release branch
git checkout -b release/v1.2.0 develop
# Bump version, update changelog# ... make changes ...# Merge to main and tag
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
# Merge back to develop
git checkout develop
git merge release/v1.2.0
Changelog Format
# Changelog## [1.2.0] - 2024-01-15### Added- OAuth2 authentication support
### Changed- Improved error messages
### Fixed- Memory leak in cache handler
### Deprecated- Old authentication method (use OAuth2)
### Removed- Legacy API v1 endpoints
Git Hooks
Common Hooks
Hook
Timing
Use Case
pre-commit
Before commit
Linting, formatting
commit-msg
After message
Validate message format
pre-push
Before push
Run tests
post-merge
After merge
Install dependencies
Example pre-commit
#!/bin/sh# .git/hooks/pre-commit# Run linter
npm run lint
if [ $? -ne 0 ]; thenecho"Linting failed. Please fix errors."exit 1
fi# Run tests
npm testif [ $? -ne 0 ]; thenecho"Tests failed. Please fix before committing."exit 1
fi
