mastering-git-cli

# Git CLI Skill (2025 Edition)

Production-ready Git workflows and automation for modern development.

> **Compatibility:** Git 2.38+ recommended. Git 2.51+ for full SHA-256/Reftable support.

## Triggers

This skill activates on:
- `git` commands and version control questions
- Merge conflicts, rebase operations, cherry-pick decisions
- Worktree setup and submodule management
- Branch strategy and repository troubleshooting
- Large repo optimization (Scalar, sparse checkout, blobless clones)
- CI/CD git integration and performance tuning

## Quick Start

### Most Common Patterns

```bash
# Clone and start working (use switch, not checkout)
git clone <url> && cd <repo>
git switch -c feature-x

# Commit workflow
git add -A && git commit -m "feat: description"
git push -u origin feature-x

# Merge feature to main
git switch main && git pull
git merge --no-ff feature-x
git push

# Large repo? Use partial clone
git clone --filter=blob:none <url>
```

### Modern Git Config (2025 Defaults)

```bash
# Core workflow
git config --global pull.rebase true
git config --global push.autoSetupRemote true
git config --global merge.conflictStyle zdiff3
git config --global diff.algorithm histogram
git config --global rerere.enabled true
git config --global rebase.autoStash true

# Performance (essential for large repos)
git config --global core.fsmonitor true
git config --global fetch.prune true
git config --global feature.manyFiles true

# SSH signing (simpler than GPG)
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

# Enable background maintenance
git maintenance start
```

## Decision Trees

### Merge vs Rebase vs Cherry-pick

```
Need to integrate changes?
│
├─ All commits from a branch?
│  ├─ Shared branch (pushed/collaborative) → MERGE
│  └─ Local-only branch → REBASE (cleaner) or MERGE
│
└─ Specific commits only?
   └─ CHERRY-PICK
      ├─ Hotfix to release branch → cherry-pick -x
      └─ Backport to old version → cherry-pick -x

⚠️ AVOID: Rebasing shared/pushed branches (rewrites history others depend on)
```

### Worktrees vs Branches vs Stash

```
Need to switch context?
│
├─ Quick switch, will return soon → STASH
├─ Parallel work on same files → Not possible
├─ Parallel work on different features?
│  ├─ Short-lived (minutes) → STASH or COMMIT WIP
│  └─ Long-running or parallel builds → WORKTREE
│
└─ Multiple agents working simultaneously → WORKTREE (essential)
```

### Submodules vs Subtree vs Monorepo

```
External code dependency?
│
├─ Need to modify and contribute back → SUBMODULE
├─ Just embedding, no upstream → SUBTREE
├─ Tight coupling, single team → MONOREPO
└─ Standard library/package → PACKAGE MANAGER
```

### Reset vs Revert vs Restore

```
Undo something?
│
├─ Discard file changes (not staged) → git restore <file>
├─ Unstage files → git restore --staged <file>
├─ Undo commits (not pushed)?
│  ├─ Keep changes staged → git reset --soft HEAD~1
│  ├─ Keep changes unstaged → git reset HEAD~1
│  └─ Discard everything → git reset --hard HEAD~1
│
└─ Undo commits (already pushed) → git revert <sha>
```

### Clone Strategy (Large Repos)

```
How to clone?
│
├─ Small repo (<500MB) → Full clone (default)
├─ Large repo, developer workstation
│  └─ BLOBLESS clone → git clone --filter=blob:none <url>
├─ Large repo, CI build
│  ├─ Need only HEAD → SHALLOW → git clone --depth 1
│  └─ Need history → TREELESS → git clone --filter=tree:0
│
└─ Monorepo, specific directories only
   └─ SCALAR + SPARSE → scalar clone <url>, then sparse-checkout

⚠️ AVOID: Shallow clone for development (breaks blame, log, push)
```

### checkout vs switch/restore

```
Which command?
│
├─ Changing branches → git switch <branch>
├─ Creating branch → git switch -c <new-branch>
├─ Discarding file changes → git restore <file>
├─ Unstaging files → git restore --staged <file>
│
└─ git checkout → Legacy (avoid in new scripts)
```

## Merge Easy Buttons

### Integrate feature into main
```bash
git checkout main
git merge --no-ff feature    # Always creates merge commit
```

### Update feature with latest main
```bash
git checkout feature
git merge main               # Safe for shared branches
# OR
git rebase main              # Only if branch not shared
```

### Resolve all conflicts using theirs
```bash
git checkout --theirs .
git add .
git commit
```

### Resolve all conflicts using ours
```bash
git checkout --ours .
git add .
git commit
```

### Abort a broken merge
```bash
git merge --abort
```

### Undo a pushed merge
```bash
git revert -m 1 <merge-sha>
git push
```

### Merge multiple branches at once
```bash
git merge feature-a feature-b feature-c  # Octopus merge (no conflicts allowed)
```

## Script Usage

### Agent Worktree Setup
Create isolated worktrees for parallel agent development:
```bash
scripts/setup-agent-worktrees.sh [num_agents] [base_branch]
# Example: scripts/setup-agent-worktrees.sh 3 main
# Creates: ../agent-1, ../agent-2, ../agent-3, ../integration
# Output: "Created 3 agent worktrees from main"
```
**Use case:** Running 3 Claude agents in parallel on different features, each with isolated working directories.

### Agent Worktree Cleanup
Remove all agent worktrees and optionally delete branches:
```bash
scripts/cleanup-agent-worktrees.sh [--delete-branches] [--force]
# Example: scripts/cleanup-agent-worktrees.sh --delete-branches
# Removes worktrees and their associated branches
```

### Submodule Status Report
Get readable status of all submodules:
```bash
scripts/submodule-report.sh
# Output: Table showing submodule path, branch, commit, and sync status
```

### Git Health Check
Diagnose common repository issues:
```bash
scripts/git-health-check.sh [--verbose]
# Checks: dangling objects, broken refs, large files, stale branches
```

## Reference Navigation

Read the appropriate reference file based on your task:

| Task | Reference File |
|------|----------------|
| Understand Git internals, object model, DAG | [references/foundations.md](references/foundations.md) |
| Configure Git, set up 2025 defaults | [references/foundations.md](references/foundations.md) |
| Clone, commit, log, branch basics | [references/daily-usage.md](references/daily-usage.md) |
| Create/manage worktrees | [references/worktrees.md](references/worktrees.md) |
| Set up parallel agent workflows | [references/worktrees.md](references/worktrees.md) |
| Choose merge strategy | [references/merge-operations.md](references/merge-operations.md) |
| Resolve merge conflicts | [references/merge-operations.md](references/merge-operations.md) |
| Use rerere for conflict resolution | [references/merge-operations.md](references/merge-operations.md) |
| Add/update/manage submodules | [references/submodules.md](references/submodules.md) |
| Multi-repo project architecture | [references/submodules.md](references/submodules.md) |
| Reset, revert, restore operations | [references/advanced-operations.md](references/advanced-operations.md) |
| Interactive rebase, squashing | [references/advanced-operations.md](references/advanced-operations.md) |
| Stashing, tags, hooks | [references/advanced-operations.md](references/advanced-operations.md) |
| Recover lost commits/branches | [references/recovery.md](references/recovery.md) |
| Troubleshoot common errors | [references/recovery.md](references/recovery.md) |
| Command cheat sheet | [references/recovery.md](references/recovery.md) |
| **SHA-256, Reftable, SSH signing** | [references/git-2025-features.md](references/git-2025-features.md) |
| **git switch/restore, range-diff** | [references/git-2025-features.md](references/git-2025-features.md) |
| **Git maintenance, bisect run** | [references/git-2025-features.md](references/git-2025-features.md) |
| **Merge queues, pre-commit framework** | [references/git-2025-features.md](references/git-2025-features.md) |
| **Partial/blobless clones, Scalar** | [references/large-repos.md](references/large-repos.md) |
| **Sparse checkout for monorepos** | [references/large-repos.md](references/large-repos.md) |
| **Bare repo + worktree layout** | [references/large-repos.md](references/large-repos.md) |
| **CI/CD Git optimization** | [references/large-repos.md](references/large-repos.md) |

## Critical Knowledge

### The `-X ours` vs `-s ours` Trap

```bash
# -X ours: Prefer our changes ONLY IN CONFLICTS
git merge -X ours feature
# ↑ Merges all non-conflicting changes from feature

# -s ours: IGNORE EVERYTHING from other branch
git merge -s ours feature
# ↑ Keeps our tree exactly, just records the merge
```

### Conflict Style Recommendation

```bash
git config --global merge.conflictStyle zdiff3
```

Shows base version in conflicts, making resolution clearer:
```
<<<<<<< HEAD
our version
||||||| merged common ancestor
original version
=======
their version
>>>>>>> feature
```

### Branch Can Only Exist in One Worktree

A branch can only be checked out in ONE worktree. To work on it elsewhere:
```bash
git worktree add -b feature-copy ../feature-copy feature  # Create copy
```

### Submodules Default to Detached HEAD

After `git submodule update`, always checkout a branch before making changes:
```bash
cd submodule-dir
git checkout main  # Then make changes
```

## 2025 Easy Buttons

### Find the bug-introducing commit automatically
```bash
# Create test script: exit 0 = good, exit 1 = bad
echo '#!/bin/bash
npm test -- --grep="broken feature"' > test.sh
chmod +x test.sh

git bisect start HEAD v1.0.0
git bisect run ./test.sh
git bisect reset
```

### Compare rebased PR (what actually changed)
```bash
git range-diff main..feature@{1} main..feature
```

### Monorepo: checkout only what you need
```bash
git clone --filter=blob:none <url>
cd repo
git sparse-checkout init --cone
git sparse-checkout set backend/api frontend/app
```

### Set up performance optimization
```bash
scalar register                 # Enable all optimizations
# OR manually:
git maintenance start          # Background maintenance
git config core.fsmonitor true # Filesystem watcher
```

### SSH signing setup (simpler than GPG)
```bash
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true
```

### Migrate to reftable (10K+ branches)
```bash
git refs migrate --ref-format=reftable
```

## Anti-Patterns (Avoid These)

### Don't use checkout for file operations
```bash
# Bad: ambiguous, can lose data
git checkout file.txt

# Good: explicit intent
git restore file.txt
```

### Don't shallow clone for development
```bash
# Bad: breaks blame, log, push
git clone --depth 1 <url>

# Good: blobless preserves history
git clone --filter=blob:none <url>
```

### Don't skip --force-with-lease
```bash
# Bad: can overwrite teammates' work
git push --force

# Good: fails if remote has new commits
git push --force-with-lease
```

### Don't run git gc manually
```bash
# Bad: blocks, runs everything at once
git gc

# Good: scheduled, incremental
git maintenance start
```

### Don't rebase shared branches
```bash
# Bad: rewrites history others depend on
git rebase main  # on a pushed branch

# Good: merge instead for shared branches
git merge main
```

### Don't commit secrets or generated files
```bash
# Bad: committing sensitive or generated files
git add .env node_modules/

# Good: ensure .gitignore is set first
echo -e ".env\nnode_modules/" >> .gitignore
git add .gitignore
```

### Don't ignore merge conflicts
```bash
# Bad: accepting all changes blindly
git checkout --theirs .  # without reviewing

# Good: review each conflict
git mergetool  # or manual review with zdiff3
```