# Git Mastery Suite

> Advanced Git operations including rebasing, conflict resolution, history rewriting, worktrees, bisect, submodules, hooks, and complex workflows. Use for sophisticated Git challenges beyond basic add/commit/push, including fixing repository states, optimizing history, and managing complex branching strategies.

- Skill: `majiayu000/git-mastery-suite` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/git-mastery-suite`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/git-mastery-suite/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/git-mastery-suite

---


# 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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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):
```bash
git merge feature-branch  # Preserves full history
```

**REBASE** (only for personal/feature branches):
```bash
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

```bash
# 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](https://git-scm.com/book) - Comprehensive free guide
- [Git Reference Manual](https://git-scm.com/docs) - Official commands
- [Atlassian Git Tutorials](https://www.atlassian.com/git/tutorials) - Practical guides

**Problem Solving:**
- [Oh Shit, Git!?!](https://ohshitgit.com/) - Common mistakes
- [Git Flight Rules](https://github.com/k88hudson/git-flight-rules) - Specific problems
- [Learn Git Branching](https://learngitbranching.js.org/) - Interactive sandbox