scm

name	scm
description	Guide for effective source control management with Git following modern best practices. Covers branching strategies, commit hygiene, PR workflows, and team collaboration patterns. Triggers on "git", "source control", "version control", "branching", "merge", "rebase", "git workflow", "pull request", "commit message", "git history", "git conflict", "git stash", "git cherry-pick", "git bisect", "git blame", "git log", "git diff", "git reset", "git checkout", "git switch", "git restore", "git tag", "git remote", "git fetch", "git pull", "git push", "git branch", "conventional commits", "squash", "force push", "git hooks", "pre-commit", "commit-msg", "gitignore", "git submodule", "git worktree", "feature branch", "trunk based", "git flow", "github flow", "commit and push", "commit changes", "push changes", "push to remote", "commit this", "commit these", "make a commit", "create commit". PROACTIVE: MUST invoke when performing complex Git operations or setting up workflows.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep

ABOUTME: Source control management skill for Git best practices and workflows

ABOUTME: Covers branching, commits, PRs, conflict resolution, and team collaboration

Source Control Management (SCM) Skill

Quick Reference

Principle	Rule
Atomic Commits	One logical change per commit
Conventional Commits	type(scope): description format
Clean History	Rebase before merge for linear history
Branch Naming	type/ticket-description format
PR Size	< 400 lines of code changes
Never Force Push	To shared branches (main, develop)

🔄 RESUMED SESSION CHECKPOINT

When a session is resumed from context compaction, verify Git state:

┌─────────────────────────────────────────────────────────────┐
│  SESSION RESUMED - SCM SKILL VERIFICATION                   │
│                                                             │
│  Before continuing Git operations:                          │
│                                                             │
│  1. Was I in the middle of Git operations?                  │
│     → Check summary for "commit", "merge", "rebase"         │
│                                                             │
│  2. Current repository state:                               │
│     → Run: git status                                       │
│     → Run: git log --oneline -5                             │
│     → Run: git branch -vv                                   │
│                                                             │
│  3. Pending operations:                                     │
│     → Check for: .git/MERGE_HEAD (merge in progress)        │
│     → Check for: .git/rebase-merge (rebase in progress)     │
│     → Check for: .git/CHERRY_PICK_HEAD (cherry-pick)        │
│                                                             │
│  If operation was interrupted:                              │
│  → Complete or abort the pending operation                  │
│  → Verify working directory is clean                        │
│  → Ensure no uncommitted changes are lost                   │
└─────────────────────────────────────────────────────────────┘

Branching Strategies

Git Flow (Traditional)

main ─────●─────────────────●─────────────●──────
          │                 ↑             ↑
          │         merge   │     merge   │
          ↓                 │             │
develop ──●──●──●──●──●─────●──●──●──●────●──────
              │     ↑           │     ↑
              ↓     │           ↓     │
feature/xyz ──●──●──┘   feature/abc ──●──┘

Use when:

• Scheduled releases
• Multiple versions in production
• Formal QA process

Branches:

• main: Production code
• develop: Integration branch
• feature/*: New features
• release/*: Release preparation
• hotfix/*: Emergency fixes

GitHub Flow (Simplified)

main ─────●───────●───────●───────●──────
          │       ↑       │       ↑
          ↓       │       ↓       │
feature ──●──●──●─┘ fix ──●──●────┘

Use when:

• Continuous deployment
• Small teams
• Rapid iteration

Branches:

• main: Always deployable
• feature/*, fix/*, chore/*: Short-lived branches

Trunk-Based Development

main ─────●──●──●──●──●──●──●──●──●──────
          ↑     ↑     ↑     ↑     ↑
          │     │     │     │     │
          └─────┴─────┴─────┴─────┴── Small, frequent commits

Use when:

• Mature CI/CD pipeline
• Feature flags available
• High-trust team

Branch Naming Convention

<type>/<ticket>-<brief-description>

Examples:
- feature/PROJ-123-user-authentication
- fix/PROJ-456-login-timeout
- chore/PROJ-789-update-dependencies
- docs/PROJ-012-api-documentation
- refactor/PROJ-345-extract-service

Type	Purpose
feature/	New functionality
fix/	Bug fixes
chore/	Maintenance tasks
docs/	Documentation only
refactor/	Code restructuring
test/	Test additions
hotfix/	Emergency production fixes

Conventional Commits

Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

Type	Description	Triggers
feat	New feature	Minor version bump
fix	Bug fix	Patch version bump
docs	Documentation only	No version bump
style	Formatting, no code change	No version bump
refactor	Code change, no feature/fix	No version bump
test	Adding/fixing tests	No version bump
chore	Build process, tooling	No version bump
perf	Performance improvement	Patch version bump
ci	CI configuration	No version bump
build	Build system changes	No version bump
revert	Revert previous commit	Varies

Examples

# Feature with scope
feat(auth): add OAuth2 login support

# Bug fix with body
fix(api): handle null response from payment gateway

The payment gateway occasionally returns null instead of
an error object. Added null check before processing.

Fixes #123

# Breaking change
feat(api)!: change user endpoint response format

BREAKING CHANGE: The /api/users endpoint now returns
a paginated response object instead of an array.

# Multiple footers
fix(security): upgrade vulnerable dependency

Reviewed-by: John Doe
Refs: CVE-2024-12345

Commit Best Practices

Atomic Commits

Each commit should:

• Represent ONE logical change
• Be independently revertable
• Pass all tests
• Have a clear, descriptive message

# BAD: Multiple unrelated changes
git add .
git commit -m "various fixes and updates"

# GOOD: Separate logical changes
git add src/auth/
git commit -m "feat(auth): implement password reset flow"

git add tests/auth/
git commit -m "test(auth): add password reset tests"

git add package.json package-lock.json
git commit -m "chore(deps): update authentication libraries"

Interactive Staging

# Stage specific hunks
git add -p

# Stage specific files interactively
git add -i

Commit Message Guidelines

Subject line:

• Max 50 characters
• Imperative mood ("add" not "added")
• No period at end
• Capitalize first word after type

Body (optional):

• Wrap at 72 characters
• Explain WHAT and WHY, not HOW
• Reference issues/tickets

# Use editor for complex commits
git commit

# Quick commit with message
git commit -m "fix(api): correct rate limit calculation"

Merging vs Rebasing

When to Merge

# Merge preserves history
git checkout main
git merge feature/user-auth --no-ff

# Creates merge commit:
# *   Merge branch 'feature/user-auth'
# |\
# | * feat: add login endpoint
# | * feat: add user model
# |/
# *   Previous commit on main

Use merge when:

• Preserving feature branch history is important
• Working with public/shared branches
• Team prefers merge commits

When to Rebase

# Rebase creates linear history
git checkout feature/user-auth
git rebase main

# Results in linear history:
# * feat: add login endpoint
# * feat: add user model
# * Previous commit on main

Use rebase when:

• Cleaning up local commits before PR
• Updating feature branch with main
• Maintaining linear project history

Interactive Rebase for Cleanup

# Squash, reorder, edit last 5 commits
git rebase -i HEAD~5

# In editor:
pick abc1234 feat: add user model
squash def5678 fix: typo in user model
pick ghi9012 feat: add login endpoint
reword jkl3456 feat: add logout endpoint
drop mno7890 WIP: debugging

# Commands:
# p, pick   = use commit
# r, reword = use commit but edit message
# e, edit   = use commit but stop for amending
# s, squash = meld into previous commit
# f, fixup  = like squash but discard message
# d, drop   = remove commit

Pull Request Workflow

Before Creating PR

# 1. Ensure branch is up to date
git fetch origin
git rebase origin/main

# 2. Run tests locally
npm test  # or equivalent

# 3. Check for linting issues
npm run lint  # or equivalent

# 4. Review your changes
git diff origin/main...HEAD
git log origin/main..HEAD --oneline

PR Size Guidelines

Size	Lines Changed	Review Time
XS	< 50	Minutes
S	50-200	< 30 min
M	200-400	< 1 hour
L	400-800	Hours
XL	> 800	Split required

PR Description Template

## Summary
Brief description of changes (1-3 bullet points)

## Changes
- Added X feature
- Modified Y component
- Fixed Z bug

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Screenshots (if UI changes)
[Before/After screenshots]

## Related Issues
Closes #123
Refs #456

Conflict Resolution

Understanding Conflicts

<<<<<<< HEAD (current branch)
const timeout = 5000;
=======
const timeout = 10000;
>>>>>>> feature-branch (incoming changes)

Resolution Strategies

# 1. Keep current branch version
git checkout --ours path/to/file

# 2. Keep incoming version
git checkout --theirs path/to/file

# 3. Manual resolution
# Edit file, then:
git add path/to/file
git rebase --continue  # or git merge --continue

Prevention Strategies

• Pull/rebase frequently
• Keep branches short-lived
• Communicate about shared files
• Use code owners for critical paths

Git Configuration

Essential Configuration

# Identity
git config --global user.name "Your Name"
git config --global user.email "[e-mail]"

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

# Editor
git config --global core.editor "code --wait"

# Diff tool
git config --global diff.tool vscode
git config --global difftool.vscode.cmd 'code --wait --diff $LOCAL $REMOTE'

# Merge tool
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'

# Auto-correct typos
git config --global help.autocorrect 10

# Prune deleted remote branches
git config --global fetch.prune true

# Default push behavior
git config --global push.default current
git config --global push.autoSetupRemote true

Useful Aliases

# Add to ~/.gitconfig
[alias]
    # Status shortcuts
    st = status -sb

    # Log formats
    lg = log --oneline --graph --decorate -20
    lga = log --oneline --graph --decorate --all -20

    # Branch operations
    co = checkout
    cob = checkout -b
    br = branch -vv
    brd = branch -d

    # Commit shortcuts
    ci = commit
    ca = commit --amend
    can = commit --amend --no-edit

    # Diff shortcuts
    df = diff
    dfs = diff --staged

    # Undo operations
    unstage = reset HEAD --
    uncommit = reset --soft HEAD~1

    # Show recent branches
    recent = for-each-ref --sort=-committerdate refs/heads/ --format='%(refname:short) - %(committerdate:relative)'

    # Clean merged branches
    cleanup = "!git branch --merged | grep -v '\\*\\|main\\|master\\|develop' | xargs -n 1 git branch -d"

Common Operations

Undo Operations

# Undo last commit (keep changes staged)
git reset --soft HEAD~1

# Undo last commit (keep changes unstaged)
git reset HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Undo uncommitted changes to file
git checkout -- path/to/file

# Undo staged changes
git reset HEAD path/to/file

# Revert a pushed commit (creates new commit)
git revert <commit-sha>

Stashing

# Stash current changes
git stash

# Stash with message
git stash save "WIP: feature description"

# Include untracked files
git stash -u

# List stashes
git stash list

# Apply most recent stash
git stash pop

# Apply specific stash
git stash apply stash@{2}

# Drop stash
git stash drop stash@{0}

Cherry-Picking

# Apply single commit
git cherry-pick <commit-sha>

# Apply multiple commits
git cherry-pick <sha1> <sha2> <sha3>

# Apply range of commits
git cherry-pick <sha1>^..<sha2>

# Cherry-pick without committing
git cherry-pick -n <commit-sha>

Bisect (Find Bug Introduction)

# Start bisect
git bisect start

# Mark current as bad
git bisect bad

# Mark known good commit
git bisect good <commit-sha>

# Git checks out middle commit; test and mark
git bisect good  # or bad

# When done
git bisect reset

Safety Guidelines

Never Do on Shared Branches

# NEVER force push to main/develop
git push --force origin main  # DANGEROUS

# NEVER rebase public branches
git rebase main  # on shared feature branch

# NEVER reset pushed commits
git reset --hard HEAD~3  # if already pushed

Safe Alternatives

# Instead of force push, use:
git push --force-with-lease  # Fails if remote changed

# Instead of rebase on shared branch, use:
git merge origin/main

# Instead of reset pushed commits, use:
git revert <sha>

Checklist

Before committing:

• Changes are atomic (one logical change)
• Commit message follows conventional format
• Tests pass locally
• No debug code or console.logs
• No secrets or credentials
• Branch is up to date with target

Before creating PR:

• Rebased on latest main/develop
• All commits have meaningful messages
• PR is appropriately sized (< 400 lines)
• Description explains what and why
• Related issues are linked
• CI checks pass

Anti-Patterns to Avoid

Anti-Pattern	Problem	Solution
git add . blindly	Commits unintended files	Use git add -p or specific files
"WIP" commits	Unclear history	Squash before merge
Force push to shared	Overwrites team work	Use --force-with-lease
Long-lived branches	Merge conflicts	Keep branches < 1 week
Large PRs	Slow reviews, bugs	Split into smaller PRs
Merge commits locally	Messy history	Rebase for updates
Ignoring CI failures	Broken main branch	Fix before merge

Additional Resources

• Pro Git Book
• Conventional Commits
• Git Flight Rules
• Oh Shit, Git!?!