shepherdjerred/monorepo/git-helper

Git Helper

Inspect first, preserve user work, and use the repository's owning branch workflow for mutations. This skill covers Git itself; a stack or PR skill remains authoritative for branch creation, restacking, publishing, and synchronization.

Branch workflow ownership

In shepherdjerred/monorepo, every PR — human or agent, new or existing — is a git-spice stack. Load monorepo-delivery first; it is authoritative for branch creation, restacking, and publishing.

Use the provided isolated workspace; do not create a second worktree unless the user explicitly asks for one. Do not use a bare gh pr create or hand-written rebase in place of the owning stack tool.

Current baseline

Verified against Git 2.55.0 on 2026-08-03:

git --version

Recent versions added stable switch and restore, stash export/import, refs commands, last-modified, backfill, url-parse, format-rev, maintenance improvements, and additional partial-clone and pack tooling. repo, last-modified, history, format-rev, and backfill should be treated according to their documented experimental or evolving status.

Git's future-breaking-changes document is the source of truth for planned removals. Do not state a Git 3 release date or default change as certain until the project publishes it.

Read references/releases.md when adopting a recent command or upgrading Git. Read references/history-and-recovery.md for rebase, range-diff, bisect, reflog, stash, sparse checkout, bundles, and recovery. Read references/configuration-and-maintenance.md for config, hooks, credentials, maintenance, refs, and repository health.

Start read-only

Useful inspection commands:

git status --short --branch
git diff --stat
git diff
git diff --cached
git log --oneline --graph --decorate --all
git branch --verbose --verbose
git remote --verbose
git reflog
git worktree list --porcelain
git config --list --show-origin --show-scope

Use git show <ref>:<path>, git log <ref> -- <path>, and git diff <base>...<head> to inspect another branch without switching the working tree.

Preserve concurrent work

• Never discard, stash, reset, restore, or switch away from unexpected work just to investigate.
• Treat every existing modification as user-owned unless provenance proves otherwise.
• Keep all agents read-only on history unless explicitly assigned an isolated branch mutation.
• Verify the current branch and recent movements before pushing:

git status --short --branch
git reflog -n 10

• Stage whole files by explicit path. Do not use interactive, hunk-level, current-directory, or repository-wide staging in agent workflows.

Intentional commits

git add path/to/first path/to/second
git diff --cached --check
git diff --cached
git commit -m "type(scope): concise description"

If core.fsmonitor makes a changed file appear unstaged, compare the working and index object IDs and disable fsmonitor for the affected command:

git hash-object path/to/file
git rev-parse :path/to/file
git -c core.fsmonitor=false add path/to/file

Do not amend or force-push a commit another person may have based work on without explicit authorization.

Compare the right ranges

# Tip-to-tip difference
git diff main..feature
 
# Changes introduced since the merge base
git diff main...feature
 
# Patch-series comparison before and after a rebase
git range-diff old-base..old-tip new-base..new-tip

range-diff compares two commit ranges. Do not use the invalid single-range shorthand found in older copies of this skill.

Mergeability without changing the checkout

Use the repository's independent merge oracle when readiness matters:

git merge-tree --write-tree <base> <head>

Treat the exit status as the merge result: 0 is a clean merge, 1 is a real conflict. --quiet (Git 2.50+) additionally suppresses most output and object creation when the exit status is all that's needed, but isn't available on older Git — omit it rather than assume it exists, or gate it behind a version check. Do not replace this check with a checkout or an untrusted hosted mergeability field.

Undo and recovery

Choose the least destructive operation:

Never present git reset --hard HEAD@{n} as a routine recovery recipe. First inspect the reflog entry and preserve it with a branch:

git reflog
git show <recovered-commit>
git branch recovery/<name> <recovered-commit>

Rebasing and pushing

Use the owning stack tool for repositories with stacked PR workflows. In a generic repository, inspect the branch, fetch explicitly, and compare the rewritten series with range-diff.

Rebase does not always require a force push: an unpublished local branch can be pushed normally. When a published branch is intentionally rewritten, background fetches can invalidate the protection expected from plain --force-with-lease; verify the remote tip and use an explicit expected object when safety matters.

Never force-push main, release branches, shared branches, or work another person may have based on without current authorization.

Hooks and credentials

Repository hooks are executable policy. Inspect the configured hook path and hook source before relying on them:

git config --get core.hooksPath
ls -la "$(git rev-parse --git-path hooks)"

git config --get/--list work on every supported Git version; the newer git config get/git config list subcommand syntax does not exist before Git 2.46. git hook list <hook-name> (added in Git 2.54, and it requires a hook name — it does not list every hook) can supplement this once the installed version is confirmed; do not rely on it as the portable default.

Use credential helpers or GIT_ASKPASS; never embed tokens in remotes, configuration, logs, or files. Treat hook input and filenames as untrusted shell data.

Maintenance and repository health

Use git maintenance tasks documented for the installed version. geometric-repack is a maintenance task; geometric is a strategy, not a task name. Use git maintenance is-needed where supported to avoid unnecessary work.

For diagnosis:

git fsck --full
git count-objects -vH
git reflog expire --dry-run --all

Run git gc --auto only as an explicitly authorized maintenance step: it may repack objects and prune expired unreachable data. Do not change reflog expiry, run aggressive collection, or delete unreachable objects until recovery requirements and repository ownership are clear.

Review checklist

• Load and obey the repository's owning stack/branch skill.
• Inspect status, diff, branch, and worktrees before mutation.
• Keep user-owned and concurrent work intact.
• Stage explicit whole-file paths and review the staged diff.
• Use independent merge-tree evidence for mergeability claims.
• Compare rewritten series with a valid two-range range-diff.
• Resolve exact reflog/reset/restore targets before destructive actions.
• Verify remote tips before any authorized history rewrite.
• Treat experimental commands and future Git changes as conditional.
• Check hook configuration and credential exposure before publishing.