git-helper

name	git-helper
description	Git version control best practices, advanced operations, and modern features When user works with git, mentions git commands, branching, rebasing, merging, or git troubleshooting

Git Helper Agent

Branch & PR management in shepherdjerred/monorepo uses git-spice — every PR is a stacked PR. Load the git-spice-helper skill first (it's authoritative) before creating branches, stacking, restacking, or opening PRs; create/update PRs with git-spice branch/stack submit. The gh pr create and manual-git rebase examples below are the generic fallback for repos without git-spice.

What's New in Git (2024-2026)

Git 2.52 (2025)

• git last-modified: New command to determine which commit most recently modified each file in a directory (5.5x faster than ls-tree + log)
• git refs list / git refs exists: Consolidated reference operations
• git repo: Experimental command for retrieving repository information
• git maintenance geometric task: Alternative to all-into-one repacks
• git sparse-checkout clean: Recover from difficult checkout state transitions
• Default branch change: Git 3.0 will default to "main" instead of "master"
• Rust integration: Optional Rust code for variable-width integer operations
• git describe 30% faster, git log -L faster for merge commits

Git 2.51 (2025)

• Stash interchange format: git stash export and git stash import subcommands for cross-machine stash migration
• --path-walk repacking: Significantly smaller pack files by emitting all objects from a given path simultaneously
• Cruft-free multi-pack indexes: 38% smaller MIDXs, 35% faster writes, 5% better read performance at GitHub
• git switch / git restore: No longer experimental after six years
• git whatchanged: Marked for removal in Git 3.0

Git 2.50 (2025)

• ORT merge engine: Completely replaced the older recursive merge engine
• git merge-tree --quiet: Check mergeability without writing objects
• git maintenance new tasks: worktree-prune, rerere-gc, reflog-expire
• Incremental multi-pack bitmap support: Fast reachability bitmaps for extremely large repos
• git cat-file object filtering: Filter objects by type using partial clone mechanisms
• Bundle URI: Faster fill-in fetches by advertising all known references from bundles

Git 2.49 (2025)

• Name-hash v2: Dramatically improved packing (fluentui: 96s to 34s, 439 MiB to 160 MiB)
• git backfill: Batch-fault missing blobs in --filter=blob:none partial clones
• zlib-ng support: ~25% speed improvement for compression
• git clone --revision: Clone specific commits without branch/tag references
• git gc --expire-to: Manage pruned objects by moving them elsewhere
• First Rust code integration via libgit-sys and libgit crates

Git 2.48 (2025)

• Faster checksums: 10-13% performance improvement in serving fetches/clones using non-collision-detecting SHA-1 for trailing checksums
• range-diff --remerge-diff: Review merge conflict resolutions during rebase
• Remote HEAD tracking: Fetch auto-updates refs/remotes/origin/HEAD if missing; configure remote.origin.followRemoteHead
• Meson build system: Alternative build system alongside Make/CMake/Autoconf
• Memory leak elimination: Entire test suite passes with leak checking
• BreakingChanges.txt: Documents anticipated deprecations for future versions

Git 2.47 (2024)

• Incremental multi-pack indexes: Layered MIDX chains for faster object addition
• Separate hash function for checksums: 10-13% serving performance improvement

Git 2.46 (2024)

• Pseudo-merge bitmaps: Faster reachability queries
• git config list / git config get: New sub-command interface
• Reftable migration: git refs migrate --ref-format=reftable for faster reference operations
• Enhanced credential helpers: authtype/credential fields, multi-round auth (NTLM, Kerberos)

Git 2.45 (2024)

• Reftable backend: New reference storage with faster lookups, reads, and writes

Git 2.44 (2024)

• Multi-pack reuse optimization: Faster fetches and clones
• builtin_objectmode pathspec: Filter paths by mode

Overview

Git is the distributed version control system used by virtually all modern software projects. This skill covers general Git best practices, advanced operations, branching strategies, and modern features. For worktree-specific workflows (parallel development, AI agent isolation), see the worktree-workflow skill instead.

CLI Commands

Auto-Approved (Safe, Read-Only)

These commands are safe to run without user confirmation:

• git status - Working tree status
• git log - Commit history (with --oneline, --graph, --all, --since, --author)
• git diff - Show changes (staged: --cached, between branches, specific files)
• git branch - List branches (-a for all, -v for verbose, --merged, --no-merged)
• git tag - List tags (-l "v1.*" for patterns)
• git show - Show commit details
• git remote -v - List remotes
• git stash list - List stashed changes
• git reflog - Reference log history
• git blame - Line-by-line authorship
• git shortlog - Summarized log output
• git config --list - Show configuration
• git rev-parse - Parse revision/path info
• git ls-files - Show tracked files
• git describe - Human-readable name from commit

Common Operations

# Stage changes
git add <file>              # Stage specific file
git add -p                  # Interactive staging (hunk-by-hunk)
git add -N <file>           # Track file without staging content

# Commit
git commit -m "message"     # Commit with message
git commit --amend          # Amend last commit (message or content)
git commit --fixup=<sha>    # Create fixup commit for later autosquash
git commit --allow-empty    # Empty commit (useful for CI triggers)

# Branch operations
git branch <name>           # Create branch
git branch -d <name>        # Delete merged branch
git branch -D <name>        # Force delete branch
git branch -m <old> <new>   # Rename branch
git switch <branch>         # Switch branch (preferred over checkout)
git switch -c <new-branch>  # Create and switch

# Remote operations
git fetch                   # Fetch from default remote
git fetch --all --prune     # Fetch all remotes and prune stale tracking
git pull --rebase           # Pull with rebase instead of merge
git push -u origin <branch> # Push and set upstream

# Undoing changes
git restore <file>          # Discard working tree changes (preferred over checkout --)
git restore --staged <file> # Unstage file
git reset --soft HEAD~1     # Undo last commit, keep changes staged
git reset --mixed HEAD~1    # Undo last commit, keep changes unstaged
git revert <sha>            # Create a new commit that undoes a previous commit

Log and History

# Useful log formats
git log --oneline --graph --all --decorate
git log --since="2 weeks ago" --author="name"
git log --follow -p -- <file>       # Full history of a file including renames
git log -S "search_string"          # Find commits that add/remove a string (pickaxe)
git log -G "regex_pattern"          # Find commits matching regex in diffs
git log --first-parent              # Follow only first parent (clean merge history)
git log --diff-filter=D -- <path>   # Find when files were deleted

# Comparing
git diff main..feature              # Changes in feature not in main
git diff main...feature             # Changes since feature branched from main
git diff --stat                     # Summary of changes
git diff --name-only                # Just filenames
git diff --word-diff                # Word-level diff

Essential Workflows

Creating Good Commits

1. Atomic commits: Each commit should represent one logical change

2. Write clear messages: Follow conventional commit format

   type(scope): short description
   
   Longer explanation if needed. Wrap at 72 characters.
   
   Refs: #123
   

   Types: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert

3. Stage intentionally: Review staged changes with git diff --cached before committing

4. Verify before committing: Run git diff --cached to review staged changes

Monorepo commit-msg convention (this repo)

Git hooks were removed 2026-07 (lefthook and its commit-msg validator are gone), so nothing enforces this anymore — but keep following the convention: type(scope): description with a scope that is a packages/ dir name or one of root / practice / archive (monorepo, repo, ALL were never valid). Use root for sweeping cross-package commits (e.g. feat(root): …). Types: feat fix chore ci docs refactor test perf build style revert misc. There is also no pre-commit formatting hook — run bunx prettier --write <file> yourself before committing.

Syncing with Upstream

# Rebase approach (linear history)
git fetch origin
git rebase origin/main

# If conflicts arise during rebase
git status                  # See conflicted files
# ... resolve conflicts ...
git add <resolved-files>
git rebase --continue       # Continue after resolving
git rebase --abort          # Abort and return to pre-rebase state

# Merge approach (preserves branch topology)
git fetch origin
git merge origin/main

Cleaning Up Before PR

# Interactive rebase to clean commit history
git rebase -i origin/main

# With autosquash (processes fixup!/squash! commits automatically)
git rebase -i --autosquash origin/main

# Enable autosquash globally
git config --global rebase.autoSquash true

Recovering from Mistakes

# Find lost commits or states
git reflog                          # Show recent HEAD movements
git reflog show <branch>            # Show branch-specific reflog

# Recover after bad rebase/reset
git reset --hard HEAD@{2}           # Reset to state 2 moves ago

# Recover deleted branch
git reflog | grep "checkout.*branch-name"
git branch <branch-name> <sha>      # Recreate from found SHA

Safety Rules (Agent)

• Never destroy uncommitted work to investigate. Don't git stash, git checkout -- <file>, git restore, or switch branches just to test something (e.g. checking whether failures are pre-existing) — these discard the user's or a concurrent agent's in-progress changes. Note the observation and move on, or ask the user.
• Force-push only branches you own. Never force-push main, release branches, or any branch others have pushed to or based work on without explicit confirmation at the moment of execution. Force-pushing a feature branch Claude created and owns this session is fine — use --force-with-lease, never --force. If unsure who else touched it, treat it as shared and ask first.
• Subagents must stay read-only on history. When spawning Explore/Plan/general-purpose agents, explicitly forbid git checkout <branch>, git switch, git stash, git reset, or anything that moves HEAD or the working tree — they can silently leave the user on a stale commit. Tell them to use git show <ref>:<path>, git log <ref>, and git diff <ref>..<ref> for cross-branch inspection. Verify HEAD with git reflog before any push after a subagent ran.
• Never revert changes you didn't make. Unexpected file modifications may be a concurrent human or agent, not a rogue linter — reverting them causes build failures and lost work. If a change looks intentional (new types, refactored functions, new files) rather than formatting-only, leave it; ask before reverting anything.
• Whole-file staging only. Split work into multiple commits with plain git add <path> ... grouped by file or concern — never git add -p / -i / --patch or any interactive hunk staging (it is opaque and hard to review). This overrides the git add -p suggestions elsewhere in this skill; if one file truly mixes two unrelated concerns, ask rather than reaching for -p.
• core.fsmonitor can silently drop git add. The user's git config enables core.fsmonitor + core.untrackedCache; a stale cache can make git status report a clean tree and git add no-op after tool-driven edits. Detect it when git hash-object <file> ≠ git rev-parse :<file>. Work around by prefixing commands with -c core.fsmonitor=false (e.g. git -c core.fsmonitor=false add <files>).

When to Ask for Help

Ask the user for clarification when:

• Choosing between rebase vs merge strategy for their team
• Whether to force push after rebase (check if others use the branch)
• How to handle complex merge conflicts
• Repository-specific branching conventions
• Whether to squash commits before merging

References

• Git Official Documentation
• Git Release Notes
• GitHub Blog - Git Updates
• Pro Git Book
• Conventional Commits

Skill References

For detailed coverage of specific topics, see:

• references/advanced-operations.md - Interactive rebase, bisect, reflog, cherry-pick, filter-repo, stash, rerere, blame, notes, bundle, sparse-checkout
• references/branching-workflows.md - Branching strategies, commit conventions, merge vs rebase, signed commits, tags, release workflows
• references/config-hooks.md - Git configuration, conditional includes, aliases, hooks, maintenance, scalar, performance, .gitattributes, .gitignore