holocron/plugins/git/.apm/skills/git-history/SKILL.md

name, description, metadata, allowed-tools

name	description	metadata	allowed-tools
git-history	Use when investigating git history — pickaxe (`-S`/`-G`) or `-L` line-range log queries, tracing when a change landed, bisecting what broke something, or locating a commit to revert or backport. Not authoring or rebasing commits -> `git-commits`. Not a Gitea server's history -> `gitea-branches`.	version category source_keys 1.0.2 git git-scm-bisect-docs git-scm-log-docs git-scm-diff-docs	Bash

Gotchas

• -S"string" matches only where the string's count changed, so a line edited in place matches -G"regex" and not -S. Reach for -G whenever the string may have moved rather than appeared.
• --follow traces renames for exactly one path. Given several paths or a glob it fails instead of degrading, so run it once per file.
• Under git bisect run, exit 128 or above aborts the session rather than marking the commit bad, so a crashing test script ends the search silently.
• Bisect answering "cannot find exact culprit" beside skipped commits is a complete result: it is as precise as the skip range allows.

Step 1 — Pick the entry procedure

What is known	Procedure
Content, a file, or a line range to search for	Query the log — Step 2
Nothing to search for — only that the behaviour changed between two points	Bisect — read references/bisect.md
The commit itself, already identified	Step 3

Step 2 — Query the log

Default to rtk git log --oneline, then narrow by whatever is known:

• Content: rtk git log -S"string", or -G"regex" to match any diff line. --pickaxe-regex makes the -S argument a POSIX ERE; --pickaxe-all shows every file in a matching changeset.
• A line or function: git log -L <start>,<end>:<file> or git log -L :<function>:<file> — bare, not rtk: rtk truncates each diff line at ~72 characters. Confirm the range resolves before reporting on it — an off-by-one silently omits the target.
• A file across renames: rtk git log --follow -- <file>. Without --follow the history stops at the rename boundary.
• Mainline only: --first-parent follows the integration branch and skips commits merged in from side branches.
• Structured output: rtk git log --format="%h | %s | %an (%ar)".

If you need the placeholder catalogue, format presets, --diff-filter letters, full -L syntax, ancestry filters, pickaxe binary-file behaviour, or git diff output-control flags such as --stat, --word-diff and the whitespace options, read references/git-log-format.md.

Step 3 — Act on a located commit

Offer the operation and its consequence; run it only once the user has chosen.

• Backporting the commit to another branch is a cherry-pick, and cherry-pick is git-commits' — it owns the destination-branch check, the rtk git wrapper and the --abort path. Hand it the SHA; do not run git cherry-pick from here.
• rtk git revert <commit> adds a new commit undoing it — for un-applying merged work without rewriting history.
• rtk git blame <file> attributes each line to the commit that last touched it, when the question is which commit introduced one specific line.

For diff output control on the located commit, read references/git-log-format.md.

Step 4 — Return the result

Report each located commit in this shape, so a calling agent can act on it without reparsing raw log output:

<sha> — <subject>
<author> (<relative date>)
Recommendation: <action or "none">