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:

# Update from main frequently
git checkout main
git pull origin main
git checkout feat/user-authentication
git rebase main  # Keep history linear

4. Push and create PR:

git push -u origin feat/user-authentication
# Create PR on GitHub

5. After PR approval:

# Squash merge or merge commit to main
# Delete feature branch immediately
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 feature
fix/authentication-timeout - Bug fix
refactor/database-queries - Code refactoring
docs/api-endpoints - Documentation
test/user-service - Tests only
chore/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 changes
fix(ui): - UI fix
refactor(database): - Database refactoring
feat(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                    # See working tree status
git diff                      # Show unstaged changes
git diff --staged            # Show staged changes

Make commits:

git add <file>               # Stage specific file
git add .                    # Stage all changes
git commit -m "type: message" # Commit with message
git commit                   # Open editor for commit message

Sync with remote:

git pull origin main         # Fetch and merge from main
git push origin <branch>     # Push branch to remote
git fetch origin            # Fetch without merging

Branch management:

git branch                   # List local branches
git branch -a               # List all branches (including remote)
git checkout -b <branch>    # Create and switch to branch
git checkout <branch>       # Switch to existing branch
git branch -d <branch>      # Delete local branch

Workflow Commands

Update feature branch from main:

git checkout main
git pull origin main
git checkout feat/my-feature
git rebase main             # Keep linear history
# Resolve conflicts if any
git push --force-with-lease origin feat/my-feature

Amend last commit:

git commit --amend          # Edit last commit message/content
git commit --amend --no-edit # Add changes to last commit

Unstage changes:

git reset HEAD <file>       # Unstage file
git reset HEAD .           # Unstage all

Discard changes:

git checkout -- <file>      # Discard changes in file
git restore <file>         # Modern alternative
git clean -fd              # Remove untracked files/dirs

Stash changes:

git stash                   # Stash working changes
git stash push -m "message" # Stash with message
git stash list             # List stashes
git stash apply            # Apply most recent stash
git stash pop              # Apply and remove stash
git stash drop             # Remove stash

View history:

git log                     # Show commit history
git log --oneline          # Compact history
git log --graph            # Visual branch graph
git log -p                 # Show patches
git log --follow <file>    # Follow file history

Compare branches:

git diff main..feat/branch  # Changes in branch vs main
git log main..feat/branch   # Commits in branch not in main

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:

Code follows project conventions
Changes are well-tested
No unnecessary changes included
Documentation updated if needed
Commit messages follow Conventional Commits
No security vulnerabilities introduced
Performance implications considered

Addressing Review Feedback

1. Make requested changes:

# Make changes in your branch
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:

# Delete remote branch (or use GitHub auto-delete)
git push origin --delete feat/user-authentication

# Update local main
git checkout main
git pull origin main

# Delete local branch
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:

Require pull request before merging
Require approvals (at least 1)
Require status checks to pass
Require branches to be up to date

Recommended:

Require conversation resolution
Require linear history
Do not allow bypassing settings
Automatically delete head branches

Optional (for teams):

Require review from Code Owners
Restrict push access
Require signed commits

Handling Merge Conflicts

When conflicts occur

During merge:

git merge main
# CONFLICT in file.py

During rebase:

git rebase main
# CONFLICT in file.py

Resolution process

1. View conflicts:

git status  # Shows conflicted files

2. Open conflicted file:

<<<<<<< HEAD
# Your changes
=======
# Their changes
>>>>>>> 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:

# For merge:
git commit

# For rebase:
git rebase --continue

6. Abort if needed:

# For merge:
git merge --abort

# For rebase:
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

# 1. Ensure main is current
git checkout main
git pull origin main

# 2. Create feature branch
git checkout -b feat/new-feature

# 3. Make changes and commit
git add .
git commit -m "feat(module): add new functionality"

# 4. Push and create PR
git push -u origin feat/new-feature
# Create PR on GitHub

Quick Bug Fix

# 1. Create fix branch from main
git checkout main
git pull origin main
git checkout -b fix/bug-description

# 2. Fix and commit
git add .
git commit -m "fix(module): resolve bug description"

# 3. Push and create PR
git push -u origin fix/bug-description
# Create PR with "Fixes #issue-number"

Updating Branch from Main

# Option 1: Rebase (preferred for clean history)
git checkout feat/my-feature
git fetch origin
git rebase origin/main
# Resolve conflicts if any
git push --force-with-lease origin feat/my-feature

# Option 2: Merge (preserves branch history)
git checkout feat/my-feature
git fetch origin
git merge origin/main
git push origin feat/my-feature

Splitting Large Branch

# If branch too large, split into smaller PRs:

# 1. Create first sub-feature
git checkout -b feat/user-auth-part1 feat/user-auth
git rebase -i main  # Mark only first commits as pick
git push -u origin feat/user-auth-part1
# Create PR for part 1

# 2. After part 1 merges, continue with part 2
git checkout main
git pull origin main
git checkout -b feat/user-auth-part2 feat/user-auth
# Continue with remaining commits

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"

# Move commit to new branch
git branch feat/new-branch    # Create branch at current commit
git reset --hard HEAD~1       # Remove commit from current branch
git checkout feat/new-branch  # Switch to new branch

"I need to undo last commit"

# Keep changes, undo commit
git reset --soft HEAD~1

# Undo commit and changes
git reset --hard HEAD~1

# Undo but keep as uncommitted
git reset HEAD~1

"I committed sensitive data"

# Remove from last commit
git rm --cached <file>
git commit --amend
git push --force-with-lease

# Remove from history (use tools like BFG Repo-Cleaner)
# Then rotate any exposed secrets!

"My branch diverged from main"

# Rebase to fix
git fetch origin
git rebase origin/main
# Resolve conflicts
git push --force-with-lease origin feat/my-branch

"I need to change commit message"

# Last commit only
git commit --amend

# Older commits
git rebase -i HEAD~3  # For last 3 commits
# Change 'pick' to 'reword' for commits to change

"Rebase went wrong"

# Abort and start over
git rebase --abort

# Or if already messed up
git reflog  # Find previous state
git reset --hard <previous-commit>

See references/troubleshooting.md for more scenarios.

Advanced Git Topics

Interactive Rebase

# Rebase last 3 commits interactively
git rebase -i HEAD~3

# Options:
# pick - keep commit
# reword - change commit message
# edit - pause to amend commit
# squash - combine with previous commit
# fixup - like squash but discard message
# drop - remove commit

Cherry-Pick

# Apply specific commit to current branch
git cherry-pick <commit-hash>

# Cherry-pick multiple commits
git cherry-pick <commit1> <commit2>

# Cherry-pick range
git cherry-pick <start>..<end>

Reflog (recover lost commits)

# View reference log
git reflog

# Find lost commit
git reflog show HEAD

# Restore to previous state
git reset --hard HEAD@{2}

Bisect (find bug-introducing commit)

# Start bisect
git bisect start
git bisect bad              # Current commit is bad
git bisect good <commit>    # Last known good commit

# Git will checkout middle commit, test it
git bisect good  # If works
git bisect bad   # If broken

# Repeat until found
git bisect reset  # Return to original state

Worktrees (work on multiple branches)

# Create worktree for different branch
git worktree add ../project-feature feat/feature

# List worktrees
git worktree list

# Remove worktree
git worktree remove ../project-feature

See references/advanced-git.md for detailed coverage.

GitHub Actions Integration

Basic CI Workflow

# .github/workflows/ci.yml
name: CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install
        run: npm ci
      - name: Test
        run: npm test
      - name: Lint
        run: npm run lint

Conventional Commit Validation

# .github/workflows/commit-lint.yml
name: Commit Lint

on: [pull_request]

jobs:
  lint-commits:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: wagoid/commitlint-github-action@v5

See examples/github-actions/ for more workflow examples.

Tools and Resources

Recommended Tools

Commit message helpers:

commitizen - Interactive commit message builder
commitlint - Validate commit messages
husky - 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:

# User info
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Editor
git config --global core.editor "vim"

# Default branch
git config --global init.defaultBranch main

# Rebase by default
git config --global pull.rebase true

# Helpful aliases
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                      # Check status
git add .                       # Stage changes
git commit -m "type: message"  # Commit
git pull origin main           # Update from main
git push origin branch         # Push changes

Branch Workflow:

git checkout main              # Switch to main
git pull origin main           # Update
git checkout -b feat/name      # Create branch
# ... make changes ...
git push -u origin feat/name   # Push and create PR

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               # Fetch updates
git rebase origin/main         # Rebase on main
git push --force-with-lease    # Force push safely

Remember: Small commits, frequent integration, clear messages, short-lived branches, and always keep main deployable. This is the path to professional version control.

Install Skill

SKILL.md

Version Control & Git Workflow Skill

Core Philosophy

Trunk-Based Development Workflow

The Main Branch

Feature Branch Workflow

Branch Naming Conventions

Conventional Commits

Format

Types

Scope

Subject Rules

Body (Optional)

Footer (Optional)

Examples

Essential Git Commands

Daily Commands

Workflow Commands

GitHub Pull Request Workflow

Creating a PR

Reviewing PRs

Addressing Review Feedback

Merging PRs

Branch Protection Rules

Handling Merge Conflicts

When conflicts occur

Resolution process

Preventing conflicts

Common Workflows

Starting New Feature

Quick Bug Fix

Updating Branch from Main

Splitting Large Branch

Git Best Practices

Commit Practices

Branch Practices

Collaboration Practices

Repository Hygiene

Troubleshooting Common Issues

"I committed to wrong branch"

"I need to undo last commit"

"I committed sensitive data"

"My branch diverged from main"

"I need to change commit message"

"Rebase went wrong"

Advanced Git Topics

Interactive Rebase

Cherry-Pick

Reflog (recover lost commits)

Bisect (find bug-introducing commit)

Worktrees (work on multiple branches)

GitHub Actions Integration

Basic CI Workflow

Conventional Commit Validation

Tools and Resources

Recommended Tools

Configuration

Learning Resources

When to Use This Skill

Quick Reference