feat(git-plugin): add complete git workflow automation suite
## Why The git plugin only covered a partial slice of common git workflows. This adds the remaining skill set (branches, commits, history, remotes, submodules, workflow, worktrees) plus a git-orchestrate agent so the plugin can handle end-to-end git automation instead of a handful of commands. ## Implementation Notes Each new skill was validated against its research docs and org conventions after initial authoring, which surfaced hallucinated version pins, factual errors, and completeness gaps that were corrected in the same pass rather than left for follow-up. ## Impact Bumps the git plugin to 1.3.0. Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
24
plugins/git/skills/git-history/README.md
Normal file
24
plugins/git/skills/git-history/README.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# git-history
|
||||
|
||||
Inspect git history — log queries, bisect, and locating problematic commits.
|
||||
|
||||
## What it does
|
||||
|
||||
This skill handles history inspection within the git workflow suite. It queries logs with pickaxe/line-range/custom formats, runs bisect to find bug-introducing commits, and locates commits for downstream cherry-picking or reverting. It returns structured results for agent composition. Rebase, squash, fixup, and other history-rewriting operations are owned by git-commits, not this skill.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/git-history
|
||||
```
|
||||
|
||||
Describe your history task: search logs, bisect for a regression, or locate a specific commit. The skill will query history and return structured results.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `references/git-log-format.md` | Full log format placeholders, diff-filter letters, `-L` syntax, ancestry filters, diff output-control flags |
|
||||
| `references/sources.md` | Research sources and provenance |
|
||||
| `references/README.md` | Index of the references directory |
|
||||
96
plugins/git/skills/git-history/SKILL.md
Normal file
96
plugins/git/skills/git-history/SKILL.md
Normal file
@@ -0,0 +1,96 @@
|
||||
---
|
||||
name: git-history
|
||||
|
||||
description: >
|
||||
Inspect git history: query logs with pickaxe, line-range, or custom formats; find bug origins via bisect; locate problematic commits for cherry-picking or reverting. Use when investigating history, tracing when a change happened, or finding the commit that broke something. Return structured results for downstream agents. Do not use for authoring or formatting commit messages, or executing rebase/squash/fixup operations — use git-commits for that.
|
||||
|
||||
metadata:
|
||||
category: git
|
||||
source_keys:
|
||||
- git-scm-bisect-docs
|
||||
- git-scm-log-docs
|
||||
- git-scm-diff-docs
|
||||
|
||||
allowed-tools: Bash
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Pickaxe searches (`-S` vs `-G`)**: `-S"string"` finds commits where string count changed; `-G"regex"` finds any line matching regex in diffs. They're not equivalent: a line replaced (one removal + one addition) matches `-G` but not `-S` if count is unchanged.
|
||||
- **`--follow` only works for single files**: it traces renames but fails with multiple paths or directory globs. Use `git log -- <single-file>` or query without `--follow`.
|
||||
- **Bisect with skips**: if bisect cannot pinpoint a commit because the culprit is adjacent to skipped commits, it reports "cannot find exact culprit" and lists candidates. This is not a failure — it's as precise as the skip range allows.
|
||||
- **Interactive rebase is non-recoverable on mistake**: there's no undo once `rebase -i` starts. Suggest `git reflog` to recover if the user realizes mid-way they selected the wrong commits.
|
||||
- **`-L` (line-range history) requires exact line numbers or regex patterns**: off-by-one errors omit the target range. Test the range with `git log -L` before offering it to users.
|
||||
|
||||
## Query Logs and Locate Commits
|
||||
|
||||
Default to `git log --oneline` for quick inspection. For deeper queries:
|
||||
|
||||
- **Find when a string appeared or disappeared**: Use `git log -S"string"` (count-sensitive, finds adds/removes). If you need any mention of the string in diffs, use `git log -G"regex"` instead. Add `--pickaxe-regex` to treat the `-S` string as a POSIX ERE, and `--pickaxe-all` to show every changed file in a matching changeset, not just the matching ones. Binary files are searched by `-S`; `-G` ignores them unless `--text` is also supplied.
|
||||
- **Trace changes to a specific line or function**: Use `git log -L <start>,<end>:<file>` or `git log -L :<function>:<file>` (requires function name heuristic). This shows the evolution of that range across all commits.
|
||||
- **Filter by change type**: Use `git log --diff-filter=<type>` (A=added, M=modified, D=deleted, R=renamed) to narrow to specific file operations.
|
||||
- **Mainline-only history through merges**: Use `--first-parent` to follow only the integration branch and skip merged-in side-branch commits; combine with `--merges`/`--no-merges` or `--ancestry-path`/`--min-parents`/`--max-parents` for other ancestry-graph filtering — see `references/git-log-format.md` for the full set.
|
||||
- **Custom format for structured output**: Construct format string with `%h` (hash), `%s` (subject), `%an` (author), `%ar` (relative date), `%b` (body). Example: `git log --format="%h | %s | %an (%ar)"`.
|
||||
- **File-specific history with renames**: Use `git log --follow -- <file>` (single file only). Without `--follow`, log stops at the rename boundary.
|
||||
|
||||
## Bisect to Find Blame Commit
|
||||
|
||||
Use bisect when hunting for the commit that introduced a bug or behaviour change. Binary search reduces iterations from O(N) to O(log N).
|
||||
|
||||
**Basic manual flow:**
|
||||
```bash
|
||||
git bisect start
|
||||
git bisect bad [HEAD] # mark current (or specified) as broken
|
||||
git bisect good <commit> # mark known-good baseline
|
||||
# Git checks out midpoint; test it manually
|
||||
git bisect good # if test passes
|
||||
git bisect bad # if test fails
|
||||
# Repeat until git reports "X is the first bad commit"
|
||||
git bisect reset # return to original HEAD
|
||||
```
|
||||
|
||||
**Automated with `git bisect run`:** if a test command exists, use `git bisect run <cmd>`. Git interprets the exit code: `0`=good, `1-124`=bad, `125`=skip (build broken), `126-127`=POSIX shell errors treated as bad, `128+`=**aborts the bisect session entirely** (not treated as bad — a crashed test script can silently end the search).
|
||||
|
||||
**With skip:** if a commit is untestable (broken build), use `git bisect skip` to exclude it without manually deciding good/bad. If the first-bad is adjacent to skips, bisect reports it cannot pinpoint but lists candidates.
|
||||
|
||||
**Undoing a wrong good/bad call:** `git bisect log` prints the session's decision history; save it (`git bisect log > bisect.log`), edit out the mistaken entry, then `git bisect reset && git bisect replay bisect.log` to resume from the corrected log instead of restarting the whole search.
|
||||
|
||||
**Narrowing and speeding up the search:** `git bisect start HEAD v1.2 -- src/` limits bisection to a path, cutting the number of trials. `--no-checkout` updates the `BISECT_HEAD` ref instead of checking out a working tree (useful for tests that don't need one; automatic in bare repos). `--first-parent` follows only first parents at merges, finding the integration commit that introduced a regression while ignoring broken side branches.
|
||||
|
||||
**Inspecting remaining candidates visually:** `git bisect visualize` (alias `view`) opens the suspects in gitk; add `--stat` or `-p` to show diffstat or full patches instead. Falls back to `git log` when no graphical display is detected.
|
||||
|
||||
**For non-regression hunts:** use `git bisect start --term-new <new> --term-old <old>` to search for a property change instead of a bug (e.g., performance regression). Then use the custom terms instead of `good`/`bad`.
|
||||
|
||||
For rebase execution (interactive rebase, squash/fixup/reword, conflict handling) see git-commits — it owns history-rewriting operations. This skill only locates commits and reports on history; it does not execute rebases.
|
||||
|
||||
## Find and Manipulate Problematic Commits
|
||||
|
||||
Once a commit is identified (via log query or bisect), offer cherry-pick or revert. This section is general git knowledge, not sourced from `history-inspection.md` — `git-branches`'s SKILL.md explicitly delegates cherry-pick/revert here (see its Merging section), which is why this skill carries them rather than treating them as out of scope:
|
||||
|
||||
- **Cherry-pick**: `git cherry-pick <commit>` copies a commit's changes onto current HEAD. Use when backporting fixes to other branches.
|
||||
- **Revert**: `git revert <commit>` creates a new commit that undoes the changes. Use when un-applying a merged commit without rewriting history.
|
||||
- **Blame for context**: `git blame <file>` shows which commit last changed each line. Use to trace a specific line back to its introducing commit.
|
||||
|
||||
## Inspect Diffs
|
||||
|
||||
Diff-output tuning is in scope too: `--stat` for a diffstat summary, `--word-diff` for word-level (not line-level) changes, and whitespace flags (`-w`, `--ignore-blank-lines`) to suppress noise from reformatting. See `references/git-log-format.md` for the full flag set.
|
||||
|
||||
## Return Results Structured
|
||||
|
||||
For agent consumption, return:
|
||||
- **Commit SHA** (full or abbreviated as appropriate)
|
||||
- **Subject line** (from `%s`)
|
||||
- **Author and date** (from `%an` and `%ar`)
|
||||
- **Action taken or recommended** (e.g., "Found via bisect", "Offer cherry-pick to main", "Rebase conflicts detected")
|
||||
|
||||
Example for agent:
|
||||
```
|
||||
Found first bad commit: abc1234
|
||||
Subject: fix null pointer in parser
|
||||
Author: Alice (2 weeks ago)
|
||||
Recommendation: Backport to release branch via cherry-pick
|
||||
```
|
||||
|
||||
## Reference
|
||||
|
||||
For the full log format placeholder catalogue, named format presets, `--diff-filter` letters, `-L` range syntax, ancestry filters, and `git diff` output-control flags, read `references/git-log-format.md`.
|
||||
15
plugins/git/skills/git-history/references/README.md
Normal file
15
plugins/git/skills/git-history/references/README.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
source_keys:
|
||||
- git-scm-bisect-docs
|
||||
- git-scm-log-docs
|
||||
- git-scm-diff-docs
|
||||
---
|
||||
|
||||
# References
|
||||
|
||||
This directory contains provenance metadata and research sources for the `git-history` skill.
|
||||
|
||||
## Files
|
||||
|
||||
- `sources.md` — Extracted research sources and their contributing documents
|
||||
- `git-log-format.md` — Full `git log` format placeholder catalogue, named format presets, `--diff-filter` letters, `-L` line-range syntax, ancestry filters, and `git diff` output-control flags
|
||||
232
plugins/git/skills/git-history/references/git-log-format.md
Normal file
232
plugins/git/skills/git-history/references/git-log-format.md
Normal file
@@ -0,0 +1,232 @@
|
||||
---
|
||||
topic: git-log-format
|
||||
source_keys:
|
||||
- git-scm-log-docs
|
||||
- git-scm-diff-docs
|
||||
---
|
||||
|
||||
## Named Format Presets (`--format` / `--pretty`)
|
||||
|
||||
| Name | Output |
|
||||
|---|---|
|
||||
| `oneline` | `<hash> <title>` |
|
||||
| `short` | hash, author, title |
|
||||
| `medium` | hash, author, date, full message (default) |
|
||||
| `full` | adds committer |
|
||||
| `fuller` | separate author/committer dates |
|
||||
| `reference` | `<abbrev> (<title>, <date>)` — for use in commit messages |
|
||||
| `email` | RFC 2822 email format |
|
||||
| `raw` | full object as stored in the object database |
|
||||
| `format:<str>` | custom template with placeholders |
|
||||
|
||||
## Custom Format Placeholders
|
||||
|
||||
**Commit identity:**
|
||||
|
||||
| Placeholder | Meaning |
|
||||
|---|---|
|
||||
| `%H` | full commit hash |
|
||||
| `%h` | abbreviated commit hash |
|
||||
| `%T` | tree hash |
|
||||
| `%t` | abbreviated tree hash |
|
||||
| `%P` | full parent hashes |
|
||||
| `%p` | abbreviated parent hashes |
|
||||
|
||||
**Author:**
|
||||
|
||||
| Placeholder | Meaning |
|
||||
|---|---|
|
||||
| `%an` | author name |
|
||||
| `%aN` | author name (mailmap-resolved) |
|
||||
| `%ae` | author email |
|
||||
| `%aE` | author email (mailmap-resolved) |
|
||||
| `%ad` | author date (respects `--date=`) |
|
||||
| `%ar` | author date, relative |
|
||||
| `%at` | author date, UNIX timestamp |
|
||||
| `%ai` | author date, ISO 8601-like |
|
||||
| `%aI` | author date, strict ISO 8601 |
|
||||
| `%as` | author date, short (YYYY-MM-DD) |
|
||||
|
||||
**Committer:**
|
||||
|
||||
| Placeholder | Meaning |
|
||||
|---|---|
|
||||
| `%cn` | committer name |
|
||||
| `%ce` | committer email |
|
||||
| `%cd` | committer date (respects `--date=`) |
|
||||
| `%cr` | committer date, relative |
|
||||
| `%ct` | committer date, UNIX timestamp |
|
||||
| `%ci` | committer date, ISO 8601-like |
|
||||
| `%cs` | committer date, short |
|
||||
|
||||
**Message:**
|
||||
|
||||
| Placeholder | Meaning |
|
||||
|---|---|
|
||||
| `%s` | subject (first line) |
|
||||
| `%f` | sanitized subject (filename-safe) |
|
||||
| `%b` | body (everything after blank line following subject) |
|
||||
| `%B` | raw body (subject + body) |
|
||||
| `%N` | commit notes |
|
||||
|
||||
**Refs and decorations:**
|
||||
|
||||
| Placeholder | Meaning |
|
||||
|---|---|
|
||||
| `%d` | ref names (like `--decorate`) |
|
||||
| `%D` | ref names without surrounding parentheses |
|
||||
| `%S` | ref name by which commit was reached (requires `--source`) |
|
||||
| `%(decorate[:opts])` | custom decorated refs; options: `prefix=`, `suffix=`, `separator=`, `pointer=`, `tag=` |
|
||||
| `%(describe[:opts])` | like `git describe`; options: `tags=`, `abbrev=`, `match=`, `exclude=` |
|
||||
|
||||
**GPG signature:**
|
||||
|
||||
| Placeholder | Meaning |
|
||||
|---|---|
|
||||
| `%G?` | status: `G`=good, `B`=bad, `U`=unknown, `X`=expired, `R`=revoked, `N`=no signature |
|
||||
| `%GS` | signer name |
|
||||
| `%GK` | signing key ID |
|
||||
|
||||
**Trailers:**
|
||||
```
|
||||
%(trailers[:key=<k>][,only][,separator=<s>][,unfold][,keyonly][,valueonly])
|
||||
```
|
||||
|
||||
**Formatting / color:**
|
||||
|
||||
| Placeholder | Meaning |
|
||||
|---|---|
|
||||
| `%n` | newline |
|
||||
| `%%` | literal `%` |
|
||||
| `%Cred` / `%Cgreen` / `%Cblue` / `%Creset` | terminal colors |
|
||||
| `%C(<spec>)` | color per git-config spec |
|
||||
| `%<(<n>[,trunc])` | right-pad field to width n |
|
||||
| `%>(<n>)` | left-pad to width |
|
||||
|
||||
**Reflog** (requires `-g` / `--walk-reflogs`):
|
||||
|
||||
| Placeholder | Meaning |
|
||||
|---|---|
|
||||
| `%gD` | reflog selector (e.g. `refs/stash@{1}`) |
|
||||
| `%gd` | shortened reflog selector |
|
||||
| `%gs` | reflog subject |
|
||||
|
||||
## Pickaxe Search: -S and -G
|
||||
|
||||
**`-S<string>`** — finds commits where the **count** of `<string>` changed (i.e. the string was added or removed net). Does not match commits where the string merely appears in a diff hunk without a count change.
|
||||
|
||||
```bash
|
||||
git log -S"my_function"
|
||||
git log -S"my_function" --pickaxe-regex # treat as POSIX ERE
|
||||
git log -S"my_function" --pickaxe-all # show all files in matching changesets
|
||||
```
|
||||
|
||||
**`-G<regex>`** — finds commits where any added or removed **line** in the patch matches `<regex>`. Broader than `-S`: matches whenever the pattern appears in diff text regardless of count.
|
||||
|
||||
```bash
|
||||
git log -G"frotz\(nitfol"
|
||||
```
|
||||
|
||||
**Critical distinction:** given a diff that removes one occurrence of `foo` and adds one occurrence of `foo` (net change = 0):
|
||||
- `-S"foo"` — does **not** match (count unchanged)
|
||||
- `-G"foo"` — **matches** (pattern appears in patch text)
|
||||
|
||||
Binary files are searched by `-S`; ignored by `-G` unless `--text` is supplied.
|
||||
|
||||
## --diff-filter (full table)
|
||||
|
||||
Selects commits (in `git log`) or files (in `git diff`) by change type:
|
||||
|
||||
| Letter | Meaning |
|
||||
|---|---|
|
||||
| `A` | Added |
|
||||
| `C` | Copied |
|
||||
| `D` | Deleted |
|
||||
| `M` | Modified |
|
||||
| `R` | Renamed |
|
||||
| `T` | Type changed (regular file ↔ symlink ↔ submodule) |
|
||||
| `U` | Unmerged (conflict) |
|
||||
| `X` | Unknown (indicates a git bug) |
|
||||
| `B` | Pairing broken |
|
||||
|
||||
Lowercase letters **exclude** that type:
|
||||
```bash
|
||||
git log --diff-filter=ad # exclude added and deleted files
|
||||
git log --diff-filter=M # only show commits with modified files
|
||||
```
|
||||
|
||||
`C` and `R` only appear when copy/rename detection is enabled (`-C`, `-M` flags or `diff.renames` config).
|
||||
|
||||
## -L — Line Range History (full syntax)
|
||||
|
||||
Traces the evolution of a specific range of lines or a named function through commits. Implies `--patch`.
|
||||
|
||||
```bash
|
||||
git log -L 10,20:file.txt
|
||||
git log -L /start_pattern/,/end_pattern/:file.txt
|
||||
git log -L :myfunction:src/app.c
|
||||
git log -L /init/,+15:config.py # 15 lines after first match of /init/
|
||||
```
|
||||
|
||||
Range formats:
|
||||
|
||||
| Format | Meaning |
|
||||
|---|---|
|
||||
| `<n>` | Absolute line number (1-based) |
|
||||
| `/<regex>/` | First line matching regex from previous range end |
|
||||
| `^/<regex>/` | First line matching regex from file start |
|
||||
| `+<n>` / `-<n>` | Offset relative to `<start>` (end position only) |
|
||||
|
||||
Limitations: incompatible with `--raw`, `--numstat`, `--shortstat`, `--name-only`, `--name-status`, `--check`. Cannot use pathspec limiters alongside `-L`.
|
||||
|
||||
## Graph and Ancestry Filters
|
||||
|
||||
```bash
|
||||
git log --first-parent # at merges, follow only first parent (mainline evolution)
|
||||
git log --merges # only merge commits (≥2 parents); equivalent to --min-parents=2
|
||||
git log --no-merges # only non-merge commits; equivalent to --max-parents=1
|
||||
git log --ancestry-path D..M # only commits actually on the path from D to M
|
||||
git log --min-parents=<n> # include only commits with ≥ n parents
|
||||
git log --max-parents=<n> # include only commits with ≤ n parents
|
||||
```
|
||||
|
||||
`--ancestry-path` is significant: without it, `D..M` includes all commits reachable from M but not D — including side branches that merged into the path. With it, only commits directly between D and M are shown.
|
||||
|
||||
## git diff — Output Control
|
||||
|
||||
### --stat
|
||||
|
||||
```bash
|
||||
git diff --stat # diffstat: file names + ± bar
|
||||
git diff --stat=<width>,<name-width>,<count>
|
||||
git diff --compact-summary # alongside --stat: shows new/gone, +x/-x (executable), +l (symlink)
|
||||
git diff --numstat # machine-readable: <added>\t<deleted>\t<path>; - for binary
|
||||
```
|
||||
|
||||
### --name-only / --name-status
|
||||
|
||||
```bash
|
||||
git diff --name-only # only filenames, one per line
|
||||
git diff --name-status # status letter + filename per line
|
||||
```
|
||||
|
||||
`--name-status` uses the same status letters as `--diff-filter`.
|
||||
|
||||
### --word-diff
|
||||
|
||||
```bash
|
||||
git diff --word-diff # inline word-level diff with [-removed-] {+added+} markers
|
||||
git diff --word-diff=color # color only, no markers
|
||||
git diff --word-diff=porcelain # machine-readable: +/- prefixed lines, ~ for newlines
|
||||
git diff --word-diff-regex=<re> # define what counts as a "word"
|
||||
```
|
||||
|
||||
### Whitespace Flags
|
||||
|
||||
| Flag | Effect |
|
||||
|---|---|
|
||||
| `-b` / `--ignore-space-change` | Treat any run of whitespace as equivalent; ignore trailing whitespace |
|
||||
| `-w` / `--ignore-all-space` | Ignore all whitespace completely |
|
||||
| `--ignore-space-at-eol` | Ignore whitespace at end-of-line only |
|
||||
| `--ignore-blank-lines` | Ignore changes consisting entirely of blank lines |
|
||||
| `-I<regex>` / `--ignore-matching-lines=<re>` | Ignore changes where all changed lines match regex |
|
||||
31
plugins/git/skills/git-history/references/sources.md
Normal file
31
plugins/git/skills/git-history/references/sources.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
topic: history-inspection
|
||||
source_keys:
|
||||
- git-scm-bisect-docs
|
||||
- git-scm-log-docs
|
||||
- git-scm-diff-docs
|
||||
---
|
||||
|
||||
## git-scm-bisect-docs
|
||||
|
||||
Git bisect documentation covering binary search through commit history to find the commit that introduced a bug. Includes manual flow, automated mode with exit codes, skip patterns, and visualization options.
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/history-inspection.md
|
||||
- **Doc heading:** `## git bisect`
|
||||
- **Contributing files:** SKILL.md
|
||||
|
||||
## git-scm-log-docs
|
||||
|
||||
Git log documentation covering format presets, custom format placeholders (commit identity, author, committer, message, refs, GPG signature), pickaxe search (`-S` and `-G`), `--follow` for file renames, `--diff-filter`, and line-range history (`-L`).
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/history-inspection.md
|
||||
- **Doc heading:** `## git log — Format and Filtering`
|
||||
- **Contributing files:** SKILL.md, references/git-log-format.md
|
||||
|
||||
## git-scm-diff-docs
|
||||
|
||||
Git diff documentation covering output control (--stat, --name-only, --name-status, --word-diff) and whitespace handling flags.
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/history-inspection.md
|
||||
- **Doc heading:** `## git diff — Output Control`
|
||||
- **Contributing files:** references/git-log-format.md
|
||||
Reference in New Issue
Block a user