mastering-git-cli

name

mastering-git-cli

description

Git CLI operations, workflows, and automation for modern development (2025). Use when working with repositories, commits, branches, merging, rebasing, worktrees, submodules, or multi-repo architectures. Includes parallel agent workflow patterns, merge strategies, conflict resolution, and large repo optimization. Triggers on git commands, version control, merge conflicts, worktree setup, submodule management, repository troubleshooting, branch strategy, rebase operations, cherry-pick decisions, and CI/CD git integration.

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

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

# 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

git checkout main
git merge --no-ff feature    # Always creates merge commit

Update feature with latest main

git checkout feature
git merge main               # Safe for shared branches
# OR
git rebase main              # Only if branch not shared

Resolve all conflicts using theirs

git checkout --theirs .
git add .
git commit

Resolve all conflicts using ours

git checkout --ours .
git add .
git commit

Abort a broken merge

git merge --abort

Undo a pushed merge

git revert -m 1 <merge-sha>
git push

Merge multiple branches at once

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:

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:

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:

scripts/submodule-report.sh
# Output: Table showing submodule path, branch, commit, and sync status

Git Health Check

Diagnose common repository issues:

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

Critical Knowledge

The -X ours vs -s ours Trap

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

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:

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:

cd submodule-dir
git checkout main  # Then make changes

2025 Easy Buttons

Find the bug-introducing commit automatically

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

git range-diff main..feature@{1} main..feature

Monorepo: checkout only what you need

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

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)

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)

git refs migrate --ref-format=reftable

Anti-Patterns (Avoid These)

Don't use checkout for file operations

# Bad: ambiguous, can lose data
git checkout file.txt

# Good: explicit intent
git restore file.txt

Don't shallow clone for development

# 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

# 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

# Bad: blocks, runs everything at once
git gc

# Good: scheduled, incremental
git maintenance start

Don't rebase shared branches

# 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

# 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

# Bad: accepting all changes blindly
git checkout --theirs .  # without reviewing

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