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:
@@ -26,6 +26,7 @@ allowed-tools: Bash Read
|
||||
- When a hook modifies files (e.g. `trailing-whitespace`, `end-of-file-fixer`), the commit is blocked intentionally — the staged version is stale. The fix is `git add -u && git commit`. Do NOT call `pre-commit install -f` here; that is for overwriting existing hooks, not re-staging.
|
||||
- `pre-commit autoupdate` modifies `.pre-commit-config.yaml` in-place. Re-read the file after calling it to show the user the updated `rev` values.
|
||||
- The `SKIP` env var requires exact hook `id` values, comma-separated, no spaces: `SKIP=check-yaml,gitleaks git commit -m "msg"`. A space after the comma silently skips nothing.
|
||||
- Never use `git commit --no-verify` (or `-n`) to bypass a failing hook. Hooks are the automated QA gate; bypassing them breaks the pipeline. Diagnose and fix the failure instead — see the hook-specific guidance below and in `references/failure-patterns.md`.
|
||||
- A stages mismatch — hook stage not installed — means the hook was added to the config but `pre-commit install` was not re-run with the correct `-t` flags. Hooks in stages not listed under `default_install_hook_types` will never fire.
|
||||
|
||||
## Route
|
||||
@@ -36,6 +37,7 @@ Determine intent from the user's request, then execute the matching operation:
|
||||
|---|---|
|
||||
| "run", "check", "verify", "test hooks" | `pre-commit run --all-files` (default) |
|
||||
| "staged", "simulate commit" | `pre-commit run` (staged files only) |
|
||||
| "CI", "changed files only", "diff range" | `pre-commit run --from-ref <base> --to-ref <head>` — prefer this over `--all-files` on large repos |
|
||||
| "install", "set up hooks", "wire into git" | `pre-commit install` — see Install |
|
||||
| "pre-create environments", "install-hooks", "warm cache" | `pre-commit install-hooks` — see Install |
|
||||
| "remove hooks", "uninstall", "tear down pre-commit" | `pre-commit uninstall` |
|
||||
@@ -71,7 +73,7 @@ Before running, check for existing hook files:
|
||||
ls .git/hooks/
|
||||
```
|
||||
|
||||
If any hook files exist (e.g. a hand-written `pre-commit`), `pre-commit install` will refuse and exit with an error — it will not overwrite them without `-f`. If files are present, warn the user: "Existing hook files found at `.git/hooks/<names>`. Running `pre-commit install -f` will replace them permanently. Proceed?" Wait for confirmation before using `-f`.
|
||||
If any hook files exist (e.g. a hand-written `pre-commit`), `pre-commit install` does NOT refuse or error — it defaults to migration mode, which runs the existing hook and pre-commit's hooks both. Only `-f` replaces the existing hook file outright, and that replacement is not reversible via `pre-commit uninstall` — uninstall only removes pre-commit from `.git/hooks/`, it does not restore whatever hand-written hook `-f` overwrote. If files are present, tell the user: "Existing hook files found at `.git/hooks/<names>`. Plain `pre-commit install` will run both; `pre-commit install -f` will overwrite them permanently instead. Proceed with plain install, or overwrite?" Wait for confirmation before using `-f`.
|
||||
|
||||
```bash
|
||||
pre-commit install
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
source_keys:
|
||||
- context7-pre-commit-com
|
||||
- pre-commit-com
|
||||
- context7-pre-commit-hooks
|
||||
- pre-commit-hooks-github
|
||||
---
|
||||
|
||||
# references/
|
||||
|
||||
| File | Purpose |
|
||||
|
||||
@@ -20,6 +20,8 @@ git commit -m "same message"
|
||||
|
||||
## Secret detected (gitleaks)
|
||||
|
||||
> Not sourced from the pre-commit research corpus (`context7-pre-commit-com`/`pre-commit-com` cover pre-commit itself, not gitleaks) — general tool knowledge, verify against gitleaks' own docs if precision matters.
|
||||
|
||||
Cause: gitleaks found a high-entropy string or known secret pattern in a staged file.
|
||||
|
||||
Suggestions:
|
||||
@@ -28,6 +30,8 @@ Suggestions:
|
||||
|
||||
## Shellcheck warning
|
||||
|
||||
> Not sourced from the pre-commit research corpus — general tool knowledge, verify against shellcheck's own docs if precision matters.
|
||||
|
||||
Cause: shellcheck found a shell script issue. The output includes the file path, line number, and SC-code.
|
||||
|
||||
Fix: Look up the SC-code on shellcheck.net or pass `--explain SCxxxx` to shellcheck for a detailed explanation. The most common fixes:
|
||||
@@ -35,6 +39,44 @@ Fix: Look up the SC-code on shellcheck.net or pass `--explain SCxxxx` to shellch
|
||||
- SC2046 (unquoted command substitution): wrap in double quotes.
|
||||
- SC2181 (check exit code of `$?`): use `if command; then` directly.
|
||||
|
||||
## `check-hooks-apply` fails
|
||||
|
||||
Cause: A hook's `files`/`types` filter matches zero files in the repo — the hook is dead weight.
|
||||
|
||||
Fix: Broaden the filter, or remove the hook if it no longer applies to this repo.
|
||||
|
||||
## `check-useless-excludes` fails
|
||||
|
||||
Cause: An `exclude` pattern matches no files.
|
||||
|
||||
Fix: Remove or fix the pattern.
|
||||
|
||||
## SSH cloning fails in CI
|
||||
|
||||
Cause: The CI environment lacks SSH credentials to clone hook repos over SSH.
|
||||
|
||||
Fix: Export `SSH_AUTH_SOCK` in the CI environment, or switch hook repo URLs to HTTPS.
|
||||
|
||||
## HTTP proxy needed
|
||||
|
||||
Cause: The CI/sandbox network requires a proxy to reach hook repos.
|
||||
|
||||
Fix:
|
||||
```bash
|
||||
export http_proxy=http://proxy.example.com:3128
|
||||
export https_proxy=http://proxy.example.com:3128
|
||||
export no_proxy=localhost,127.0.0.1
|
||||
```
|
||||
|
||||
## `rev` is a branch name — `autoupdate` broke it
|
||||
|
||||
Cause: Branch refs are mutable and drift over time; pre-commit resolves them once at install time, so pinning to a branch name (instead of a tag or commit SHA) leads to silent version drift.
|
||||
|
||||
Fix:
|
||||
```bash
|
||||
pre-commit autoupdate # finds the latest tag and rewrites rev in place
|
||||
```
|
||||
|
||||
## pretty-format-json fails but doesn't fix
|
||||
|
||||
Cause: `pretty-format-json` requires `args: [--autofix]` to modify files. Without it, the hook only fails.
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
- **URL:** context7:/pre-commit/pre-commit.com
|
||||
- **Description:** Official pre-commit.com documentation — installation, configuration schema, CLI reference, hook authoring, advanced features, troubleshooting
|
||||
- **Contributing files:** SKILL.md, references/failure-patterns.md
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/pre-commit/sources.md
|
||||
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## pre-commit-com
|
||||
@@ -13,7 +13,7 @@
|
||||
- **URL:** https://pre-commit.com/
|
||||
- **Description:** Pre-commit framework homepage — full docs covering install, config, CLI, hook authoring, stages, local hooks, meta hooks, hazmat helpers, CI integration
|
||||
- **Contributing files:** SKILL.md, references/failure-patterns.md
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/pre-commit/sources.md
|
||||
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## context7-pre-commit-hooks
|
||||
@@ -21,7 +21,7 @@
|
||||
- **URL:** context7:/pre-commit/pre-commit-hooks
|
||||
- **Description:** Official pre-commit-hooks collection — all available hook IDs with options and examples
|
||||
- **Contributing files:** (none)
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/pre-commit/sources.md
|
||||
- **Research doc:** plugins/git/docs/research/docs/pre-commit/hooks-reference.md § "pre-commit-hooks (official collection)"
|
||||
- **Status:** `extracted`
|
||||
|
||||
## pre-commit-hooks-github
|
||||
@@ -29,5 +29,5 @@
|
||||
- **URL:** https://raw.githubusercontent.com/pre-commit/pre-commit-hooks/main/README.md
|
||||
- **Description:** Official pre-commit-hooks README — complete hook listing with all args, categories, deprecated hooks, and latest version
|
||||
- **Contributing files:** (none)
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/pre-commit/sources.md
|
||||
- **Research doc:** plugins/git/docs/research/docs/pre-commit/hooks-reference.md § "pre-commit-hooks (official collection)"
|
||||
- **Status:** `extracted`
|
||||
|
||||
Reference in New Issue
Block a user