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

🔄 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

Conventional Commits

Format

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

[optional body]

[optional footer(s)]

Types

Examples

bash
1# Feature with scope
2feat(auth): add OAuth2 login support
3
4# Bug fix with body
5fix(api): handle null response from payment gateway
6
7The payment gateway occasionally returns null instead of
8an error object. Added null check before processing.
9
10Fixes #123
11
12# Breaking change
13feat(api)!: change user endpoint response format
14
15BREAKING CHANGE: The /api/users endpoint now returns
16a paginated response object instead of an array.
17
18# Multiple footers
19fix(security): upgrade vulnerable dependency
20
21Reviewed-by: John Doe
22Refs: 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

bash
1# BAD: Multiple unrelated changes
2git add .
3git commit -m "various fixes and updates"
4
5# GOOD: Separate logical changes
6git add src/auth/
7git commit -m "feat(auth): implement password reset flow"
8
9git add tests/auth/
10git commit -m "test(auth): add password reset tests"
11
12git add package.json package-lock.json
13git commit -m "chore(deps): update authentication libraries"

Interactive Staging

bash
1# Stage specific hunks
2git add -p
3
4# Stage specific files interactively
5git 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

bash
1# Use editor for complex commits
2git commit
3
4# Quick commit with message
5git commit -m "fix(api): correct rate limit calculation"

Merging vs Rebasing

When to Merge

bash
1# Merge preserves history
2git checkout main
3git merge feature/user-auth --no-ff
4
5# Creates merge commit:
6# *   Merge branch 'feature/user-auth'
7# |\
8# | * feat: add login endpoint
9# | * feat: add user model
10# |/
11# *   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

bash
1# Rebase creates linear history
2git checkout feature/user-auth
3git rebase main
4
5# Results in linear history:
6# * feat: add login endpoint
7# * feat: add user model
8# * 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

bash
1# Squash, reorder, edit last 5 commits
2git rebase -i HEAD~5
3
4# In editor:
5pick abc1234 feat: add user model
6squash def5678 fix: typo in user model
7pick ghi9012 feat: add login endpoint
8reword jkl3456 feat: add logout endpoint
9drop mno7890 WIP: debugging
10
11# Commands:
12# p, pick   = use commit
13# r, reword = use commit but edit message
14# e, edit   = use commit but stop for amending
15# s, squash = meld into previous commit
16# f, fixup  = like squash but discard message
17# d, drop   = remove commit

Pull Request Workflow

Before Creating PR

bash
1# 1. Ensure branch is up to date
2git fetch origin
3git rebase origin/main
4
5# 2. Run tests locally
6npm test  # or equivalent
7
8# 3. Check for linting issues
9npm run lint  # or equivalent
10
11# 4. Review your changes
12git diff origin/main...HEAD
13git log origin/main..HEAD --oneline

PR Size Guidelines

PR Description Template

markdown
1## Summary
2Brief description of changes (1-3 bullet points)
3
4## Changes
5- Added X feature
6- Modified Y component
7- Fixed Z bug
8
9## Testing
10- [ ] Unit tests pass
11- [ ] Integration tests pass
12- [ ] Manual testing completed
13
14## Screenshots (if UI changes)
15[Before/After screenshots]
16
17## Related Issues
18Closes #123
19Refs #456

Conflict Resolution

Understanding Conflicts

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

Resolution Strategies

bash
1# 1. Keep current branch version
2git checkout --ours path/to/file
3
4# 2. Keep incoming version
5git checkout --theirs path/to/file
6
7# 3. Manual resolution
8# Edit file, then:
9git add path/to/file
10git 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

bash
1# Identity
2git config --global user.name "Your Name"
3git config --global user.email "your.email@example.com"
4
5# Default branch
6git config --global init.defaultBranch main
7
8# Editor
9git config --global core.editor "code --wait"
10
11# Diff tool
12git config --global diff.tool vscode
13git config --global difftool.vscode.cmd 'code --wait --diff $LOCAL $REMOTE'
14
15# Merge tool
16git config --global merge.tool vscode
17git config --global mergetool.vscode.cmd 'code --wait $MERGED'
18
19# Auto-correct typos
20git config --global help.autocorrect 10
21
22# Prune deleted remote branches
23git config --global fetch.prune true
24
25# Default push behavior
26git config --global push.default current
27git config --global push.autoSetupRemote true

Useful Aliases

bash
1# Add to ~/.gitconfig
2[alias]
3    # Status shortcuts
4    st = status -sb
5
6    # Log formats
7    lg = log --oneline --graph --decorate -20
8    lga = log --oneline --graph --decorate --all -20
9
10    # Branch operations
11    co = checkout
12    cob = checkout -b
13    br = branch -vv
14    brd = branch -d
15
16    # Commit shortcuts
17    ci = commit
18    ca = commit --amend
19    can = commit --amend --no-edit
20
21    # Diff shortcuts
22    df = diff
23    dfs = diff --staged
24
25    # Undo operations
26    unstage = reset HEAD --
27    uncommit = reset --soft HEAD~1
28
29    # Show recent branches
30    recent = for-each-ref --sort=-committerdate refs/heads/ --format='%(refname:short) - %(committerdate:relative)'
31
32    # Clean merged branches
33    cleanup = "!git branch --merged | grep -v '\\*\\|main\\|master\\|develop' | xargs -n 1 git branch -d"

Common Operations

Undo Operations

bash
1# Undo last commit (keep changes staged)
2git reset --soft HEAD~1
3
4# Undo last commit (keep changes unstaged)
5git reset HEAD~1
6
7# Undo last commit (discard changes)
8git reset --hard HEAD~1
9
10# Undo uncommitted changes to file
11git checkout -- path/to/file
12
13# Undo staged changes
14git reset HEAD path/to/file
15
16# Revert a pushed commit (creates new commit)
17git revert <commit-sha>

Stashing

bash
1# Stash current changes
2git stash
3
4# Stash with message
5git stash save "WIP: feature description"
6
7# Include untracked files
8git stash -u
9
10# List stashes
11git stash list
12
13# Apply most recent stash
14git stash pop
15
16# Apply specific stash
17git stash apply stash@{2}
18
19# Drop stash
20git stash drop stash@{0}

Cherry-Picking

bash
1# Apply single commit
2git cherry-pick <commit-sha>
3
4# Apply multiple commits
5git cherry-pick <sha1> <sha2> <sha3>
6
7# Apply range of commits
8git cherry-pick <sha1>^..<sha2>
9
10# Cherry-pick without committing
11git cherry-pick -n <commit-sha>

Bisect (Find Bug Introduction)

bash
1# Start bisect
2git bisect start
3
4# Mark current as bad
5git bisect bad
6
7# Mark known good commit
8git bisect good <commit-sha>
9
10# Git checks out middle commit; test and mark
11git bisect good  # or bad
12
13# When done
14git bisect reset

Safety Guidelines

Never Do on Shared Branches

bash
1# NEVER force push to main/develop
2git push --force origin main  # DANGEROUS
3
4# NEVER rebase public branches
5git rebase main  # on shared feature branch
6
7# NEVER reset pushed commits
8git reset --hard HEAD~3  # if already pushed

Safe Alternatives

bash
1# Instead of force push, use:
2git push --force-with-lease  # Fails if remote changed
3
4# Instead of rebase on shared branch, use:
5git merge origin/main
6
7# Instead of reset pushed commits, use:
8git 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

Additional Resources

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