spillwavesolutions/agent_rulez/mastering-git-cli

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

# 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

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)

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)

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

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>

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)

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)

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

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

git checkout --theirs .
git add .
git commit

git checkout --ours .
git add .
git commit

git merge --abort

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

git merge feature-a feature-b feature-c  # Octopus merge (no conflicts allowed)

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"

scripts/cleanup-agent-worktrees.sh [--delete-branches] [--force]
# Example: scripts/cleanup-agent-worktrees.sh --delete-branches
# Removes worktrees and their associated branches

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

scripts/git-health-check.sh [--verbose]
# Checks: dangling objects, broken refs, large files, stale branches

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

git config --global merge.conflictStyle zdiff3

<<<<<<< HEAD
our version
||||||| merged common ancestor
original version
=======
their version
>>>>>>> feature

git worktree add -b feature-copy ../feature-copy feature  # Create copy

cd submodule-dir
git checkout main  # Then make changes

# 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

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

git clone --filter=blob:none <url>
cd repo
git sparse-checkout init --cone
git sparse-checkout set backend/api frontend/app

scalar register                 # Enable all optimizations
# OR manually:
git maintenance start          # Background maintenance
git config core.fsmonitor true # Filesystem watcher

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

git refs migrate --ref-format=reftable

# Bad: ambiguous, can lose data
git checkout file.txt
 
# Good: explicit intent
git restore file.txt

# Bad: breaks blame, log, push
git clone --depth 1 <url>
 
# Good: blobless preserves history
git clone --filter=blob:none <url>

# Bad: can overwrite teammates' work
git push --force
 
# Good: fails if remote has new commits
git push --force-with-lease

# Bad: blocks, runs everything at once
git gc
 
# Good: scheduled, incremental
git maintenance start

# Bad: rewrites history others depend on
git rebase main  # on a pushed branch
 
# Good: merge instead for shared branches
git merge main

# 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

# Bad: accepting all changes blindly
git checkout --theirs .  # without reviewing
 
# Good: review each conflict
git mergetool  # or manual review with zdiff3