| name | managing-git |
| description | 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.
When to Use This Skill
- Setting up branching strategies
- Writing commit messages
- Handling merges and conflicts
- Managing releases
- Code review workflows
- Maintaining clean history
Branching Strategies
Git Flow
main โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโถ
\ / /
release \โโโโโโโโโโโโโโโโโโ /
\ /
develop โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโถ
\ \ \ \
feature \โโโโโโโโโโโโโโโโ \โโโโโโโโ
\ \
hotfix \ \โโโโโโโโโถ main
| Branch | Purpose | Branches From | Merges Into |
|---|
main | Production code | - | - |
develop | Integration | main | release |
feature/* | New features | develop | develop |
release/* | Release prep | develop | main, develop |
hotfix/* | Production fixes | main | main, develop |
Use when: Scheduled releases, multiple versions supported
GitHub Flow
main โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโถ
\ / \ / \ /
feature โโโ โโโ โโโ
PR PR PR
| Branch | Purpose |
|---|
main | Always deployable |
feature/* | All changes (features, fixes) |
Use when: Continuous deployment, simple workflow
Trunk-Based Development
main โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโถ
โ โ โ โ โ โ โ โ โ โ
โ โ โ โ โ โ โ โ โ โ
Small, frequent commits (often direct to main)
Use when: High trust teams, strong CI/CD, frequent deploys
Commit Message Conventions
Conventional Commits
<type>(<scope>): <subject>
<body>
<footer>
Types
| Type | Description | Example |
|---|
feat | New feature | feat(auth): add OAuth2 login |
fix | Bug fix | fix(api): handle null response |
docs | Documentation | docs(readme): update setup steps |
style | Formatting | style: fix indentation |
refactor | Code restructuring | refactor(db): simplify query builder |
test | Adding tests | test(user): add registration tests |
chore | Maintenance | chore(deps): update lodash |
perf | Performance | perf(search): add index on email |
ci | CI/CD changes | ci: add Node 18 to matrix |
Good vs Bad Commits
BAD:
- "fix"
- "update code"
- "WIP"
- "changes"
- "asdfasdf"
GOOD:
- "fix(auth): prevent session timeout on idle"
- "feat(cart): add quantity validation"
- "refactor(api): extract common error handling"
Commit Body Guidelines
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
git checkout main
git pull origin main
git checkout -b feature/AUTH-123-add-login
git add -p
git commit -m "feat(auth): add login form"
git fetch origin
git rebase origin/main
git merge origin/main
git push -u origin feature/AUTH-123-add-login
Useful Commands
| Command | Purpose |
|---|
git stash | Save uncommitted changes temporarily |
git stash pop | Restore stashed changes |
git commit --amend | Modify last commit |
git rebase -i HEAD~3 | Interactive rebase (squash, reorder) |
git cherry-pick <sha> | Apply specific commit |
git bisect | Binary search for bug introduction |
git reflog | View all HEAD movements (recovery) |
Cleanup Commands
git branch --merged | grep -v main | xargs git branch -d
git fetch --prune
git clean -fd
Handling Conflicts
Conflict Resolution Flow
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
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
git checkout -b release/v1.2.0 develop
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
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
npm run lint
if [ $? -ne 0 ]; then
echo "Linting failed. Please fix errors."
exit 1
fi
npm test
if [ $? -ne 0 ]; then
echo "Tests failed. Please fix before committing."
exit 1
fi
Using Husky (Node.js)
{
"husky": {
"hooks": {
"pre-commit": "lint-staged",
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
}
}
Troubleshooting
Common Issues
| Problem | Solution |
|---|
| Accidental commit to main | git reset HEAD~1 (before push) |
| Wrong branch | git stash, switch, git stash pop |
| Need to undo merge | git revert -m 1 <merge-commit> |
| Lost commits | git reflog to find, git cherry-pick |
| Large file committed | git filter-branch or BFG Repo-Cleaner |
Recovery Commands
git reset --soft HEAD~1
git reset --hard HEAD~1
git reflog
git checkout -b recovered-branch <sha>
git revert <sha>
Anti-Patterns to Avoid
- Force pushing to shared branches - Breaks others' history
- Giant commits - Hard to review, hard to bisect
- Vague commit messages - "fix" tells nothing
- Long-lived branches - Merge conflict hell
- Committing generated files - Bloats repo, causes conflicts
- Committing secrets - Security risk (even after removal)
- Rebasing public history - Breaks collaborators
- Ignoring CI failures - Broken windows effect
Quick Reference
BRANCHES:
main โ Production (protected)
develop โ Integration (Git Flow)
feature/* โ New work
fix/* โ Bug fixes
hotfix/* โ Production emergencies
COMMITS:
feat(scope): add feature
fix(scope): fix bug
docs(scope): update docs
refactor(scope): restructure code
DAILY FLOW:
git checkout -b feature/ticket-desc
git add -p && git commit
git rebase origin/main
git push -u origin feature/ticket-desc
VERSIONING:
MAJOR.MINOR.PATCH
Breaking.Feature.Bugfix
