version-control

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@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

# .github/workflows/commit-lint.yml
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 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.