Git Mastery Suite

Purpose

Git is a "whole can of worms" requiring deep expertise for production workflows. This Skill provides advanced Git capabilities for:

1. Complex History Management - Interactive rebase, history rewriting, commit surgery
2. Advanced Branching - Worktrees, orphan branches, branch strategies
3. Conflict Resolution - Sophisticated merge/rebase conflict handling
4. Repository Archaeology - Bisect, blame, reflog recovery
5. Workflow Automation - Hooks, aliases, custom commands
6. Submodule Management - Complex dependency trees
7. Repository Optimization - Cleanup, gc, filter-repo operations

When to Use This Skill

• Complex interactive rebases with conflicts
• Recovering lost commits or branches
• Fixing repository states (detached HEAD, corrupted refs)
• Managing worktrees for parallel development
• Advanced conflict resolution strategies
• Git bisect for bug hunting
• Cherry-picking and commit manipulation
• Repository cleanup and optimization
• Setting up or debugging Git hooks
• Submodule operations and workflows

Quick Start: Top 5 Essential Operations

1. Interactive Rebase (Cleanup Feature Branch)

# Rebase last 5 commits on feature branch
git rebase -i HEAD~5

# Commands in editor:
# pick    - keep commit
# squash  - combine with previous
# edit    - stop to modify
# drop    - remove commit
# reword  - change message

# After resolving conflicts
git rebase --continue

2. Recover Lost Commits

# View all HEAD movements
git reflog

# Find lost commit and recover
git checkout abc123           # Or git reset --hard abc123
git branch recovery-branch    # Save as new branch

3. Worktree for Parallel Work

# Create second worktree (same repo, different branch)
git worktree add ../hotfix hotfix-branch

# Work in hotfix directory without stashing
cd ../hotfix
git add . && git commit -m "Fix critical bug"

# Cleanup when done
git worktree remove ../hotfix

4. Bisect to Find Bug

git bisect start
git bisect bad          # Mark current as broken
git bisect good v1.0   # Mark last known good

# Git checks out middle - test it
npm test

# Tell git if good or bad
git bisect good         # Or: git bisect bad

# Repeat until found - then
git bisect reset

5. Resolve Merge Conflicts

# Understand three versions
git show :1:file.txt   # Common ancestor
git show :2:file.txt   # Our version (HEAD)
git show :3:file.txt   # Their version (incoming)

# Resolve and complete
git add file.txt
git rebase --continue  # Or: git merge --continue

Essential Command Reference

Viewing History

# Beautiful log with graph
git log --oneline --graph --all --decorate

# Search commits by message
git log --grep="pattern"

# Find commits changing specific code
git log -S"function_name"

# View changes between branches
git log branch1..branch2

Branch Operations

# Create and switch
git checkout -b feature-branch

# List branches with tracking
git branch -vv

# Delete branch (safe/force)
git branch -d feature-branch
git branch -D feature-branch

# Rename branch
git branch -m old-name new-name

Remote Operations

# Fetch latest
git fetch origin --prune

# Push new branch with upstream
git push -u origin feature-branch

# Safe force push (checks if remote changed)
git push --force-with-lease

# Delete remote branch
git push origin --delete feature-branch

Rebase vs Merge Decision

MERGE (safe for public branches):

git merge feature-branch  # Preserves full history

REBASE (only for personal/feature branches):

git rebase main  # Creates linear history

Rule: Never rebase branches others use. Always rebase local features onto latest main.

Best Practices

DO's

1. Commit Often - Small, focused commits are easier to manage
2. Write Good Messages - Explain why, not what
3. Use Branches - Keep main/develop clean
4. Pull Before Push - Avoid merge conflicts
5. Use --force-with-lease - Never use bare --force
6. Tag Releases - Use semantic versioning (v1.2.3)
7. Review Before Push - Check diffs: git diff origin/main..HEAD

DON'Ts

1. Don't Commit Secrets - Use .gitignore and env vars
2. Don't Rebase Public Branches - Only rebase local/feature branches
3. Don't Force Push to Shared Branches - Breaks others' work
4. Don't Commit Large Binaries - Use Git LFS instead
5. Don't Use git add . Blindly - Review what you're staging
6. Don't Panic on Mistakes - Reflog can recover most issues

Core Concepts

Three Git Areas

1. Working Directory - Your files on disk
2. Staging Area (Index) - Files ready to commit
3. Repository - Committed history

Git Object Model

Every commit is a snapshot:
Commit -> Tree -> Blobs (files)
   |
   v
Parent Commits

Ref Types

• Branches - Movable pointers (refs/heads/main)
• Tags - Fixed pointers (refs/tags/v1.0.0)
• Remote-tracking - Remote copies (refs/remotes/origin/main)
• HEAD - Current position (usually via branch)
• Reflog - Journal of where HEAD has been

Common Gotchas Quick Reference

1. Detached HEAD - Make branch immediately: git checkout -b recovery
2. Force Push - Always use --force-with-lease not --force
3. Merge vs Rebase - Never rebase public branches, only personal branches
4. Lost Commits - Use reflog: git reflog then git checkout <commit>
5. Submodules - Always git submodule update --init --recursive after checkout

Documentation Structure (Progressive Disclosure)

This Skill uses progressive disclosure. Reference files contain:

• SKILL.md (this file) - Quick start and essential operations
• KNOWLEDGE.md - Git internals, resources, learning materials
• GOTCHAS.md - Common mistakes, recovery procedures, detailed solutions
• PATTERNS.md - Advanced workflows (rebase, worktrees, bisect, hooks, cleanup)
• EXAMPLES.md - Detailed real-world scenarios and walkthroughs
• REFERENCE.md - Complete command syntax and options

See GOTCHAS.md for detailed recovery procedures, PATTERNS.md for workflow examples, and REFERENCE.md for complete command reference.

Pre-Push Safety Checklist

# 1. Fetch latest
git fetch origin

# 2. Check if up-to-date
git status -uno

# 3. Review your changes
git diff origin/main..HEAD

# 4. Run tests
npm test

# 5. Push safely
git push --force-with-lease

When to Use Specific Patterns

Use Interactive Rebase When:

• Cleaning up feature branch before PR
• Reorganizing commits logically
• Fixing commit messages
• Removing debug code commits

Use Worktrees When:

• Switching branches frequently
• Reviewing multiple PRs simultaneously
• Running long tests on different branches
• Parallel development without stashing

Use Bisect When:

• Bug exists but commit unknown
• Need to find breaking commit
• Regression in test suite
• Want to pinpoint when something changed

Use Reflog When:

• Accidentally reset commits
• Lost branch after rebase
• Need to recover "deleted" work
• Branch somehow disappeared

Related Skills

• deployment-automation-toolkit - For Git-based deployments
• code-review-framework - For review workflows with Git
• codebase-onboarding-analyzer - Uses Git history for analysis
• security-scanning-suite - Scan Git history for secrets

Learning Resources

Official Documentation:

• Pro Git Book - Comprehensive free guide
• Git Reference Manual - Official commands
• Atlassian Git Tutorials - Practical guides

Problem Solving:

• Oh Shit, Git!?! - Common mistakes
• Git Flight Rules - Specific problems
• Learn Git Branching - Interactive sandbox