mastering-git-cli
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.
- Installs
- 39
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/spillwavesolutions/mastering-git-cli-agent-skill --skill mastering-git-cli- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads mastering-git-cli automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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:
gitcommands 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
FAQ
What does the mastering-git-cli skill do?
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.
How do I install mastering-git-cli?
Run npx skills add https://github.com/spillwavesolutions/mastering-git-cli-agent-skill --skill mastering-git-cli in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/mastering-git-cli/ (personal) or .claude/skills/mastering-git-cli/ (project).
Which AI agents can use mastering-git-cli?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is mastering-git-cli safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains mastering-git-cli?
It is published by spillwavesolutions in spillwavesolutions/mastering-git-cli-agent-skill. It has 39 recorded installs.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.