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