| name | version-control |
| description | Expert guidance for Git version control, trunk-based development workflows, and GitHub best practices.
Emphasizes Conventional Commits for clean history, short-lived feature branches, frequent integration,
and professional collaboration patterns. Use when users need help with git commands, branching strategies,
commit messages, PRs, merge conflicts, or git troubleshooting. Triggers include 'git,' 'commit,' 'branch,'
'merge,' 'rebase,' 'PR,' 'pull request,' or version control questions.
|
| allowed-tools | ["*"] |
Version Control & Git Workflow Skill
Guide users through professional version control practices using Git with trunk-based development, Conventional Commits, and GitHub integration.
Core Philosophy
Trunk-Based Development:
- Keep main branch always deployable
- Short-lived feature branches (days, not weeks)
- Frequent integration to main
- Small, incremental changes
- Continuous integration mindset
Conventional Commits:
- Structured, semantic commit messages
- Enables automated tooling (changelogs, versioning)
- Clear intent and scope in history
- Searchable, filterable commits
GitHub Integration:
- Pull requests for code review
- Branch protection for main
- CI/CD with GitHub Actions
- Clear PR descriptions and discussions
Trunk-Based Development Workflow
The Main Branch
- Always deployable - Main branch should always be in working state
- Protected - Require PRs, reviews, passing CI
- Source of truth - All branches stem from and merge back to main
- No long-lived branches - Avoid develop, staging branches
Feature Branch Workflow
1. Start from main:
git checkout main
git pull origin main
git checkout -b feat/user-authentication
2. Make small, focused changes:
- One feature/fix per branch
- Commit frequently with Conventional Commits
- Keep branch lifespan short (1-3 days ideal)
3. Stay synchronized:
git checkout main
git pull origin main
git checkout feat/user-authentication
git rebase main
4. Push and create PR:
git push -u origin feat/user-authentication
5. After PR approval:
git checkout main
git pull origin main
git branch -d feat/user-authentication
Branch Naming Conventions
Pattern: <type>/<short-description>
Types match Conventional Commit types:
feat/add-oauth-login - New featurefix/authentication-timeout - Bug fixrefactor/database-queries - Code refactoringdocs/api-endpoints - Documentationtest/user-service - Tests onlychore/update-dependencies - Maintenance
Keep descriptions short, lowercase, hyphen-separated.
Conventional Commits
Format
<type>(<scope>): <subject>
<body>
<footer>
Required: type, subject
Optional: scope, body, footer
Types
feat: New feature for users
feat(auth): add OAuth2 authentication
fix: Bug fix
fix(api): handle null response in user endpoint
docs: Documentation changes
docs(readme): update installation instructions
style: Code style/formatting (no logic change)
style(components): fix indentation in Button
refactor: Code restructuring (no behavior change)
refactor(database): extract query builder class
perf: Performance improvement
perf(images): implement lazy loading
test: Adding or updating tests
test(auth): add integration tests for login flow
build: Build system or dependencies
build(deps): upgrade React to v18.2
ci: CI/CD configuration
ci(github): add automated deployment workflow
chore: Maintenance tasks
chore(deps): update development dependencies
revert: Revert previous commit
revert: revert "feat(auth): add OAuth2 authentication"
Scope
Optional but recommended. Indicates what part of codebase changed:
feat(api): - API changesfix(ui): - UI fixrefactor(database): - Database refactoringfeat(auth): - Authentication feature
Use project-specific scopes that make sense for your codebase.
Subject Rules
- Use imperative mood: "add" not "added" or "adds"
- No capitalization of first letter
- No period at the end
- Keep under 50 characters
- Complete the sentence: "If applied, this commit will..."
Good:
feat(api): add user profile endpoint
fix(auth): prevent token expiration race condition
Bad:
feat(api): Added user profile endpoint.
fix(auth): Fixes a bug
Update stuff
Body (Optional)
- Explain what and why, not how
- Wrap at 72 characters
- Separate from subject with blank line
- Use bullet points for multiple points
feat(search): implement full-text search
- Add PostgreSQL full-text search indexes
- Create search API endpoint with pagination
- Implement search result ranking by relevance
This enables users to search across all content with better
performance than previous LIKE queries.
Footer (Optional)
Breaking changes:
feat(api): change authentication endpoint
BREAKING CHANGE: /auth/login moved to /api/v2/auth/login
Issue references:
fix(ui): prevent modal from closing on backdrop click
Fixes #123
Closes #456
Examples
Simple feature:
feat(dashboard): add user activity chart
Bug fix with details:
fix(api): handle network timeout errors
Previously, network timeouts would crash the application.
Now we catch timeout errors and return appropriate error
response to client.
Fixes #789
Breaking change:
feat(api)!: redesign user authentication
BREAKING CHANGE: Auth tokens now expire after 1 hour instead
of 24 hours. Clients must implement token refresh logic.
Multiple changes:
refactor(database): optimize query performance
- Add indexes on frequently queried columns
- Implement connection pooling
- Cache common queries with Redis
- Update ORM configuration for better performance
These changes reduce average query time from 200ms to 50ms.
See references/conventional-commits.md for comprehensive guide.
Essential Git Commands
Daily Commands
Check status:
git status
git diff
git diff --staged
Make commits:
git add <file>
git add .
git commit -m "type: message"
git commit
Sync with remote:
git pull origin main
git push origin <branch>
git fetch origin
Branch management:
git branch
git branch -a
git checkout -b <branch>
git checkout <branch>
git branch -d <branch>
Workflow Commands
Update feature branch from main:
git checkout main
git pull origin main
git checkout feat/my-feature
git rebase main
git push --force-with-lease origin feat/my-feature
Amend last commit:
git commit --amend
git commit --amend --no-edit
Unstage changes:
git reset HEAD <file>
git reset HEAD .
Discard changes:
git checkout -- <file>
git restore <file>
git clean -fd
Stash changes:
git stash
git stash push -m "message"
git stash list
git stash apply
git stash pop
git stash drop
View history:
git log
git log --oneline
git log --graph
git log -p
git log --follow <file>
Compare branches:
git diff main..feat/branch
git log main..feat/branch
See references/git-commands.md for complete command reference.
GitHub Pull Request Workflow
Creating a PR
1. Push branch:
git push -u origin feat/user-authentication
2. Create PR on GitHub with:
Title: Use Conventional Commit format
feat(auth): add OAuth2 authentication
Description template:
## Summary
Brief description of changes and motivation.
## Changes
- List key changes
- Use bullet points
- Be specific
## Testing
How to test these changes:
1. Step-by-step instructions
2. Expected behavior
## Screenshots (if UI changes)
[Add screenshots]
## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No breaking changes (or documented)
- [ ] Follows Conventional Commits
3. Request reviewers
4. Link related issues
Reviewing PRs
As reviewer:
- Check code quality and style
- Verify tests are adequate
- Test functionality locally
- Ask questions, suggest improvements
- Approve or request changes
PR review checklist:
Addressing Review Feedback
1. Make requested changes:
git add .
git commit -m "fix(auth): address PR feedback"
git push origin feat/user-authentication
2. Respond to comments
3. Mark conversations as resolved
4. Request re-review
Merging PRs
Merge strategies:
Squash and merge (recommended for most features):
- Combines all commits into one
- Clean main branch history
- Loses detailed commit history
- Good for: Features with many small commits
Merge commit (for collaborative branches):
- Preserves all commits
- Shows branch history
- Can clutter main history
- Good for: Complex features with meaningful commit history
Rebase and merge (for clean branches):
- Applies commits directly to main
- Linear history
- Requires clean branch history
- Good for: Branches with well-crafted commits
After merge:
git push origin --delete feat/user-authentication
git checkout main
git pull origin main
git branch -d feat/user-authentication
See references/github-workflow.md for detailed GitHub guidance.
Branch Protection Rules
Configure on GitHub for main branch:
Required:
Recommended:
Optional (for teams):
Handling Merge Conflicts
When conflicts occur
During merge:
git merge main
During rebase:
git rebase main
Resolution process
1. View conflicts:
git status
2. Open conflicted file:
<<<<<<< HEAD
=======
>>>>>>> main
3. Resolve manually:
- Choose one version, or
- Combine both, or
- Write new solution
4. Mark as resolved:
git add file.py
5. Continue operation:
git commit
git rebase --continue
6. Abort if needed:
git merge --abort
git rebase --abort
Preventing conflicts
- Pull/rebase from main frequently
- Keep branches short-lived
- Coordinate with team on overlapping work
- Make small, focused changes
See references/troubleshooting.md for complex conflict scenarios.
Common Workflows
Starting New Feature
git checkout main
git pull origin main
git checkout -b feat/new-feature
git add .
git commit -m "feat(module): add new functionality"
git push -u origin feat/new-feature
Quick Bug Fix
git checkout main
git pull origin main
git checkout -b fix/bug-description
git add .
git commit -m "fix(module): resolve bug description"
git push -u origin fix/bug-description
Updating Branch from Main
git checkout feat/my-feature
git fetch origin
git rebase origin/main
git push --force-with-lease origin feat/my-feature
git checkout feat/my-feature
git fetch origin
git merge origin/main
git push origin feat/my-feature
Splitting Large Branch
git checkout -b feat/user-auth-part1 feat/user-auth
git rebase -i main
git push -u origin feat/user-auth-part1
git checkout main
git pull origin main
git checkout -b feat/user-auth-part2 feat/user-auth
Git Best Practices
Commit Practices
✅ Do:
- Commit frequently (multiple times per day)
- Keep commits focused (one logical change)
- Write meaningful commit messages
- Follow Conventional Commits format
- Test before committing
- Review changes before committing (
git diff)
❌ Don't:
- Commit broken code to main
- Make giant commits with unrelated changes
- Write vague messages ("fix stuff", "updates")
- Commit commented-out code
- Commit sensitive data (secrets, credentials)
- Force push to main
Branch Practices
✅ Do:
- Keep branches short-lived (days not weeks)
- One feature/fix per branch
- Use descriptive branch names
- Delete branches after merging
- Rebase/merge from main frequently
- Keep main always deployable
❌ Don't:
- Create long-lived feature branches
- Mix multiple features in one branch
- Push directly to main (without PR)
- Leave stale branches
- Let branches get too far behind main
Collaboration Practices
✅ Do:
- Pull before starting work
- Communicate about overlapping work
- Review others' PRs promptly
- Provide constructive feedback
- Respond to review comments
- Use PR templates
- Link issues in PRs
❌ Don't:
- Work on main directly
- Force push to shared branches (without communication)
- Approve PRs without reviewing
- Ignore CI failures
- Merge your own PRs without review
Repository Hygiene
✅ Do:
- Use
.gitignore properly
- Keep repository clean
- Document in README
- Tag releases
- Archive old branches
- Use GitHub releases
❌ Don't:
- Commit build artifacts
- Commit dependencies (unless necessary)
- Commit IDE-specific files
- Commit large binary files
- Let main branch diverge from production
Troubleshooting Common Issues
"I committed to wrong branch"
git branch feat/new-branch
git reset --hard HEAD~1
git checkout feat/new-branch
"I need to undo last commit"
git reset --soft HEAD~1
git reset --hard HEAD~1
git reset HEAD~1
"I committed sensitive data"
git rm --cached <file>
git commit --amend
git push --force-with-lease
"My branch diverged from main"
git fetch origin
git rebase origin/main
git push --force-with-lease origin feat/my-branch
"I need to change commit message"
git commit --amend
git rebase -i HEAD~3
"Rebase went wrong"
git rebase --abort
git reflog
git reset --hard <previous-commit>
See references/troubleshooting.md for more scenarios.
Advanced Git Topics
Interactive Rebase
git rebase -i HEAD~3
Cherry-Pick
git cherry-pick <commit-hash>
git cherry-pick <commit1> <commit2>
git cherry-pick <start>..<end>
Reflog (recover lost commits)
git reflog
git reflog show HEAD
git reset --hard HEAD@{2}
Bisect (find bug-introducing commit)
git bisect start
git bisect bad
git bisect good <commit>
git bisect good
git bisect bad
git bisect reset
Worktrees (work on multiple branches)
git worktree add ../project-feature feat/feature
git worktree list
git worktree remove ../project-feature
See references/advanced-git.md for detailed coverage.
GitHub Actions Integration
Basic CI Workflow
name: CI
on:
pull_request:
branches: [main]
push:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup
uses: actions/setup-node@v4
with:
node-version: '18'
- name: Install
run: npm ci
- name: Test
run: npm test
- name: Lint
run: npm run lint
Conventional Commit Validation
name: Commit Lint
on: [pull_request]
jobs:
lint-commits:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: wagoid/commitlint-github-action@v6
See examples/github-actions/ for more workflow examples.
Tools and Resources
Recommended Tools
Commit message helpers:
commitizen - Interactive commit message buildercommitlint - Validate commit messageshusky - Git hooks for validation
GitHub CLI:
gh pr create --title "feat: add feature" --body "Description"
gh pr checkout 123
gh pr review --approve
gh pr merge --squash
Visual tools:
gitk - Built-in Git GUI- GitKraken, SourceTree - Full-featured GUIs
- VS Code Git integration
- GitHub Desktop
Configuration
Useful git config:
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global core.editor "vim"
git config --global init.defaultBranch main
git config --global pull.rebase true
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.cm commit
git config --global alias.lg "log --oneline --graph --decorate"
Learning Resources
- references/conventional-commits.md - Complete Conventional Commits guide
- references/trunk-based-development.md - Detailed TBD workflow
- references/github-workflow.md - GitHub-specific practices
- references/git-commands.md - Comprehensive command reference
- references/troubleshooting.md - Problem-solving guide
- references/advanced-git.md - Advanced techniques
- examples/ - Example commit messages, PR templates, workflows
- assets/templates/ - Templates for PRs, commits, checklists
When to Use This Skill
Activate for requests involving:
- Git commands and operations
- Branching and merging strategies
- Commit message formatting
- Pull request creation and review
- Merge conflict resolution
- Repository management
- GitHub workflow questions
- Git troubleshooting
- Version control best practices
- Team collaboration with Git
Quick Reference
Daily Commands:
git status
git add .
git commit -m "type: message"
git pull origin main
git push origin branch
Branch Workflow:
git checkout main
git pull origin main
git checkout -b feat/name
git push -u origin feat/name
Conventional Commit:
type(scope): subject
- Use feat, fix, docs, style, refactor, test, chore
- Imperative mood in subject
- Optional body for details
- Optional footer for breaking changes/issues
Stay Updated:
git fetch origin
git rebase origin/main
git push --force-with-lease
Remember: Small commits, frequent integration, clear messages, short-lived branches, and always keep main deployable. This is the path to professional version control.
