git · diff

git:20260722.f0eb407 to git:20261105.39988c5

13 added, 245 removed. Audit A to A.

---

name: git

- description: Operate Git safely for status, diffs, branches, staging, commits, history, conflicts, worktrees, tags, remotes, hooks, cleanup, and recovery. Use only for actual Git operations.

+ description: Stages and commits scoped changes, fetches and integrates branches, resolves conflicts, pushes authorized history, and writes PR descriptions while preserving others' work. Applies to Git operations and commit messages, not permission to publish ordinary file edits.

---

- # Git

- ## Core Rules

- Treat the repository as shared. Inspect first, preserve user work, and make the smallest reviewable Git operation that satisfies the request.

- - Run Git commands to verify state; do not infer branch, cleanliness, staged files, upstreams, conflicts, tags, or remotes from memory.

- - Use official Git docs (`https://git-scm.com/docs/git-<command>`) when command behavior, flags, or edge cases matter.

- - Verify the installed Git version for version-sensitive syntax and read [authoritative Git sources](references/sources.md) before relying on rolling command documentation.

- - Before writing or committing, inspect `git status --short --branch`, changed file names or stats, targeted diffs, and recent history when history affects the operation.

- - Prefer non-destructive commands. Treat `reset --hard`, `clean`, `checkout -- <path>`, `restore <path>`, force-push, submodule deinit, tag deletion, and history rewriting as high-risk.

- ## First Inspection

- Use this sequence before any Git-affecting work:

- ```bash

- git rev-parse --show-toplevel

- git status --short --branch

- git diff --stat

- git diff --name-status

- git diff --staged --stat

- git diff --staged --name-status

- ```

- Add targeted commands as needed:

- - Branch/upstream: `git branch --show-current`, `git branch -vv`, `git remote -v`

- - Recent history: `git log --oneline --decorate --graph --max-count=20`

- - Changed names: `git diff --name-status`, `git diff --staged --name-status`

- - Submodules: `git submodule status --recursive`

- - Stashes/worktrees: `git stash list`, `git worktree list`

- Inspect full diffs only for relevant paths or staged changes that matter to the task: `git diff -- <path>...` and `git diff --staged -- <path>...`. If output is large, narrow by pathspec, commit range, or `--stat`/`--name-only`. Do not dump full repository history or full repo diffs unless necessary.

- When a script must parse paths or status, use a stable machine format such as `git status --porcelain=v1 -z`; never parse human-oriented short or colorized output.

- ## Preserving User Changes

- - Separate your changes from existing changes before editing. Record the initial status mentally or in notes.

- - If a file already has user changes, read the relevant sections and patch around them; do not normalize unrelated formatting.

- - If a required operation needs a clean tree, prefer a new branch or worktree. Use stash only with explicit intent and a descriptive message.

- - Use pathspecs for staging and diffs. Avoid broad `git add .` unless the whole change set is intentionally yours and reviewed.

- - Before finalizing, rerun status and inspect the exact staged or unstaged diff you are claiming.

- ## Branches

- - Inspect current branch and upstream before branch operations.

- - Create topic branches with `git switch -c <name>` when asked to isolate work.

- - Switch branches only after checking for local changes that would be carried, overwritten, or conflicted.

- - Treat fetches as external state-changing operations. Before comparing with remote branches, use local upstream data when sufficient; otherwise prefer `git fetch --dry-run --prune` for discovery and `git fetch --prune` only when current remote-tracking refs are needed.

- - Do not delete branches unless the user asks and the branch has been checked for unmerged work.

- Useful checks:

- ```bash

- git branch --show-current

- git branch -vv

- git fetch --dry-run --prune

- git fetch --prune

- git log --oneline --left-right --cherry-pick HEAD...@{upstream}

- ```

- ## Staging

- - Stage only intended paths: `git add -- <path>...`

- - For partial staging, use `git add -p` when an interactive terminal is appropriate; otherwise split the patch manually.

- - Unstage without losing work using `git restore --staged -- <path>` or `git reset -- <path>`.

- - Verify the index with `git diff --staged` before committing.

- ## Commits

- Only commit when the user explicitly authorizes the commit.

- - Inspect `git diff --staged` and `git status --short --branch` immediately before `git commit`.

- - Use a message that describes the user-visible or maintainer-visible change, not the implementation trivia.

- - Prefer one focused commit over a mixed commit. Split commits when changes are independently reviewable.

- - Do not amend someone else's commit or rewrite published history without explicit instruction.

- - If hooks fail, inspect the failure and fix the cause when in scope. Do not bypass hooks with `--no-verify` unless explicitly requested.

- Commit message shape:

- ```text

- Short imperative summary following repository convention; use 72 characters as a fallback readability guideline

- Optional body explaining motivation, compatibility, or risk.

- ```

- ## Rebase, Merge, Cherry-Pick, Revert

- Use history-changing operations deliberately and only after inspecting state.

- - Rebase: use for replaying local unpublished commits or when the user requests it. Check upstream and dirty state first. Stop on conflicts, resolve, validate, then `git rebase --continue`; use `git rebase --abort` if the operation should be abandoned.

- - Merge: use when preserving branch topology matters. Consider `git merge --no-commit --no-ff <branch>` for inspectable integration before committing.

- - Cherry-pick: inspect the source commit with `git show --stat <commit>` and `git show <commit>` first. Use `git cherry-pick -x <commit>` for public backports when provenance matters.

- - Revert: prefer `git revert <commit>` over history rewriting for published commits. For merge commits, verify the mainline parent and use `git revert -m <parent> <merge>`.

- - After any operation, run status, inspect resulting diff or commit, and run risk-appropriate validation.

- Abort/continue commands:

- ```bash

- git rebase --continue

- git rebase --abort

- git merge --continue

- git merge --abort

- git cherry-pick --continue

- git cherry-pick --abort

- git revert --continue

- git revert --abort

- ```

- ## Conflict Handling

- - Start with `git status --short` and identify unmerged paths.

- - Inspect each conflict in context; do not blindly choose ours/theirs.

- - Understand operation semantics: during rebase, "ours" is the rebased-onto side and "theirs" is the commit being replayed.

- - Resolve files, stage only resolved paths, and continue the active operation.

- - Validate after conflict resolution, especially for generated lockfiles, migrations, submodules, and binary files.

- - If conflict state is confusing, stop and report the safest next command instead of improvising.

- Helpful commands:

- ```bash

- git diff --name-only --diff-filter=U

- git diff

- git ls-files -u

- git status --short --branch

- ```

- ## Stash And Worktree

- Prefer worktrees for parallel work that should not disturb the current tree:

- ```bash

- git worktree list

- git worktree add <absolute-or-verified-sibling-path> -b <branch>

- git worktree remove <path>

- ```

- - Before adding a worktree, verify the target path is absolute or an intended sibling path, does not already exist with unexpected contents, and is outside the current worktree.

- - Before removing a worktree, inspect `git worktree list`, verify the target path, and run `git -C <path> status --short --branch`. Do not remove a dirty worktree or one with untracked/ignored work unless the user explicitly asks after the risk is known.

- Use stash when temporarily shelving local changes is the safest option:

- ```bash

- git stash push -u -m "<clear reason>"

- git stash show --stat stash@{0}

- git stash show -p stash@{0}

- git stash apply stash@{0}

- git stash drop stash@{0}

- ```

- Do not use `git stash clear`. Do not pop a stash unless immediate deletion on successful apply is intended; prefer `apply`, inspect, then `drop`.

- ## Tags, Remotes, And Pushes

- - Inspect remotes with `git remote -v` before fetch/push operations.

- - Fetch before comparing local and remote state.

- - Treat pushes as external side effects. Push only when the user asks or the workflow explicitly calls for it.

- - For an explicitly authorized history rewrite, never use plain `--force`. Verify the remote ref and prefer `--force-with-lease=<ref>:<expected-oid>`; an unqualified lease can be weakened by background fetches, and any lease protects only the named expectation.

- - For tags, prefer annotated tags for releases: `git tag -a <tag> -m "<message>"`. Verify target commit with `git show <tag>` or `git rev-parse <tag>^{}`.

- - Do not delete or move local or remote tags without explicit instruction.

- ## Submodules

- Submodules have separate repositories and can contain independent user changes.

- - Inspect superproject and submodule state: `git submodule status --recursive`, then `git -C <submodule> status --short --branch`.

- - Update submodules only when requested or required by the task.

- - When changing a submodule commit, inspect and validate inside the submodule, then stage the gitlink change in the superproject.

- - Do not run recursive reset, clean, deinit, or checkout across submodules without explicit permission and a verified recovery path.

- ## Untrusted Repositories

- - Treat repositories from unknown sources as untrusted until inspected. Do not run hooks, build scripts, package scripts, or tooling from them unless the task requires it and the risk is acceptable.

- - Do not set `safe.directory=*`. If Git blocks an operation due to ownership, verify the repository path and add only that exact path when necessary.

- - When cloning from a local path controlled by another user or an untrusted source, avoid hardlink/object-sharing surprises by using `git clone --no-local <path> <dest>` when isolation matters.

- ## Hooks

- - Treat hooks as repository policy. Let them run by default.

- - If a hook edits files, inspect the resulting diff before proceeding.

- - If hooks are missing dependencies or are broken outside the requested scope, report the blocker and the attempted command.

- - Do not bypass hooks, edit hook scripts, or disable hook configuration unless explicitly asked.

- ## Investigation: Log, Blame, Bisect

- Use history tools to ground claims:

- ```bash

- git log --oneline --decorate -- <path>

- git log -p -S'<text>' -- <path>

- git blame -L <start>,<end> -- <path>

- git show --stat <commit>

- git show <commit>

- ```

- Use bisect for regressions with a known good and bad commit:

- ```bash

- git bisect start

- git bisect bad <bad>

- git bisect good <good>

- git bisect run <test-command>

- git bisect reset

- ```

- Always run `git bisect reset` before leaving the task. If the test command mutates files, inspect status after reset.

- ## Cleanup And Recovery

- - Use `git restore --staged <path>` to unstage without changing the working tree.

- - Use `git restore <path>` only for changes you own and intend to discard.

- - Use `git clean -nd` first to preview untracked deletion. Require explicit user intent before `git clean -fd`, and be more cautious with `-x`.

- - Avoid `git reset --hard`. If a hard reset is explicitly requested, first show status, branch, target commit, and recovery information.

- - Use recovery tools before assuming data is lost:

- ```bash

- git reflog

- git show ORIG_HEAD

- git fsck

- git stash list

- ```

- Treat reflog and unreachable-object recovery as local, best-effort, and time-limited. Reflogs expire and unreachable objects can be pruned. After locating an object, immediately protect it with an appropriate branch, tag, ref, patch, or bundle before further cleanup.

- Use `git fsck --lost-found` only when its repository-metadata writes into `.git/lost-found` are intentional and authorized; inspect with read-only `git fsck` options first.

- If recovery involves another person's work, preserve evidence first with a branch, tag, patch file, or bundle before attempting cleanup.

- Read [safety, rewriting, and recovery](references/safety-and-recovery.md) before force updates, history rewriting, cleanup, worktree removal, or recovery.

- ## Validation

- Choose checks based on risk:

- - Git-state validation: `git status --short --branch`, `git diff`, `git diff --staged`, `git log --oneline --max-count=5`

- - Integrity validation: `git fsck` only when repository corruption or recovery is suspected

- - Code validation: run the repo's cheapest relevant formatter, typecheck, lint, or tests from project instructions

- - Commit validation: `git show --stat HEAD` and `git show --check HEAD`

- - Push validation: compare local and upstream with `git log --oneline --left-right HEAD...@{upstream}`

+ 1. Establish the authorized operation, repository root, branch, upstream and intended remote. Read project rules, signing requirements and PR templates. Inspect `git status --short --branch`, staged and unstaged diffs, untracked files and unfinished merges, rebases or cherry-picks. Do not take over someone else's unfinished operation. Use `git --no-pager` for log, diff, show and other paged output, and prevent unexpected editor or credential prompts.

+ 2. Identify pre-existing work, including staged changes. Stage only task-owned paths or hunks after reviewing them. Never stage an entire mixed-ownership file. Broad `git add .`, `git add -A` and `git commit -a` require review of everything they include. For non-interactive partial staging use a reviewed patch with the existing tool, not a hung interactive prompt or a working-tree reset.

+ 3. Before preparing a commit message or PR description, read [message guidance](references/messages.md). Keep each commit coherent and independently understandable. Include related tests and required documentation, without unrelated cleanup.

+ 4. Verify the prospective commit's full file list and diff, including new files, and run `git diff --cached --check` plus relevant project checks. Account for unstaged changes on which working-tree tests depend. Preserve unrelated staged work. `git commit --only -- <paths>` takes current working-tree contents for those paths and loses partial-staging boundaries within them. Use it only for wholly task-owned paths after inspecting the exact proposed content.

+ 5. Commit only when authorized, with an explicit message that will not open an editor. Preserve configured authorship, signing and required hooks. Inspect the resulting SHA, message, files and remaining status. A requested commit does not authorize push, release, deployment or notifications.

+ 6. For an authorized update fetch the intended remote, then inspect divergence from the intended branch. Do not integrate over unreviewed uncommitted changes. Use an explicit fast-forward-only update for non-divergent history, such as `git pull --ff-only <remote> <branch>`. For divergence apply repository policy and task authorization before choosing merge or rebase. Never interpret a rejected fast-forward as permission to rewrite history.

+ 7. For merge preserve both histories and review the resulting tree. For an authorized rebase identify the exact unpublished range and new base before replaying it. Published-history rewriting needs specific authorization. In conflicts read base and both sides, preserve their intent, stage only resolved task files and rerun affected checks. Use the operation's continue command with the reviewed message and non-interactive editor settings where needed. Abort only an operation started by this task when that is the chosen recovery. Do not auto-select ours/theirs or skip a conflicting commit to obtain a green status.

+ 8. Before push review the destination and complete outgoing range, including commits predating the task, and workflows/notifications publication triggers. Use an explicit remote and refspec. If rejected because the remote advanced, fetch and inspect the new work. Only for an explicitly authorized rewrite use targeted `--force-with-lease=<ref>:<reviewed-expected-SHA>`. An implicit lease can be weakened by background fetches. Never use blind force or bulk branch/tag publication as a rejection fix.

+ 9. Honor notification restrictions. Inspect existing suppression mechanisms only for the authorized publication. Do not disable workflows permanently or bypass required checks. GitHub skip markers apply only to certain events and can leave required checks pending, so do not add them by default. Verify current applicability when suppression is requested.

+ 10. When a PR is requested follow its template and the final implementation. After push verify the remote SHA. Use the host's required PR linking and status mechanisms and, if waiting is required, its watcher. Report commit, push, CI and deployment as separate outcomes, with only observed checks and concrete blockers.

- ## References

+ Never discard or hide others' work with reset, restore, clean or stash. Without an explicit request do not amend or rewrite existing history, delete branches/tags, force-push, create a commit, publish a branch or open a PR. Do not invent coauthors, acknowledgments or sign-offs, bypass hooks with --no-verify, disable signing, change global Git configuration, or suppress checks to finish the task. Existing authorization persists within its stated scope and does not need repeated confirmation.

- - Read [safety, rewriting, and recovery](references/safety-and-recovery.md) for state machines, explicit leases, machine-readable status, worktree/stash safety, and best-effort recovery.

- - Read [authoritative Git sources](references/sources.md) for current command semantics and source classification. Pin the installed Git version before using version-sensitive flags.

+ Use the installed Git version's [add](https://git-scm.com/docs/git-add), [commit](https://git-scm.com/docs/git-commit), [pull](https://git-scm.com/docs/git-pull), [merge](https://git-scm.com/docs/git-merge), [rebase](https://git-scm.com/docs/git-rebase) and [push](https://git-scm.com/docs/git-push) references when option behavior matters.