chore: drop the flat content mirror and native install support (ADR-0024)
apm becomes the only supported install path. The flat mirror at each plugin root existed solely so Claude Code's native `claude plugin install` could convention-scan plugin content (ADR-0017). With no native consumers, it cost ~20,000 tracked lines plus ~2,100 lines of sync tooling and ~88s of every push to guard content apm never reads — and its only automated gate, `claude plugin validate --strict`, passes on a plugin with zero content, so it could not detect the defect ADR-0017 was created to fix. Removes the mirror (213 files), the six per-plugin manifest pairs, sync-plugin-content.sh, its 1,289-line test, the orphaned marketplace-plugins.sh, and the check-plugin-content-sync and validate-plugins pre-push hooks. The root `marketplace:` block and .claude-plugin/ catalogue stay: apm's own marketplace consumers read that same file, so `<name>@holocron` short names keep working. tests/run-bats.sh now excludes .claude/skills/. apm installs from .apm/, which carries the tests/ dirs the mirror stripped, so deployed .bats files would otherwise be discovered and double-run. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
This commit is contained in:
@@ -1,19 +0,0 @@
|
||||
{
|
||||
"name": "git",
|
||||
"version": "1.3.7",
|
||||
"description": "Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.",
|
||||
"author": {
|
||||
"name": "Defame1297",
|
||||
"email": "defame1297@rkdr.net",
|
||||
"url": "https://git.dev.rkdr.net/Defame1297/"
|
||||
},
|
||||
"license": "MIT",
|
||||
"homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/git",
|
||||
"repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/git",
|
||||
"keywords": [
|
||||
"git",
|
||||
"vcs",
|
||||
"commit",
|
||||
"branch"
|
||||
]
|
||||
}
|
||||
19
plugins/git/.github/plugin/plugin.json
vendored
19
plugins/git/.github/plugin/plugin.json
vendored
@@ -1,19 +0,0 @@
|
||||
{
|
||||
"name": "git",
|
||||
"version": "1.3.7",
|
||||
"description": "Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.",
|
||||
"author": {
|
||||
"name": "Defame1297",
|
||||
"email": "defame1297@rkdr.net",
|
||||
"url": "https://git.dev.rkdr.net/Defame1297/"
|
||||
},
|
||||
"license": "MIT",
|
||||
"homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/git",
|
||||
"repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/git",
|
||||
"keywords": [
|
||||
"git",
|
||||
"vcs",
|
||||
"commit",
|
||||
"branch"
|
||||
]
|
||||
}
|
||||
@@ -1,88 +0,0 @@
|
||||
---
|
||||
name: git-orchestrate
|
||||
|
||||
description: Orchestrates git workflow operations for other agents. Invoke when a caller needs a multi-step or destructive git operation (rebase, force-push, branch deletion) coordinated across domain skills with safety gates, session context, and structured results.
|
||||
|
||||
source_keys:
|
||||
- context7-git-htmldocs
|
||||
- git-scm-docs
|
||||
- git-scm-worktree-docs
|
||||
- git-scm-submodule-docs
|
||||
- git-scm-remote-docs
|
||||
- conventional-commits-spec
|
||||
---
|
||||
|
||||
You are the orchestrator for the git plugin—a composable workflow dispatcher designed for other agents to invoke multi-step git operations reliably. Your one job is routing and safety-gating: you do not execute git logic yourself, you delegate to domain skills and enforce confirmation on destructive operations.
|
||||
|
||||
You act on the caller's real branch and session context (you explicitly carry forward `current_branch`), not a disposable copy — you do not run in an isolated worktree.
|
||||
|
||||
**Scope:** this orchestrator routes git-object operations only (commits, branches, worktrees, remotes, submodules, history). `pc-author` and `pc-run` (pre-commit config authoring and hook execution) are intentionally not routed here — they operate on `.pre-commit-config.yaml` and hook installation, not git objects. `git-workflow` is also not routed here, but for a different reason than `pc-author`/`pc-run`: it is a human-facing conversational wrapper for all git operation types (commits, branches, history, submodules, worktrees, remotes), and it itself calls this orchestrator internally as its execution backend — its own workflow explicitly invokes the `git-orchestrate` agent as its final step. It is not a peer to invoke instead of this dispatcher, and its own boundary clause sends agent callers here ("Not an agent caller -> `git-orchestrate`"). Agent callers route git-object operations here directly; direct human users to `git-workflow` when they want guided, conversational git help — it will call back into this orchestrator itself. Invoke `pc-author`/`pc-run` directly rather than through this dispatcher; do not invoke `git-workflow` as an agent caller under any circumstance.
|
||||
|
||||
## Hard rules
|
||||
|
||||
These are non-negotiable regardless of `confirm` or any skill-local override:
|
||||
- Never skip hooks with `--no-verify`. Hooks are the automated QA gate; bypassing them breaks the pipeline.
|
||||
- Never force-push `main` or `master`.
|
||||
- Keep commits atomic — one logical, independently reviewable and reversible change per commit.
|
||||
- Every commit must leave the repository in a working state (buildable/testable where practical).
|
||||
- Commit messages explain **why**, not **what** — the diff already documents what changed.
|
||||
- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.).
|
||||
- Never commit secrets, credentials, or environment-specific config.
|
||||
- Reference related issues, ADRs, or design documents using git trailers (`Fixes:`, `Refs:`, `ADR:`, `RFC:`, `Design:`) when applicable.
|
||||
|
||||
### Submodule ordering
|
||||
|
||||
- Commit and push the submodule first, then update and push the parent repo. Pushing the parent before the submodule commit exists on the remote breaks `git submodule update` for anyone who pulls.
|
||||
- Always use `rtk git` for parent-repo operations; drop into the submodule directory and use bare `git` for submodule-specific commands.
|
||||
- After adding or updating a submodule, check `git status` in both the parent and the submodule — a `-dirty` flag means the submodule has uncommitted local changes that must be committed before the parent pointer updates.
|
||||
|
||||
Sub-skills carry their own local copies of these rules for humans who invoke them directly, bypassing this orchestrator. When a caller routes through you, this section is the enforcement backstop: check every routed operation against it before dispatch, not just the destructive-operation confirm gate below.
|
||||
|
||||
When invoked, you:
|
||||
1. Parse the incoming workflow request (operation type, parameters, context overrides)
|
||||
2. Check safety gates: a destructive operation (force-push, branch deletion, history-losing rebase, force-checkout) without `confirm: true` fails immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm`
|
||||
3. Route to the appropriate domain skill: `git-commits`, `git-branches`, `git-history`, `git-submodules`, `git-worktrees`, `git-remotes`
|
||||
4. Manage session context: carry forward the current branch, workflow intent, and configuration, passing explicitly to each skill
|
||||
5. Handle error recovery: for recoverable failures (merge conflicts, push rejections, auth issues), attempt automatic recovery; if unrecoverable, fail gracefully with actionable diagnostics
|
||||
6. Aggregate results and return structured JSON output suitable for agent chaining
|
||||
|
||||
## Inputs
|
||||
|
||||
- **operation:** string, one of:
|
||||
- commits/history: commit, amend, cherry-pick, rebase, squash, blame, log
|
||||
- branches: create-branch, switch-branch, delete-branch, rename-branch, track-branch, list-branches
|
||||
- worktrees: create-worktree, list-worktrees, lock-worktree, unlock-worktree, move-worktree, remove-worktree, prune-worktree, repair-worktree
|
||||
- remotes: add-remote, remove-remote, rename-remote, set-remote-url, push, pull, fetch
|
||||
- submodules: add-submodule, init-submodule, update-submodule, sync-submodule, remove-submodule, submodule-status
|
||||
- **parameters:** object, operation-specific arguments (branch name, commit message, etc.)
|
||||
- **context:** object (optional), workflow state to carry forward (current_branch, branch_intent, user_config_overrides)
|
||||
- **confirm:** boolean (optional), explicit confirmation for destructive operations (required if not set for force-push, branch deletion, rebase with history loss, force-checkout)
|
||||
|
||||
## Process
|
||||
|
||||
1. Validate the request structure and check if operation is known
|
||||
2. Check the request against the Hard rules above (no `--no-verify`, no force-push `main`/`master`, atomicity, submodule ordering, etc.) — refuse outright on violation, independent of `confirm`
|
||||
3. If destructive operation: require `confirm: true`, else fail with structured "requires explicit confirmation" error
|
||||
4. Invoke the appropriate skill via `Skill` or direct bash call with the operation, parameters, and context — each domain skill infers its own branching pattern and conventions (e.g. `git-branches` from `develop`/`release/*` branch presence) rather than reading shared config. For parent-repo git invocations, use `rtk git` rather than bare `git` (per org convention); submodule-specific commands run as bare `git` inside the submodule directory (see Submodule ordering above).
|
||||
5. Catch and handle git errors: attempt automatic recovery (offer rebase strategies for conflicts, suggest `--force-with-lease` for rejections)
|
||||
6. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions
|
||||
7. Aggregate all outputs and return as structured JSON
|
||||
|
||||
## Output
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success" | "error",
|
||||
"operation": "<operation_name>",
|
||||
"result": {
|
||||
"output": "<command output or result>",
|
||||
"context": { "current_branch": "...", "workflow_intent": "..." }
|
||||
},
|
||||
"error": {
|
||||
"message": "<human-readable error>",
|
||||
"code": "<error type: conflict | auth_failure | push_rejection | invalid_state>",
|
||||
"recovery_attempted": true | false,
|
||||
"suggestions": ["<suggestion1>", "<suggestion2>"]
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -168,5 +168,4 @@ Local hooks in this repo:
|
||||
| Hook | Stage | Entry |
|
||||
|------|-------|-------|
|
||||
| `run-tests` | pre-push | `bash tests/run-tests.sh` |
|
||||
| `validate-plugins` | pre-push | `claude plugin validate --strict` per plugin dir |
|
||||
| `validate-marketplace` | pre-push | `claude plugin validate --strict .claude-plugin/marketplace.json` |
|
||||
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
name: git-branches
|
||||
|
||||
description: >
|
||||
Use when creating, switching, deleting, renaming, tracking, merging, or comparing
|
||||
local git branches under GitHub Flow or Gitflow.
|
||||
Not writing or rewriting commits -> `git-commits`.
|
||||
Not history inspection -> `git-history`.
|
||||
Not a Gitea remote's branches -> `gitea-branches`.
|
||||
|
||||
metadata:
|
||||
version: "1.0.4"
|
||||
category: git
|
||||
source_keys:
|
||||
- context7-git-htmldocs
|
||||
- nvie-gitflow-post
|
||||
- atlassian-gitflow-tutorial
|
||||
- gitflow-cheatsheet
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears.
|
||||
- **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list <name>` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous) and `rtk git tag --list <name>`; output from both means the name is ambiguous. Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/<name>` or `refs/tags/<name>`.
|
||||
- **`main`/`master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming either is rejected even with `confirm: true` — no flag recovers the remote's history. Offer a new branch instead.
|
||||
|
||||
## Step 1 — Determine the branching pattern
|
||||
|
||||
Infer the branching pattern from the repo: Gitflow if a `develop` or `release/*` branch exists, GitHub Flow otherwise (the default).
|
||||
|
||||
The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read `references/branch-patterns.md`.
|
||||
|
||||
## Step 2 — Dispatch on the action
|
||||
|
||||
| Action | Reference |
|
||||
|---|---|
|
||||
| create, switch, delete, rename, track, list, get-intent, stash | `references/branch-operations.md` |
|
||||
| merge a branch, resolve merge conflicts | `references/merging.md` |
|
||||
| compare two branches, find their divergence | `references/comparing-branches.md` |
|
||||
|
||||
Load only the file the action needs. A destructive action still passes Step 3 first.
|
||||
|
||||
## Step 3 — Gate destructive operations
|
||||
|
||||
Before any delete or force-delete that loses history:
|
||||
|
||||
- [ ] Does the branch track a remote? Warn if so.
|
||||
- [ ] Are there unpushed commits on it? Warn if so.
|
||||
- [ ] Did the caller pass `confirm: true`? Fail if not — for a human caller, prompt interactively instead of failing.
|
||||
|
||||
These gates are passable. The `main`/`master` refusal in Gotchas is not.
|
||||
|
||||
## Step 4 — Set tracking
|
||||
|
||||
A new branch's first push must be `rtk git push -u origin <branch>`. The push itself is `git-remotes`' — every remote-side gate lives there, which is why Step 2's remote-delete row hands off the same way — but the upstream requirement originates here, so carry it in the handoff. Without an upstream, later pushes and pulls either fail or silently target the wrong remote branch, and the caller has no way to tell which happened.
|
||||
|
||||
## Step 5 — Return a structured result
|
||||
|
||||
Return every operation in this shape rather than prose, including failures — a calling agent chains its next operation on the result and cannot parse a sentence.
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"action": "create|switch|delete|rename|track|list|get-intent",
|
||||
"branch": "<name>",
|
||||
"message": "descriptive message",
|
||||
"intent": "<intent if tracked>",
|
||||
"tracking": "origin/<branch, if set>",
|
||||
"error": "<error message if success=false>",
|
||||
"suggestion": "<recovery suggestion if applicable>"
|
||||
}
|
||||
```
|
||||
|
||||
When the failure is uncommitted local changes, set `"suggestion": "stash changes and retry"` so the caller can offer recovery rather than surfacing a dead end.
|
||||
|
||||
When a calling agent supplies a structured request rather than prose, read `references/orchestrator-contract.md` for the request schema.
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- context7-git-htmldocs
|
||||
---
|
||||
|
||||
# Per-action command mapping
|
||||
|
||||
One command per action. Where two forms exist, the first is the default and the second the escape
|
||||
hatch.
|
||||
|
||||
- **create** — `rtk git switch -c <branch> <base>`. Base comes from the config's `base_branch`
|
||||
(`main` under GitHub Flow, usually `develop` under Gitflow).
|
||||
- **switch** — `rtk git switch <branch>` moves to an existing local branch; it aborts rather than
|
||||
clobbering conflicting local changes. `rtk git switch -` returns to the previous branch.
|
||||
- **delete (local)** — `rtk git branch -d <branch>` refuses when the branch holds unmerged commits,
|
||||
which is why it is the default. `rtk git branch -D <branch>` forces the deletion and discards that
|
||||
work — only after the destructive-operation gates pass and `confirm: true` is set.
|
||||
- **delete (remote)** — not this skill's. Deleting a remote branch is a push, and every remote-side
|
||||
gate lives in `git-remotes`; hand it there rather than running the push from here. Its
|
||||
`references/push.md` carries the command and the refspec form.
|
||||
- **rename** — `rtk git branch -m <old> <new>`.
|
||||
- **list** — `rtk git branch` (local), `-a` (local plus remote-tracking), `-r` (remote-tracking only),
|
||||
`--merged` / `--no-merged` (filter by merge status into the current branch).
|
||||
- **track** — `rtk git branch --set-upstream-to=origin/<branch>` sets an upstream without pushing.
|
||||
`rtk git branch -vv` shows the tracking state of every local branch.
|
||||
|
||||
## get-intent
|
||||
|
||||
Git has no native field for free-text branch metadata, and this skill does not persist any. On
|
||||
`create`, the `intent` value is only returned in the structured result — the caller decides
|
||||
whether to store it.
|
||||
|
||||
On `get-intent`, either parse the intent back out of the branch-name convention
|
||||
(`feature/<intent-slug>`) or return `{ "intent": null }` when the caller never persisted the
|
||||
create-time value. Never fabricate an intent: a downstream commit message built on a guessed
|
||||
intent is worse than one built on none.
|
||||
|
||||
## Stashing work in progress
|
||||
|
||||
A switch aborts rather than clobbering conflicting local changes (see Gotchas). Stash is the way
|
||||
past it: it shelves the working tree and index so the branch pointer can move.
|
||||
|
||||
- **save** — `rtk git stash push -m "<message>"`. Add `-u` to include untracked files; verified on Git
|
||||
2.39.5, a plain `push` leaves them in place, and a plain `push` with *only* untracked changes
|
||||
reports `No local changes to save` and stashes nothing. Bare `git stash` is `push` with no message.
|
||||
- **restore** — `git stash pop` applies the newest entry and deletes it. Bare, not `rtk`: on a
|
||||
conflict rtk prints only `FAILED: git stash pop` and swallows the conflict report the paragraph
|
||||
below tells you to read. `rtk git stash apply stash@{n}`
|
||||
applies without deleting, for replaying one shelf onto more than one branch.
|
||||
- **list** — `git stash list` — bare, not `rtk`: rtk prints `No stashes` where git prints nothing,
|
||||
so an empty-output test misfires. `rtk git stash show -p stash@{n}` prints that entry's diff.
|
||||
- **drop** — `rtk git stash drop stash@{n}` deletes one entry. `rtk git stash clear` deletes all of them
|
||||
and nothing recovers them — confirm before running it.
|
||||
- **branch from a stash** — `rtk git stash branch <branch> stash@{n}` creates a branch at the commit the
|
||||
stash was taken from and pops it there. Use it when the stash no longer applies to the current tip.
|
||||
|
||||
**A conflicting `pop` keeps the entry.** Verified on 2.39.5: it exits 1, writes conflict markers,
|
||||
prints "The stash entry is kept in case you need it again", and `git stash list` still shows it.
|
||||
Resolve, `rtk git add`, then `rtk git stash drop` the entry by hand — otherwise it silently accumulates.
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- nvie-gitflow-post
|
||||
- atlassian-gitflow-tutorial
|
||||
- gitflow-cheatsheet
|
||||
---
|
||||
|
||||
# Branch patterns
|
||||
|
||||
Which pattern is in play decides the base branch, the branch name prefix, and whether merges are
|
||||
allowed to fast-forward. Default to GitHub Flow — simpler, and what CI/CD-oriented repos expect.
|
||||
Fall back to Gitflow only when the config says so or the repo already carries `develop` or
|
||||
`release/*` branches.
|
||||
|
||||
## GitHub Flow
|
||||
|
||||
- Base: `main`
|
||||
- Feature branches: `feature/<feature-name>` or `fix/<bug-name>`
|
||||
- Merge: fast-forward where possible, to keep history linear
|
||||
- Delete the branch after merge
|
||||
|
||||
## Gitflow
|
||||
|
||||
- Base: `main` (production) plus `develop` (integration)
|
||||
- Feature branches: `feature/<feature-name>`, cut from `develop`
|
||||
- Release branches: `release/X.Y.Z`, cut from `develop`, merged to both `main` and `develop`
|
||||
- Hotfix branches: `hotfix/X.Y.Z`, cut from `main`, merged to both `main` and `develop`
|
||||
- Merge: always `--no-ff`, so the branch structure survives in the history
|
||||
|
||||
The two are not mixable. A `--no-ff` merge into a GitHub Flow repo leaves merge commits nobody
|
||||
expects; a fast-forward merge of a Gitflow release branch erases the release boundary.
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- context7-git-htmldocs
|
||||
---
|
||||
|
||||
# Comparing two branches
|
||||
|
||||
The two-dot and three-dot forms mean different things and are easy to swap by accident — check the
|
||||
direction before reporting a result.
|
||||
|
||||
- `rtk git log main..feature` — commits on `feature` that are not on `main`.
|
||||
- `rtk git log feature..main` — the reverse direction: commits on `main` not on `feature`.
|
||||
- `rtk git log --left-right main...feature` — both diverging sets at once (symmetric difference).
|
||||
- `rtk git diff main...feature` — the diff from the common ancestor to `feature`'s tip, which is what
|
||||
a reviewer sees, rather than the diff between the two tips.
|
||||
- `rtk git merge-base main feature` — print the common ancestor commit.
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- context7-git-htmldocs
|
||||
- atlassian-gitflow-tutorial
|
||||
---
|
||||
|
||||
# Merging one branch into another
|
||||
|
||||
Scope is fast-forward and merge-commit mechanics plus conflict resolution. Rebase and cherry-pick
|
||||
belong to `git-commits`; revert to `git-history`.
|
||||
|
||||
- **Fast-forward** — `rtk git merge <branch>` advances the pointer with no merge commit when the
|
||||
target has not diverged.
|
||||
- **True merge** — `rtk git merge --no-ff <branch>` forces a merge commit even when a fast-forward is
|
||||
possible. Gitflow requires it on every supporting-branch merge.
|
||||
- **Squash merge** — `rtk git merge --squash <branch>` stages the combined diff without committing.
|
||||
Follow it with a `rtk git commit`.
|
||||
- **Octopus merge** — `rtk git merge branch-a branch-b branch-c` merges more than two branches at
|
||||
once, but fails outright on any conflict. Use sequential two-way merges when conflicts are
|
||||
likely.
|
||||
|
||||
## Conflict resolution
|
||||
|
||||
When Git cannot auto-merge it writes conflict markers and stops mid-merge. Run `rtk git status` to
|
||||
list the conflicted files, edit each to resolve its markers, then `rtk git add <file>` and
|
||||
`rtk git merge --continue`.
|
||||
|
||||
- `rtk git merge --abort` restores the pre-merge state.
|
||||
- `git mergetool` opens the configured merge tool — bare, not `rtk`: it hands control to an
|
||||
interactive child process, and a token filter has nothing to offer there.
|
||||
- `rtk git diff --diff-filter=U` shows only the still-conflicted files.
|
||||
@@ -1,20 +0,0 @@
|
||||
---
|
||||
source_keys: []
|
||||
---
|
||||
|
||||
# Orchestrator request contract
|
||||
|
||||
`git-orchestrate` and other calling agents send this shape. The result shape they parse back is in
|
||||
`SKILL.md` Step 5, because every run emits one.
|
||||
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create|switch|delete|rename|track|list|get-intent",
|
||||
"branch": "<branch-name>",
|
||||
"base": "<base branch, optional, defaults to config>",
|
||||
"intent": "<human-readable intent, optional>",
|
||||
"confirm": "<true for destructive ops, omit for read ops>"
|
||||
}
|
||||
```
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
# Research sources referenced by this skill
|
||||
# Each entry documents where the skill's guidance came from.
|
||||
---
|
||||
|
||||
## nvie-gitflow-post
|
||||
|
||||
**Description:** Original 2010 post by Vincent Driessen introducing the Gitflow branching model, including a 2020 reflection note recommending GitHub Flow for continuous delivery teams.
|
||||
|
||||
**Source:** https://nvie.com/posts/a-successful-git-branching-model/
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
|
||||
|
||||
**Contributing files:**
|
||||
- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
|
||||
- references/branch-patterns.md (Gitflow vs. GitHub Flow structure, defaults, and why the two are not mixable)
|
||||
|
||||
## atlassian-gitflow-tutorial
|
||||
|
||||
**Description:** Atlassian's comprehensive Gitflow tutorial covering all five branch types, lifecycle steps, and CLI usage.
|
||||
|
||||
**Source:** https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
|
||||
|
||||
**Contributing files:**
|
||||
- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
|
||||
- references/branch-patterns.md (Gitflow branch types, base/merge targets, `--no-ff` requirement)
|
||||
- references/merging.md (`--no-ff` requirement on Gitflow supporting-branch merges)
|
||||
|
||||
## gitflow-cheatsheet
|
||||
|
||||
**Description:** Visual cheatsheet for the git-flow CLI commands (git-flow-avh fork), covering all subcommands for feature, release, and hotfix branches.
|
||||
|
||||
**Source:** https://danielkummer.github.io/git-flow-cheatsheet/
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
|
||||
|
||||
**Contributing files:**
|
||||
- references/branch-patterns.md (feature/release/hotfix naming conventions)
|
||||
|
||||
## context7-git-htmldocs
|
||||
|
||||
**Description:** Official Git HTML documentation from the git/htmldocs repository — covers all commands, concepts, and internals.
|
||||
|
||||
**Source:** context7:/git/htmldocs
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/branching-merging.md (whole-document reference)
|
||||
|
||||
**Contributing files:**
|
||||
- SKILL.md (Gotchas — `git switch` abort-on-conflict behaviour, branch/tag name ambiguity)
|
||||
- references/branch-operations.md (`git switch`/`git branch` command vocabulary and flags)
|
||||
- references/merging.md (`git merge` strategies and conflict-resolution commands)
|
||||
- references/comparing-branches.md (`git log`/`git diff`/`git merge-base` range syntax)
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
name: git-commits
|
||||
|
||||
description: >
|
||||
Use when creating, amending, squashing, or cherry-picking commits, including
|
||||
writing and validating the Conventional Commits message.
|
||||
Not history inspection -> `git-history`.
|
||||
Not branch lifecycle -> `git-branches`.
|
||||
|
||||
metadata:
|
||||
version: "0.1.6"
|
||||
category: git
|
||||
source_keys:
|
||||
- conventional-commits-spec
|
||||
- commitlint-config-conventional
|
||||
- org-commit-conventions
|
||||
- context7-git-htmldocs
|
||||
|
||||
allowed-tools: Bash
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Run git as `rtk git <subcommand>`, never bare `git`** — org convention, in `&&` chains too, except where a skill's Gotchas name a specific bare-git case (interactive rebase here).
|
||||
- **Refuse to force-push `main`/`master`.** A rewrite diverges the branch and the reflex is to force it back — safe only where nobody else has based work on it.
|
||||
- **`reset --hard` is a confirmation gate, not a default.** It overwrites the working tree, and uncommitted edits it discards were never in git, so no reflog recovers them. Name what will be lost and offer a stash first.
|
||||
- **Never add `--no-verify`** — using it when a hook fails bypasses the QA gate the pipeline depends on. Only on the user's explicit demand, with a warning.
|
||||
|
||||
## Dispatch
|
||||
|
||||
Read exactly one flow file. Each is self-contained.
|
||||
|
||||
| Condition | Flow | Read |
|
||||
|---|---|---|
|
||||
| Composing a new commit from staged changes | create | `references/create-commit.md` |
|
||||
| Amending, squashing, folding a fixup, rebasing onto a new base, or resetting HEAD | rewrite | `references/rewrite-history.md` |
|
||||
| Replaying an existing commit onto the current branch | cherry-pick | `references/cherry-pick.md` |
|
||||
|
||||
## Gates on every flow
|
||||
|
||||
1. **Confirmation.** No history rewrite executes without explicit approval from the user or the calling agent. Cherry-pick needs the destination branch confirmed first.
|
||||
2. **Atomicity.** The result must be one logical, independently reviewable and reversible change that leaves the repository buildable and testable. This binds an amend or a squashed result as much as a fresh commit — say so before writing it, not after.
|
||||
3. **Secrets.** Before any commit or amend, scan the staged diff for anything resembling an API key,
|
||||
token, password, connection string, or environment-specific config. Stop and flag it rather than
|
||||
committing it.
|
||||
4. **Validation.** Check the message against commitlint `config-conventional` before committing. If a type, footer, or breaking-change edge case is not obvious, read `references/conventional-commits-spec.md` — it carries the constraint table, the 11-type set, and the footer token rules.
|
||||
5. **SemVer impact.** Report the bump the commit implies: `feat` → MINOR, `fix`/`perf`/`revert` → PATCH, any breaking change → MAJOR, everything else → none. Callers decide releases from this, so never omit it.
|
||||
6. **Conflicts.** If a rebase or cherry-pick halts, offer resolution or an abort. Do not resolve automatically without confirmation.
|
||||
|
||||
## Output
|
||||
|
||||
For an agent caller, return:
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "create|amend|squash|cherry-pick",
|
||||
"status": "success|conflict|rejected",
|
||||
"message": "commit message or error description",
|
||||
"commit_hash": "abc1234",
|
||||
"semver_impact": "MAJOR|MINOR|PATCH|none",
|
||||
"breaking_change": false,
|
||||
"confirmation_required": false,
|
||||
"details": {
|
||||
"type": "feat",
|
||||
"scope": "api",
|
||||
"description": "add user authentication",
|
||||
"body": "optional body text, or null",
|
||||
"footers": ["Fixes: #123", "Refs: #456", "Co-authored-by: Bob <bob@example.com>"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`details.footers` is an array of the resolved trailer lines, empty when there are none — never a
|
||||
single joined string, and never omitted. Downstream agents index it.
|
||||
|
||||
For a human caller, show the same fields as a prose preview with a confirmation prompt.
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- context7-git-htmldocs
|
||||
---
|
||||
|
||||
# Cherry-picking a commit
|
||||
|
||||
1. **Identify the source commit** — a hash or a branch reference.
|
||||
2. **Confirm the destination** — cherry-pick replays onto the branch currently checked out, so verify that is the intended branch before running anything.
|
||||
3. **Execute** — `rtk git cherry-pick <commit-hash>`. A range is `<a>..<b>` (exclusive of `<a>`) or `<a>^..<b>` (inclusive); `-n` stages without committing, for when the replay needs editing first.
|
||||
4. **Handle conflicts** — if the replay halts, offer resolution or `rtk git cherry-pick --abort`. Never resolve automatically without confirmation.
|
||||
5. **Report the outcome** — which commits replayed, which conflicted, and which were rejected.
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- org-commit-conventions
|
||||
---
|
||||
|
||||
# Commit Message Body Template
|
||||
|
||||
Use this structure for the body/footer of any non-trivial commit (skip sections that don't apply — do not leave placeholders in the actual commit).
|
||||
|
||||
```text
|
||||
<type>(<scope>): <concise summary>
|
||||
```
|
||||
The header is required. Describe the intended outcome, not the implementation.
|
||||
|
||||
## Why
|
||||
|
||||
Explain why this change exists. This is the most valuable part of the commit — the diff already shows *what* changed; future maintainers (human or AI) need *why*.
|
||||
|
||||
Include, where applicable:
|
||||
- Problem being solved
|
||||
- User or business need
|
||||
- Bug or root cause
|
||||
- Important context not visible in the code
|
||||
|
||||
Omit if the reason is immediately obvious.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
Capture decisions that are difficult to infer from the code:
|
||||
- Why this approach was chosen
|
||||
- Important assumptions or invariants
|
||||
- Constraints imposed by external systems
|
||||
- Tradeoffs or intentional compromises
|
||||
- Non-obvious implementation details
|
||||
- Workarounds or temporary solutions
|
||||
|
||||
Do NOT describe the diff ("renamed X", "added Y"). Omit if there's nothing worth preserving.
|
||||
|
||||
## Impact
|
||||
|
||||
Document effects future developers should know about:
|
||||
- Behavior changes
|
||||
- Breaking changes
|
||||
- Performance implications
|
||||
- Security considerations
|
||||
- Migration or deployment requirements
|
||||
- Compatibility concerns
|
||||
- Follow-up work or known limitations
|
||||
|
||||
Omit if there are no noteworthy impacts.
|
||||
|
||||
## Trailers
|
||||
|
||||
Structured metadata for traceability and tooling. Use only the trailers that apply:
|
||||
|
||||
```text
|
||||
Fixes:
|
||||
Refs:
|
||||
ADR:
|
||||
RFC:
|
||||
Design:
|
||||
Co-authored-by:
|
||||
Reviewed-by:
|
||||
Signed-off-by:
|
||||
BREAKING CHANGE:
|
||||
```
|
||||
@@ -1,170 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- conventional-commits-spec
|
||||
- commitlint-config-conventional
|
||||
---
|
||||
|
||||
# Conventional Commits Specification (v1.0.0)
|
||||
|
||||
Conventional Commits is a lightweight convention on top of commit messages that provides a set of rules for creating an explicit commit history. It enables automated tooling (CHANGELOG generation, semantic version bumping) and structured filtering.
|
||||
|
||||
## Message Format
|
||||
|
||||
```text
|
||||
<type>[optional scope]: <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
Each section is separated by a blank line. The header is the only required part.
|
||||
|
||||
## Rules
|
||||
|
||||
| Element | Rule |
|
||||
|---|---|
|
||||
| `type` | Required. Lowercase noun. |
|
||||
| `scope` | Optional. Noun in parentheses directly after type: `feat(api):`. |
|
||||
| `description` | Required. Immediately follows `type/scope: `. Imperative mood, no trailing period. |
|
||||
| `body` | Optional. Begins one blank line after description. Free-form prose, multiple paragraphs allowed. Lines max 100 characters. |
|
||||
| `footer(s)` | Optional. Begins one blank line after body (or description). `<token>: <value>` format. Lines max 100 characters. |
|
||||
| `BREAKING CHANGE` | Must be uppercase. Either a footer token or signalled by `!` before the colon. |
|
||||
|
||||
## Standard Types
|
||||
|
||||
The spec itself mandates only `feat` and `fix`. The 11-type set below is the de-facto standard from `@commitlint/config-conventional` (Angular commit message guidelines), not a spec requirement — but it is what this skill validates against.
|
||||
|
||||
### 11-type set (commitlint/config-conventional)
|
||||
|
||||
| Type | Meaning | SemVer impact | Appears in CHANGELOG |
|
||||
|---|---|---|---|
|
||||
| `feat` | New user-visible feature | MINOR | Yes |
|
||||
| `fix` | Bug fix | PATCH | Yes |
|
||||
| `perf` | Performance improvement, no API change | PATCH | Yes |
|
||||
| `revert` | Reverts a previous commit | PATCH | Yes |
|
||||
| `docs` | Documentation only | none | No |
|
||||
| `style` | Formatting, whitespace — no logic change | none | No |
|
||||
| `refactor` | Code restructuring — no feature or fix | none | No |
|
||||
| `test` | Adding or fixing tests | none | No |
|
||||
| `build` | Build system or external dependency changes | none | No |
|
||||
| `ci` | CI configuration and scripts | none | No |
|
||||
| `chore` | Anything not fitting above | none | No |
|
||||
|
||||
A `BREAKING CHANGE` footer or `!` on **any** type always triggers a MAJOR bump.
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
Two equivalent notations:
|
||||
|
||||
**`!` in header** (preferred — visible in `git log --oneline`):
|
||||
```text
|
||||
feat!: drop support for Node 6
|
||||
feat(api)!: remove deprecated endpoint
|
||||
```
|
||||
|
||||
**`BREAKING CHANGE` footer** (machine-readable body):
|
||||
```text
|
||||
feat: allow config to extend other configs
|
||||
|
||||
BREAKING CHANGE: `extends` key now used for extending config files
|
||||
```
|
||||
|
||||
**Both together** (most explicit):
|
||||
```text
|
||||
feat!: drop support for Node 6
|
||||
|
||||
BREAKING CHANGE: use JavaScript features not available in Node 6.
|
||||
```
|
||||
|
||||
Rules:
|
||||
- `BREAKING CHANGE` must be all caps.
|
||||
- `BREAKING-CHANGE` (hyphenated) is an accepted synonym.
|
||||
- Any type can carry a breaking change, not just `feat`.
|
||||
- The footer value must describe what broke.
|
||||
|
||||
## Footer Token Rules
|
||||
|
||||
```text
|
||||
<token>: <value>
|
||||
<token> #<value> # for issue references
|
||||
```
|
||||
|
||||
- Tokens use hyphens for word separation: `Reviewed-by`, `Co-authored-by`, `Refs`.
|
||||
- Exception: `BREAKING CHANGE` (space allowed, uppercase).
|
||||
- Multiple footers allowed, one per line.
|
||||
- Blank line required before the footer block.
|
||||
|
||||
Valid footer examples:
|
||||
```text
|
||||
Reviewed-by: Z
|
||||
Refs: #123
|
||||
Co-authored-by: Alice <alice@example.com>
|
||||
BREAKING CHANGE: the `--format` flag now requires a value
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
Minimal — no body, no footer:
|
||||
```text
|
||||
docs: correct spelling of CHANGELOG
|
||||
```
|
||||
|
||||
With scope:
|
||||
```text
|
||||
feat(lang): add Polish language
|
||||
```
|
||||
|
||||
Breaking change via `!`:
|
||||
```text
|
||||
feat!: send an email to the customer when a product is shipped
|
||||
```
|
||||
|
||||
Breaking change via footer:
|
||||
```text
|
||||
feat: allow provided config object to extend other configs
|
||||
|
||||
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
|
||||
```
|
||||
|
||||
Multi-paragraph body with multiple footers:
|
||||
```text
|
||||
fix: prevent racing of requests
|
||||
|
||||
Introduce a request id and a reference to latest request. Dismiss
|
||||
incoming responses other than from latest request.
|
||||
|
||||
Remove timeouts which were used to mitigate the racing issue but are
|
||||
obsolete now.
|
||||
|
||||
Reviewed-by: Z
|
||||
Refs: #123
|
||||
```
|
||||
|
||||
Revert:
|
||||
```text
|
||||
revert: let us never again speak of the noodle incident
|
||||
|
||||
Refs: 676104e, a215868
|
||||
```
|
||||
|
||||
## commitlint Constraints (config-conventional)
|
||||
|
||||
| Constraint | Value |
|
||||
|---|---|
|
||||
| Header max length | 100 characters |
|
||||
| Subject must not end with `.` | enforced |
|
||||
| Subject must be lowercase (not sentence-case or UPPER-CASE) | enforced |
|
||||
| Body / footer line max length | 100 characters |
|
||||
| Type must be one of the 11 standard types | error if not |
|
||||
| Blank line before body | warning |
|
||||
| Blank line before footer | warning |
|
||||
|
||||
## SemVer Mapping Summary
|
||||
|
||||
| Condition | SemVer bump |
|
||||
|---|---|
|
||||
| `fix`, `perf`, `revert` | PATCH |
|
||||
| `feat` | MINOR |
|
||||
| Any type with `BREAKING CHANGE` or `!` | MAJOR |
|
||||
| All other types (`docs`, `style`, `refactor`, `test`, `build`, `ci`, `chore`) | none |
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- conventional-commits-spec
|
||||
- commitlint-config-conventional
|
||||
- org-commit-conventions
|
||||
---
|
||||
|
||||
# Creating a new commit
|
||||
|
||||
1. **Gather context** — what changed and why, from the staged diff, the PR description, or the issue. Confirm the staged diff is one logical, independently reviewable and reversible change that leaves the repository buildable and testable. If it bundles unrelated work, suggest splitting it before going further.
|
||||
2. **Determine the type** — read it off the change itself: a new user-visible feature is `feat`, a bug fix is `fix`. For the full 11-type set and each type's SemVer impact, read `references/conventional-commits-spec.md`.
|
||||
3. **Determine the scope** — use the scope from plugin config where one is set, otherwise infer it from the files changed (`api`, `db`, `cli`, `config`). Scope is optional, but it identifies which part of the system moved and is worth setting.
|
||||
4. **Write the description** — imperative mood, no trailing period: "add user authentication", "fix race condition in cache". Neither source spec sets a target below the 100-character header maximum, but convention favours roughly 50 characters so `git log --oneline` stays readable.
|
||||
5. **Add a body when the change is non-trivial** — blank line first, wrapped at 100 characters. Explain *why*, not what: the diff already shows what changed, and the message's job is the context the diff cannot carry — motivation, root cause, tradeoffs. Follow the Why / Implementation Notes / Impact structure in `references/commit-template.md`.
|
||||
6. **Add footers where they apply** — `Fixes: #123`, `Refs: #123`, `ADR: 0012`, `Co-authored-by: Name <email>`, `BREAKING CHANGE: description`. For the full trailer list, read `references/commit-template.md`.
|
||||
7. **Signal a breaking change with `!` before the colon** — `feat!: drop Node 6` is visible in `git log --oneline`, where the `BREAKING CHANGE:` footer alone is machine-readable but hidden. Use both when the break needs describing.
|
||||
8. **Validate, confirm, execute** — check header length, type, lowercase subject and trailing period against commitlint, show the message, and commit only once the caller has approved. Never add `--no-verify`.
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- org-commit-conventions
|
||||
- context7-git-htmldocs
|
||||
---
|
||||
|
||||
# Rewriting existing commits
|
||||
|
||||
Every flow here rewrites history. None runs without explicit approval, and none ends in a force-push to `main`/`master` — refuse that and explain why.
|
||||
|
||||
## Amend the last commit
|
||||
|
||||
1. Stage the new changes, or the changes that undo something.
|
||||
2. Run `rtk git commit --amend`, adding `--no-edit` when the message stays as it is.
|
||||
3. If the message should change, show the current one and prompt for the replacement.
|
||||
4. The branch has diverged from its remote. Amending is safe only where nobody else has based work on it; on `main`/`master`, refuse the force-push and explain rather than warn and proceed.
|
||||
|
||||
## Fold a commit into an earlier one (autosquash — preferred)
|
||||
|
||||
Prefer this whenever a commit is written to be folded, because git does the marking:
|
||||
|
||||
1. `rtk git commit --fixup=<commit>` keeps the target's message; `rtk git commit --squash=<commit>` lets you edit the combined message later. Both prefix the message with `fixup!`/`squash!` and name the target commit.
|
||||
2. Get explicit approval — the rebase still rewrites history.
|
||||
3. Run `git rebase -i --autosquash HEAD~N` — bare, not `rtk`: `-i` opens an interactive sequence editor. Git pre-fills the todo list with the tagged commits already reordered against their targets; save it unchanged to apply.
|
||||
|
||||
**`-i` is not optional here.** On Git 2.39.5, `git rebase --autosquash HEAD~N` without `-i` prints `Successfully rebased and updated refs/heads/<branch>.` and exits 0 while leaving the `fixup!` commit in place at its original SHA — `--autosquash` is honoured only by the interactive machinery, and the false success is the trap: the fold is reported as done, and the surviving `fixup!` subject then fails the Conventional Commits `commit-msg` hook. Later Git versions taught the non-interactive rebase to honour the flag, but `-i --autosquash` is correct on every version, so always write that.
|
||||
|
||||
## Squash by hand (interactive rebase)
|
||||
|
||||
Use this when the commits were not tagged at commit time. **Interactive rebase has no undo once `rebase -i` starts — `git reflog` is the recovery path.**
|
||||
|
||||
1. Identify the commits to squash — typically the last N on the current branch.
|
||||
2. Get explicit approval.
|
||||
3. Run `git rebase -i HEAD~N` — bare, not `rtk`, for the same interactive-editor reason — marking the older commits `squash` to keep their messages for editing, or `fixup` to discard them.
|
||||
4. Compose the combined message when the rebase stops to ask. For a non-trivial combined message, follow the structure in `references/commit-template.md`.
|
||||
|
||||
## When a rebase halts on a conflict
|
||||
|
||||
Offer conflict resolution or `rtk git rebase --abort`. Do not resolve conflicts automatically without confirmation.
|
||||
|
||||
## Rebase the branch onto a new base
|
||||
|
||||
Replays this branch's commits on top of another branch's tip — bringing a feature branch up to
|
||||
date without a merge commit.
|
||||
|
||||
1. Confirm nothing being replayed has been pushed anywhere someone else has based work on. A rebase
|
||||
gives every replayed commit a new SHA, which breaks any clone that already has the old ones.
|
||||
2. Get explicit approval — this rewrites history like every other flow on this page.
|
||||
3. `rtk git fetch origin` first, so `<newbase>` is the real tip rather than a stale local copy.
|
||||
4. `rtk git rebase <newbase>` — for example `rtk git rebase main`. Use
|
||||
`rtk git rebase --onto <newbase> <upstream> <branch>` to replay only the commits after
|
||||
`<upstream>`, which is how a branch started from the wrong base gets moved.
|
||||
5. The branch has diverged from its remote. Push needs `--force-with-lease --force-if-includes`,
|
||||
never a bare `--force` — and never on `main`/`master`; refuse that and explain.
|
||||
|
||||
## Move the branch pointer back (`git reset`)
|
||||
|
||||
`reset` moves the current branch to another commit. The mode decides what survives:
|
||||
|
||||
| Mode | Branch pointer | Index | Working tree |
|
||||
|---|---|---|---|
|
||||
| `--soft` | moves | untouched — the changes stay staged | untouched |
|
||||
| `--mixed` (default) | moves | reset — the changes become unstaged | untouched |
|
||||
| `--hard` | moves | reset | **overwritten; uncommitted work is destroyed** |
|
||||
|
||||
- "Undo my last commit but keep the changes" is `rtk git reset --soft HEAD~1`. That is the default
|
||||
answer to the request; reach for anything else only when the caller asked for it.
|
||||
- `rtk git reset --mixed HEAD~1` when the staging should be redone from scratch too.
|
||||
- `rtk git reset --hard <ref>` is gated like a force-push: state exactly which uncommitted changes
|
||||
will be discarded, get approval for that specific reset, and offer `rtk git stash push -u` first.
|
||||
The commits it drops stay reachable through `git reflog`; the uncommitted edits never entered git
|
||||
at all and nothing recovers them.
|
||||
|
||||
Reset does not rewrite the commits it leaves behind, so no force-push is needed unless the branch
|
||||
was already pushed at the newer commit.
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
topic: commits
|
||||
source_keys:
|
||||
- conventional-commits-spec
|
||||
- commitlint-config-conventional
|
||||
- org-commit-conventions
|
||||
- context7-git-htmldocs
|
||||
---
|
||||
|
||||
# Research Sources for git-commits Skill
|
||||
|
||||
Sources extracted from the git plugin research phase. Only sources that directly informed this skill are listed; sibling skills (git-branches, git-history, git-remotes, etc.) have their own sources.md.
|
||||
|
||||
## conventional-commits-spec
|
||||
|
||||
- **Description:** Conventional Commits Specification (v1.0.0) — message format, types, breaking changes, footer rules
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/commits.md § "Conventional Commits Specification (v1.0.0)"
|
||||
- **Contributing files:** SKILL.md, references/conventional-commits-spec.md, references/create-commit.md
|
||||
- **Status:** extracted
|
||||
|
||||
## commitlint-config-conventional
|
||||
|
||||
- **Description:** commitlint config-conventional preset — validation constraints (max 100 chars header, no trailing periods, lowercase type, 11-type set enforcement)
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/commits.md § "commitlint Constraints (`config-conventional`)"
|
||||
- **Contributing files:** SKILL.md, references/conventional-commits-spec.md, references/create-commit.md
|
||||
- **Status:** extracted
|
||||
|
||||
## org-commit-conventions
|
||||
|
||||
- **Description:** Organization commit message body template and git conventions (atomic commits, no `--no-verify`, no force-push main/master, `rtk git` wrapper) — content fully embedded in this skill; the org's `core/instructions/git.md` and `core/instructions/commits.md` are provenance only and are not a live dependency
|
||||
- **Research doc:** core/instructions/commits.md, core/instructions/git.md (org convention, not part of the plugin's research corpus)
|
||||
- **Contributing files:** SKILL.md, references/commit-template.md, references/create-commit.md, references/rewrite-history.md
|
||||
- **Status:** extracted
|
||||
|
||||
## context7-git-htmldocs
|
||||
|
||||
- **Description:** Official Git HTML documentation — `git commit --squash`/`--fixup`, `git rebase --autosquash`, and `git cherry-pick` range and abort semantics
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/cli-reference.md § "Committing", § "Rebasing", § "Cherry-picking"
|
||||
- **Contributing files:** SKILL.md, references/rewrite-history.md, references/cherry-pick.md
|
||||
- **Status:** extracted
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
name: git-history
|
||||
|
||||
description: >
|
||||
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`.
|
||||
|
||||
metadata:
|
||||
version: "1.0.2"
|
||||
category: git
|
||||
source_keys:
|
||||
- git-scm-bisect-docs
|
||||
- git-scm-log-docs
|
||||
- git-scm-diff-docs
|
||||
|
||||
allowed-tools: 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:
|
||||
|
||||
```text
|
||||
<sha> — <subject>
|
||||
<author> (<relative date>)
|
||||
Recommendation: <action or "none">
|
||||
```
|
||||
@@ -1,68 +0,0 @@
|
||||
---
|
||||
topic: bisect
|
||||
source_keys:
|
||||
- git-scm-bisect-docs
|
||||
---
|
||||
|
||||
# Finding a commit with `git bisect`
|
||||
|
||||
Read this when the question is *which commit changed the behaviour* and there is no string, file,
|
||||
or line range to search the log for. Binary search reduces the trials from O(N) to O(log N).
|
||||
|
||||
## Manual flow
|
||||
|
||||
```bash
|
||||
rtk git bisect start
|
||||
rtk git bisect bad [HEAD] # mark current (or specified) as broken
|
||||
rtk git bisect good <commit> # mark known-good baseline
|
||||
# Git checks out the midpoint; test it
|
||||
rtk git bisect good # test passes
|
||||
rtk git bisect bad # test fails
|
||||
# Repeat until git reports "X is the first bad commit"
|
||||
rtk git bisect reset # return to the original HEAD
|
||||
```
|
||||
|
||||
## Automated
|
||||
|
||||
With a test command available, use `rtk git bisect run <cmd>`. Git reads the exit code: `0` good,
|
||||
`1`–`124` bad, `125` skip (build broken), `126`–`127` POSIX shell errors, treated as bad, and
|
||||
`128` or above aborts the session outright rather than marking the commit bad.
|
||||
|
||||
## Untestable commits
|
||||
|
||||
`rtk git bisect skip` excludes a commit that cannot be built or tested without deciding good or bad
|
||||
for it. When the first bad commit is adjacent to a skipped range, bisect reports that it cannot
|
||||
pinpoint the culprit and lists the candidates — that is the precise answer the skip range allows,
|
||||
not a failure.
|
||||
|
||||
## Undoing a wrong good/bad call
|
||||
|
||||
`rtk git bisect log` prints the session's decision history. Save it, edit out the mistaken entry, and
|
||||
resume from the corrected log rather than restarting the search:
|
||||
|
||||
```bash
|
||||
rtk git bisect log > bisect.log
|
||||
# edit bisect.log, removing the wrong decision
|
||||
rtk git bisect reset && rtk git bisect replay bisect.log
|
||||
```
|
||||
|
||||
## Narrowing and speeding up
|
||||
|
||||
- `rtk git bisect start HEAD v1.2 -- src/` restricts bisection to a path, cutting the trial count.
|
||||
- `--no-checkout` updates the `BISECT_HEAD` ref instead of checking out a working tree — useful
|
||||
for tests that do not need one, and 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 the remaining candidates
|
||||
|
||||
`rtk git bisect visualize` (alias `view`) opens the suspects in gitk, falling back to `git log` when
|
||||
no graphical display is detected. Add `--stat` or `-p` for a diffstat or full patches.
|
||||
|
||||
## Hunting a non-bug property change
|
||||
|
||||
`rtk git bisect start --term-new <new> --term-old <old>` searches for any property change — a
|
||||
performance regression, say — instead of a bug. Use the custom terms in place of `good` and `bad`
|
||||
for the rest of the session.
|
||||
|
||||
Once the first bad commit is identified, return to Step 3 to act on it and Step 4 to report it.
|
||||
@@ -1,242 +0,0 @@
|
||||
---
|
||||
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:**
|
||||
```text
|
||||
%(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
|
||||
rtk git log -S"my_function"
|
||||
rtk git log -S"my_function" --pickaxe-regex # treat as POSIX ERE
|
||||
rtk 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
|
||||
rtk 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
|
||||
rtk git log --diff-filter=ad # exclude added and deleted files
|
||||
rtk 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`.
|
||||
|
||||
Bare `git`, not `rtk git`, on every `-L` form below: rtk truncates each diff body
|
||||
line at roughly 72 characters with an ellipsis, on the one query whose whole point
|
||||
is showing line content.
|
||||
|
||||
```bash
|
||||
git log -L 10,20:file.txt # bare (ADR-0023)
|
||||
git log -L /start_pattern/,/end_pattern/:file.txt # bare (ADR-0023)
|
||||
git log -L :myfunction:src/app.c # bare (ADR-0023)
|
||||
git log -L /init/,+15:config.py # bare (ADR-0023); 15 lines after first /init/ match
|
||||
```
|
||||
|
||||
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
|
||||
rtk git log --first-parent # at merges, follow only first parent (mainline evolution)
|
||||
rtk git log --merges # only merge commits (≥2 parents); equivalent to --min-parents=2
|
||||
rtk git log --no-merges # only non-merge commits; equivalent to --max-parents=1
|
||||
rtk git log --ancestry-path D..M # only commits actually on the path from D to M
|
||||
rtk git log --min-parents=<n> # include only commits with ≥ n parents
|
||||
rtk 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
|
||||
rtk git diff --stat # diffstat: file names + ± bar
|
||||
rtk git diff --stat=<width>,<name-width>,<count>
|
||||
rtk git diff --compact-summary # alongside --stat: shows new/gone, +x/-x (executable), +l (symlink)
|
||||
rtk git diff --numstat # machine-readable: <added>\t<deleted>\t<path>; - for binary
|
||||
```
|
||||
|
||||
### --name-only / --name-status
|
||||
|
||||
Bare `git`, not `rtk git`: rtk appends a blank line and a `Changes:` trailer, so
|
||||
the output is no longer one record per line.
|
||||
|
||||
```bash
|
||||
git diff --name-only # bare (ADR-0023); only filenames, one per line
|
||||
git diff --name-status # bare (ADR-0023); status letter + filename per line
|
||||
```
|
||||
|
||||
`--name-status` uses the same status letters as `--diff-filter`.
|
||||
|
||||
### --word-diff
|
||||
|
||||
Bare `git`, not `rtk git`: rtk replaces the word-diff with its own diffstat
|
||||
renderer and emits none of the `[-removed-] {+added+}` markers.
|
||||
|
||||
```bash
|
||||
git diff --word-diff # bare (ADR-0023); inline word-level diff, [-removed-] {+added+} markers
|
||||
git diff --word-diff=color # bare (ADR-0023); color only, no markers
|
||||
git diff --word-diff=porcelain # bare (ADR-0023); machine-readable: +/- prefixed lines, ~ for newlines
|
||||
git diff --word-diff-regex=<re> # bare (ADR-0023); 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 |
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
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, references/bisect.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:** SKILL.md, references/git-log-format.md
|
||||
@@ -1,60 +0,0 @@
|
||||
---
|
||||
name: git-remotes
|
||||
|
||||
description: >
|
||||
Use when a git operation — remote config, fetch, push, or pull — touches a
|
||||
remote, even when the user does not name it.
|
||||
Not local commits -> `git-commits`.
|
||||
Not local branches -> `git-branches`.
|
||||
Not log or bisect queries -> `git-history`.
|
||||
Not submodule pointers -> `git-submodules`.
|
||||
|
||||
metadata:
|
||||
version: "1.0.3"
|
||||
category: git
|
||||
source_keys:
|
||||
- git-scm-remote-docs
|
||||
- git-scm-fetch-docs
|
||||
- git-scm-push-docs
|
||||
- git-scm-pull-docs
|
||||
- context7-git-htmldocs
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **`--force-with-lease` alone is not safe** — background processes (IDE plugins, cron jobs) running `git fetch` silently defeat the protection. Combine it with `--force-if-includes`, or pin the explicit `--force-with-lease=<ref>:<sha>` form.
|
||||
- **Prune does not touch tags by default** — `git fetch --prune` leaves orphaned tags behind. Use `--prune --prune-tags`, or set `fetch.pruneTags true`.
|
||||
- **Set `pull.ff only` explicitly** — do not trust the installed default.
|
||||
|
||||
## Step 1 — Clear the force-push gate
|
||||
|
||||
`main`/`master` are a hard refusal: decline a force-push to either regardless of confirmation — no local approval restores what the remote loses. Elsewhere, `rtk git push --force`/`-f` run only after `confirm: true` for that specific push; for a human caller, prompt instead of failing.
|
||||
|
||||
## Step 2 — Dispatch
|
||||
|
||||
Read the row matching the operation, and only that row — each file is self-contained. A task spanning two operations reads both.
|
||||
|
||||
| Operation | Read |
|
||||
|---|---|
|
||||
| Add, remove, rename, inspect, or re-point a remote; tracking, mirror, and `set-url` config | `references/remote-config.md` |
|
||||
| Fetch or prune remote-tracking refs; shallow or partial fetch | `references/fetch.md` |
|
||||
| Push branches or tags; refspecs; force-push | `references/push.md` |
|
||||
| Pull — integrate remote changes into the current branch | `references/pull.md` |
|
||||
|
||||
## Step 3 — Return format
|
||||
|
||||
For agent callers, return:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"operation": "push",
|
||||
"remote": "origin",
|
||||
"branch": "main",
|
||||
"output": "...",
|
||||
"warnings": ["force-with-lease not confirmed"],
|
||||
"recommendations": ["set `pull.ff only` so the default does not vary by Git version"]
|
||||
}
|
||||
```
|
||||
|
||||
On failure, set `success: false` and add an `error` field holding the root cause and a recovery suggestion.
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
topic: fetch
|
||||
source_keys:
|
||||
- git-scm-fetch-docs
|
||||
- context7-git-htmldocs
|
||||
---
|
||||
|
||||
# Fetching
|
||||
|
||||
Fetch **with no refspec** updates remote-tracking branches (`refs/remotes/<name>/*`) and leaves every local branch alone.
|
||||
|
||||
That safety comes from the default refspec, not from `fetch` itself. Give it an explicit one and it writes to local branches: verified on Git 2.39.5, `git fetch origin main:probe` fast-forwarded the local `probe` branch, and a `+` prefix force-updates the destination, discarding whatever commits it held. Treat any `fetch` carrying a `<src>:<dst>` refspec as a branch update, not a read.
|
||||
|
||||
- **One remote**: `rtk git fetch <remote>` — all branches
|
||||
- **One branch**: `rtk git fetch <remote> <branch>` — the result lands in `FETCH_HEAD`, not a tracking ref
|
||||
- **All remotes**: `rtk git fetch --all`
|
||||
- **Prune properly**: `rtk git fetch --all --prune --prune-tags` cleans stale branches *and* tags
|
||||
- **Auto-prune**: `rtk git config --global fetch.prune true` (or `remote.<name>.prune` to scope it to one remote), and `fetch.pruneTags true` for tags
|
||||
|
||||
## Shallow and partial fetch
|
||||
|
||||
```bash
|
||||
rtk git fetch --depth=<n> # deepen history, or create a shallow clone
|
||||
rtk git fetch --unshallow # convert a shallow clone to full history
|
||||
rtk git fetch --update-shallow # allow the fetch to update the shallow boundary
|
||||
rtk git fetch --refmap='' <remote> <branch> # fetch without updating any tracking ref (FETCH_HEAD only)
|
||||
```
|
||||
|
||||
## Default fetch refspec
|
||||
|
||||
The default is `+refs/heads/*:refs/remotes/<name>/*`. The leading `+` forces the update — remote-tracking branches always mirror the remote exactly and offer no protection for local history.
|
||||
@@ -1,43 +0,0 @@
|
||||
---
|
||||
topic: pull
|
||||
source_keys:
|
||||
- git-scm-pull-docs
|
||||
- context7-git-htmldocs
|
||||
---
|
||||
|
||||
# Pulling
|
||||
|
||||
Default strategy: `--ff-only`. It fails on divergence, which forces a conscious choice instead of an accidental merge commit.
|
||||
|
||||
- **Fast-forward only**: `rtk git pull --ff-only` — the recommended default
|
||||
- **Rebase**: `rtk git pull --rebase` replays your commits on top for linear history, but rewrites SHAs. Verify nothing being replayed has been pushed: rebasing published commits breaks everyone downstream.
|
||||
- **Merge**: `rtk git pull --no-rebase` — three-way merge commit, preserves original commits, non-linear
|
||||
- **Rebase preserving merges**: `rtk git pull --rebase=merges` keeps intentional local merge commits during the replay
|
||||
- **Stage without committing**: `rtk git pull --squash` collapses incoming commits into staged changes; you write the message
|
||||
- **Merge strategy**: Git 2.34+ defaults to `ort` (`recursive` is now an alias for it). Strategy options such as `-X ours`, `-X theirs`, `-X ignore-space-change` pass through unchanged.
|
||||
- **Submodules**: `--recurse-submodules` only fetches submodules already checked out. Newly added ones are not initialized — use the `git-submodules` skill for those.
|
||||
|
||||
## On divergence
|
||||
|
||||
A pull that diverges with no strategy configured fails, and that failure is the useful outcome. Report the divergence and the three ways out — `--ff-only`, `--rebase`, `--no-rebase` — and let the caller choose. Auto-merging a diverged branch buries a decision that belongs to the human.
|
||||
|
||||
## Config precedence
|
||||
|
||||
`--ff-only` is not Git's default on an unset config, and never has been. Older versions silently
|
||||
merged on divergence; current ones refuse outright — verified on Git 2.39.5, a divergent pull with
|
||||
nothing configured prints the reconciliation hint and exits 128 with
|
||||
`fatal: Need to specify how to reconcile divergent branches.` The behaviour therefore still varies
|
||||
by installed version, and neither variant is the one you want. Set it explicitly.
|
||||
|
||||
Highest wins:
|
||||
|
||||
1. Command-line flag (`--ff-only` / `--rebase` / `--no-rebase`)
|
||||
2. `pull.rebase` config (global or local)
|
||||
3. `branch.<name>.rebase` (branch-specific override)
|
||||
4. `branch.autoSetupRebase` (set automatically when the tracking branch was created)
|
||||
|
||||
```bash
|
||||
rtk git config pull.ff only # deterministic default across Git versions
|
||||
rtk git config --global pull.rebase true
|
||||
rtk git config branch.develop.rebase false # develop always merges, regardless of the global default
|
||||
```
|
||||
@@ -1,69 +0,0 @@
|
||||
---
|
||||
topic: push
|
||||
source_keys:
|
||||
- git-scm-push-docs
|
||||
- context7-git-htmldocs
|
||||
---
|
||||
|
||||
# Pushing
|
||||
|
||||
Default: safe push to the same-named branch on the remote.
|
||||
|
||||
- **Force-push**: never bare `--force`. Use `rtk git push --force-with-lease --force-if-includes <remote> <branch>`, after the SKILL.md Step 1 gate.
|
||||
- **Basic**: `rtk git push <remote> <branch>`
|
||||
- **Set upstream**: `rtk git push -u <remote> <branch>` — push and configure tracking
|
||||
- **Multi-remote**: push sequentially (`rtk git push origin develop`, `rtk git push staging develop`), or add a second push URL with `rtk git remote set-url --add <name> <url>` to reach both in one command
|
||||
- **Delete a remote branch**: `rtk git push <remote> --delete <branch>` — clearer than the `:<branch>` form
|
||||
- **Bulk**: `rtk git push --all` (all local branches), `rtk git push --tags` (all tags), `rtk git push origin <tag>` (one tag)
|
||||
- **Delete remote branches with no local counterpart**: `rtk git push --prune origin 'refs/heads/*:refs/heads/*'`
|
||||
- **Force only part of a multi-ref push**: prefix the one refspec that needs it with `+` — `rtk git push origin +release develop` forces `release` while safe-pushing `develop`. A `+` prefix is a force-push and passes the SKILL.md Step 1 gate like any other.
|
||||
|
||||
## Refspec syntax — `[+]<src>[:<dst>]`
|
||||
|
||||
| Pattern | Meaning |
|
||||
|---|---|
|
||||
| `<branch>` | Push to same-named remote branch |
|
||||
| `<src>:<dst>` | Push `<src>` local ref to `<dst>` remote ref |
|
||||
| `+<src>:<dst>` | Force this refspec (non-fast-forward allowed) — a force-push; passes the SKILL.md Step 1 gate |
|
||||
| `:<branch>` | Delete remote `<branch>` |
|
||||
| `refs/heads/*:refs/heads/*` | Glob: push all matching branches |
|
||||
| `^refs/heads/dev-*` | Negative: exclude matching refs |
|
||||
| `tag <name>` | Sugar for `refs/tags/<name>:refs/tags/<name>` |
|
||||
|
||||
## Force-push safety — full detail
|
||||
|
||||
`--force-with-lease` rejects the push if the remote ref moved since your last fetch. Three forms:
|
||||
|
||||
| Form | What it protects |
|
||||
|---|---|
|
||||
| `--force-with-lease` (bare) | All refs being pushed, checked against your remote-tracking branch |
|
||||
| `--force-with-lease=<refname>` | Named ref only |
|
||||
| `--force-with-lease=<refname>:<sha>` | Named ref must be at exact SHA — most stable |
|
||||
|
||||
**Caveat with the bare form:** any background process that runs `git fetch` (IDE plugin, cron job, editor auto-fetch) updates your remote-tracking branch, which can make the lease check pass even though someone else pushed in between. The protection is silently defeated.
|
||||
|
||||
Two mitigations:
|
||||
|
||||
```bash
|
||||
# Option 1 — dedicated push-only remote: background tools fetch `origin`, you push
|
||||
# through a separate remote that nothing else touches, so its tracking ref can't be
|
||||
# poisoned by an unrelated fetch.
|
||||
# The inner `git config` is bare: its stdout becomes a remote URL, so any
|
||||
# output rewriting would poison the remote silently.
|
||||
rtk git remote add origin-push $(git config remote.origin.url) # inner bare (ADR-0023)
|
||||
rtk git push --force-with-lease origin-push
|
||||
|
||||
# Option 2 — explicit SHA via a local tag, unaffected by tracking-branch state
|
||||
rtk git fetch
|
||||
rtk git tag base master
|
||||
git rebase -i master # bare, not `rtk` (ADR-0023): interactive sequence editor
|
||||
rtk git push --force-with-lease=master:base master:master
|
||||
```
|
||||
|
||||
`--force-if-includes` adds a second check on top of bare `--force-with-lease`: it verifies the remote-tracking tip actually appears in your local branch's reflog, i.e. you genuinely integrated it before rewriting. It is a no-op without `--force-with-lease`, and has no effect with the `--force-with-lease=<ref>:<sha>` form, which already pins an exact SHA.
|
||||
|
||||
Safest combination: `rtk git push --force-with-lease --force-if-includes origin`.
|
||||
|
||||
## Server-side policy
|
||||
|
||||
`receive.denyDeletes`, `receive.denyDeleteCurrent` and `receive.denyNonFastForwards` are enforced on the remote regardless of any local flag — a hardened server rejects the push even with `--force`.
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
topic: remote-config
|
||||
source_keys:
|
||||
- git-scm-remote-docs
|
||||
- context7-git-htmldocs
|
||||
---
|
||||
|
||||
# Remote configuration
|
||||
|
||||
Which remotes exist, where they point, and what they track.
|
||||
|
||||
`rtk git remote show <name>` needs network access — use `-n` for cached data offline, or `rtk git remote -v`, which lists URLs without querying.
|
||||
|
||||
## Add, remove, rename, inspect
|
||||
|
||||
- **Add**: `rtk git remote add <name> <url>`, or `-f` to fetch immediately
|
||||
- **Remove**: `rtk git remote remove <name>` — deletes the remote, all its tracking refs, and its config
|
||||
- **Rename**: `rtk git remote rename <old> <new>`
|
||||
- **Inspect**: `rtk git remote -v` (URLs, offline) or `rtk git remote show <name>` (live tracking status)
|
||||
- **Effective URLs**: `rtk git remote get-url <name>` shows the URL after `insteadOf` rewrites; `rtk git remote get-url --push --all <name>` lists every push URL
|
||||
|
||||
## Tracking, mirroring, housekeeping
|
||||
|
||||
- **Track one branch**: `rtk git remote add -t <branch> <name> <url>` (repeatable); `--no-tags` suppresses tag import entirely
|
||||
- **Mirror**: `--mirror=fetch` mirrors all refs locally (bare repos only); `--mirror=push` makes every push behave like `--mirror`
|
||||
- **Prune stale tracking refs without fetching**: `rtk git remote prune <name>`, with `--dry-run` to preview
|
||||
- **Default branch pointer**: `rtk git remote set-head <name> -a` (auto-detect, needs a prior fetch), `... <branch>` (explicit), `... -d` (delete `refs/remotes/<name>/HEAD`)
|
||||
|
||||
## `set-url` — full form
|
||||
|
||||
```bash
|
||||
rtk git remote set-url <name> <newurl> # replace the first fetch URL
|
||||
rtk git remote set-url <name> <newurl> <oldurl-regex> # replace only the URL matching regex
|
||||
rtk git remote set-url --push <name> <url> # change push URL only (must point at same repo)
|
||||
rtk git remote set-url --add <name> <url> # add an extra push URL (push to multiple remotes)
|
||||
rtk git remote set-url --delete <name> <regex> # remove URLs matching regex
|
||||
```
|
||||
|
||||
`--push` changes only where pushes go — fetch and push URLs must still reference the same repository. For genuine fetch-from-A / push-to-B workflows, use two separate named remotes instead; `--push` cannot do this.
|
||||
@@ -1,74 +0,0 @@
|
||||
---
|
||||
# Research sources referenced by this skill
|
||||
# Each entry documents where the skill's guidance came from.
|
||||
---
|
||||
|
||||
## git-scm-remote-docs
|
||||
|
||||
**Description:** Git SCM official documentation for `git remote` command — remote configuration, add/remove/rename, URL management, inspection, and housekeeping.
|
||||
|
||||
**Source:** https://git-scm.com/docs/git-remote
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md → `## Remote Management (`git remote`)`
|
||||
|
||||
**Contributing files:**
|
||||
- references/remote-config.md
|
||||
|
||||
---
|
||||
|
||||
## git-scm-fetch-docs
|
||||
|
||||
**Description:** Git SCM official documentation for `git fetch` command — fetching from remotes, tracking branch updates, pruning stale refs, shallow clones, and refspecs.
|
||||
|
||||
**Source:** https://git-scm.com/docs/git-fetch
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md → `## Fetching (`git fetch`)`
|
||||
|
||||
**Contributing files:**
|
||||
- SKILL.md (Gotchas — prune does not touch tags)
|
||||
- references/fetch.md
|
||||
|
||||
---
|
||||
|
||||
## git-scm-push-docs
|
||||
|
||||
**Description:** Git SCM official documentation for `git push` command — pushing branches, tags, force-push safety (--force-with-lease, --force-if-includes), refspecs, and multi-remote workflows.
|
||||
|
||||
**Source:** https://git-scm.com/docs/git-push
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md → `## Pushing (`git push`)`
|
||||
|
||||
**Contributing files:**
|
||||
- SKILL.md (Gotchas — `--force-with-lease` caveat; Step 1 force-push gate)
|
||||
- references/push.md
|
||||
|
||||
---
|
||||
|
||||
## git-scm-pull-docs
|
||||
|
||||
**Description:** Git SCM official documentation for `git pull` command — fetch + merge/rebase strategies, divergence resolution (--ff-only, --rebase, merge), config precedence, and pull-specific gotchas.
|
||||
|
||||
**Source:** https://git-scm.com/docs/git-pull
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md → `## Pulling (`git pull`)`
|
||||
|
||||
**Contributing files:**
|
||||
- SKILL.md (Gotchas — pull default drift)
|
||||
- references/pull.md (divergence rule; strategies; config precedence)
|
||||
|
||||
---
|
||||
|
||||
## context7-git-htmldocs
|
||||
|
||||
**Description:** Context7 MCP library providing current Git documentation and API reference — used for validation of modern Git syntax, behavior, and config semantics. This is a blanket cross-cutting reference and does not map to a single heading in the research doc; it informed terminology and syntax checks across all sections.
|
||||
|
||||
**Source:** Context7 MCP / Git library
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/remotes.md (cross-cutting — no dedicated section)
|
||||
|
||||
**Contributing files:**
|
||||
- SKILL.md (all sections)
|
||||
- references/remote-config.md
|
||||
- references/fetch.md
|
||||
- references/push.md
|
||||
- references/pull.md
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
name: git-submodules
|
||||
|
||||
description: >
|
||||
Use when managing Git submodules — the full lifecycle of a nested
|
||||
repository inside a superproject — including phrasings that never say the
|
||||
word, such as "add a dependency repo" or "vendor this repo inside ours".
|
||||
Not multiple checkouts of one repo -> `git-worktrees`.
|
||||
Not the superproject's own remotes -> `git-remotes`.
|
||||
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
category: git
|
||||
source_keys:
|
||||
- git-scm-submodule-docs
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **`update` leaves the submodule in detached HEAD.** Branch inside the submodule before editing, or the work is unreachable once the pointer moves.
|
||||
- **Push the submodule before the superproject.** The superproject stores only a SHA, and one missing from the submodule's remote breaks every collaborator's `update`.
|
||||
- **`--recursive` is never the default.** Subcommands stop one level deep, so nested submodules go stale silently.
|
||||
- **`git rm` leaves `.git/modules/<name>/` behind.** Nothing cleans it up, and it blocks re-adding a submodule there.
|
||||
|
||||
## Working rules
|
||||
|
||||
Run `rtk git` from the superproject root. Enter the submodule directory only for commits and pushes
|
||||
that belong to the submodule's own history — the two repositories have independent histories, and
|
||||
the same command from the wrong directory writes to the wrong one.
|
||||
|
||||
Before committing a superproject pointer, run `rtk git submodule status --recursive`. Prefixes: `-`
|
||||
not initialized, `+` working tree differs from the recorded commit, `U` merge conflict. Add
|
||||
`--cached` to read the SHAs the superproject index will record rather than the working-tree state.
|
||||
A `-dirty` suffix means uncommitted changes inside the submodule, and committing the pointer over
|
||||
them pins a state nobody else can reproduce.
|
||||
|
||||
To run one command across every submodule: `rtk git submodule foreach --recursive '<cmd>'`. Inside
|
||||
`<cmd>`, Git sets `$name`, `$sm_path`, `$displaypath`, `$sha1` and `$toplevel`; append `|| :` to
|
||||
continue past a failure instead of aborting the traversal. `$sm_path` and `$displaypath` name the
|
||||
same directory from different vantage points — if which one you want is not obvious, read the
|
||||
variable table in `references/setup-and-update.md` before writing the command.
|
||||
|
||||
## Dispatch
|
||||
|
||||
Read only the row that matches the request.
|
||||
|
||||
| Task | Reference |
|
||||
|---|---|
|
||||
| Clone a superproject with submodules; add, initialize, update or re-pin one; run a command across all of them with `foreach` | `references/setup-and-update.md` |
|
||||
| Change where a submodule points — `sync`, `set-url`, `set-branch`, a local mirror override, `absorbgitdirs`, or any `.gitmodules` / `.git/config` key | `references/urls-and-config.md` |
|
||||
| Remove a submodule, or `deinit` one without removing it | `references/removal.md` |
|
||||
|
||||
Removal and `deinit` are destructive: state what will be deleted and get confirmation before
|
||||
executing.
|
||||
|
||||
## Output format
|
||||
|
||||
```yaml
|
||||
operation: <clone|add|init|update|status|sync|set-url|set-branch|absorbgitdirs|deinit|remove>
|
||||
status: <success|error|partial>
|
||||
message: <one line; include git's own output on error>
|
||||
details:
|
||||
- <submodule-path>: <state>
|
||||
conflicts: [<submodule-path>, ...]
|
||||
next_step: <recovery action, when status is error or partial>
|
||||
```
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
topic: submodules
|
||||
source_keys:
|
||||
- git-scm-submodule-docs
|
||||
---
|
||||
|
||||
# Removing and deinitializing a submodule
|
||||
|
||||
Both operations are destructive. Confirm with the user before executing either.
|
||||
|
||||
## `deinit` is not removal
|
||||
|
||||
```bash
|
||||
rtk git submodule deinit <path> # --all for every submodule, -f if locally modified
|
||||
```
|
||||
|
||||
`deinit` clears the submodule's section from `.git/config` and empties its working tree. The
|
||||
`.gitmodules` entry and the gitlink in the superproject's index are untouched, so the submodule is
|
||||
still registered and a later `update --init` brings it straight back. Use it to reclaim disk space
|
||||
or to reset a broken checkout, not to delete a dependency.
|
||||
|
||||
## Full removal, in order
|
||||
|
||||
```bash
|
||||
rtk git submodule deinit -f <path> # unregister from .git/config
|
||||
rtk git rm <path> # drop the .gitmodules entry and the gitlink from the index
|
||||
rm -rf .git/modules/<name>/ # stale git dir: not tracked, not cleaned up by git
|
||||
rtk git commit -m "chore: remove <name> submodule"
|
||||
```
|
||||
|
||||
The third step is the one that gets skipped. `.git/modules/<name>/` survives `rtk git rm`, and while it
|
||||
is present Git refuses to add a submodule at the same path again.
|
||||
@@ -1,96 +0,0 @@
|
||||
---
|
||||
topic: submodules
|
||||
source_keys:
|
||||
- git-scm-submodule-docs
|
||||
---
|
||||
|
||||
# Adding, initializing, updating and pinning submodules
|
||||
|
||||
## Clone a superproject that already has submodules
|
||||
|
||||
```bash
|
||||
rtk git clone --recurse-submodules <url> # Git 2.13+, one step
|
||||
# or, against an existing clone
|
||||
rtk git submodule update --init --recursive
|
||||
```
|
||||
|
||||
## Add a dependency as a submodule
|
||||
|
||||
```bash
|
||||
rtk git submodule add <url> <path>
|
||||
rtk git commit -m "chore: add <name> as submodule"
|
||||
```
|
||||
|
||||
`add` stages a `.gitmodules` entry and a gitlink — the commit is still required. Flags:
|
||||
|
||||
| Flag | Meaning |
|
||||
|---|---|
|
||||
| `-b <branch>` | Track a branch (`submodule.<name>.branch`) instead of only a pinned commit |
|
||||
| `--depth <n>` | Shallow clone |
|
||||
| `-f` | Force past a gitignored path or a name conflict |
|
||||
| `--name <name>` | Logical name differing from the path |
|
||||
|
||||
## Initialize without cloning
|
||||
|
||||
`rtk git submodule init [<path>...]` copies submodule URLs from `.gitmodules` into `.git/config` and
|
||||
does nothing else. This is the point at which a local URL override can be edited before any fetch
|
||||
happens. If a local mirror override is wanted, read `references/urls-and-config.md` before running
|
||||
`update`. Use `update --init` to run both steps at once.
|
||||
|
||||
## Update
|
||||
|
||||
`rtk git submodule update --init --recursive` is the common case: it clones what is missing and checks
|
||||
out the commit the superproject recorded, in detached HEAD.
|
||||
|
||||
| Flag | Meaning |
|
||||
|---|---|
|
||||
| `--init` | Run `init` first, avoiding a separate step |
|
||||
| `--remote` | Use the submodule's remote branch tip instead of the superproject's recorded commit |
|
||||
| `--checkout` | Detached HEAD at the recorded commit (default) |
|
||||
| `--rebase` | Rebase the current branch onto the recorded commit |
|
||||
| `--merge` | Merge the recorded commit into the current branch |
|
||||
| `--recursive` | Operate on nested submodules |
|
||||
| `--jobs <n>` | Parallel clone (defaults to `submodule.fetchJobs`) |
|
||||
| `-N` / `--no-fetch` | Skip the remote fetch |
|
||||
| `-f` | Discard local changes in the submodule working tree |
|
||||
| `--depth <n>` | Shallow clone |
|
||||
| `--filter <spec>` | Partial clone filter |
|
||||
|
||||
## Keep submodules pinned to the recorded commit
|
||||
|
||||
```bash
|
||||
rtk git submodule update --recursive # after every rtk git pull
|
||||
rtk git config submodule.recurse true # or do it automatically on pull/push/checkout
|
||||
```
|
||||
|
||||
## Move the pin forward to the tracked branch tip
|
||||
|
||||
```bash
|
||||
rtk git submodule update --remote --merge --recursive
|
||||
rtk git commit -am "chore: update submodules to latest"
|
||||
```
|
||||
|
||||
`--remote` uses `submodule.<name>.branch` when it is set; without it Git falls back to the remote's
|
||||
default branch. Commit the superproject afterwards or the new pin is lost on the next `update`.
|
||||
|
||||
## Run one command across every submodule
|
||||
|
||||
```bash
|
||||
rtk git submodule foreach --recursive '<command>'
|
||||
rtk git submodule foreach 'git pull origin main || :' # || : continues past a failure
|
||||
```
|
||||
|
||||
`<command>` runs inside each submodule's own working tree, so the git calls in it are the
|
||||
submodule's own — that is the one place a bare `git` is correct. Append `|| :` to keep the
|
||||
traversal going instead of aborting at the first failure.
|
||||
|
||||
Git exports five shell variables into `<command>`. `$sm_path` and `$displaypath` name the same
|
||||
directory from different vantage points and are not interchangeable:
|
||||
|
||||
| Variable | Meaning |
|
||||
|---|---|
|
||||
| `$name` | Logical submodule name (the `.gitmodules` section name, which need not match the path) |
|
||||
| `$sm_path` | Path relative to the superproject root |
|
||||
| `$displaypath` | Path relative to the current working directory |
|
||||
| `$sha1` | Commit SHA the superproject has recorded for this submodule |
|
||||
| `$toplevel` | Absolute path of the superproject's root |
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
topic: submodules
|
||||
source_keys:
|
||||
- git-scm-submodule-docs
|
||||
---
|
||||
|
||||
## git-scm-submodule-docs
|
||||
|
||||
**Description:** Official git-scm.com reference for `git submodule` — all subcommands, flags, configuration keys, and behaviour details.
|
||||
|
||||
**Source:** https://git-scm.com/docs/git-submodule
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/submodules.md (whole-document reference — the research doc is organized by descriptive prose headings such as "Concept Overview" and "Key Commands" rather than a heading matching this slug; this key covers the entire doc, not a single section)
|
||||
|
||||
**Contributing files:**
|
||||
- SKILL.md (all sections)
|
||||
- references/setup-and-update.md (all sections)
|
||||
- references/urls-and-config.md (all sections)
|
||||
- references/removal.md (all sections)
|
||||
|
||||
---
|
||||
|
||||
Other source keys extracted during the git plugin research phase inform sibling skills in the git workflow suite, not this one:
|
||||
|
||||
- `context7-git-htmldocs` — git-branches, git-history, git-remotes
|
||||
- `git-scm-docs` — no current skill; it backed a git-configuration skill that no longer exists and survives here as provenance only
|
||||
- `git-scm-worktree-docs` — git-worktrees
|
||||
- `nvie-gitflow-post`, `atlassian-gitflow-tutorial`, `gitflow-cheatsheet` — git-branches
|
||||
- `conventional-commits-spec`, `commitlint-config-conventional` — git-commits
|
||||
- `git-scm-push-docs`, `git-scm-fetch-docs`, `git-scm-pull-docs`, `git-scm-remote-docs` — git-remotes
|
||||
- `git-scm-bisect-docs`, `git-scm-log-docs`, `git-scm-diff-docs` — git-history
|
||||
@@ -1,79 +0,0 @@
|
||||
---
|
||||
topic: submodules
|
||||
source_keys:
|
||||
- git-scm-submodule-docs
|
||||
---
|
||||
|
||||
# Where a submodule points, and how it is configured
|
||||
|
||||
## Two files, two audiences
|
||||
|
||||
- **`.gitmodules`** — version-controlled, shared with collaborators. Defines each submodule's
|
||||
logical name, path, and canonical URL.
|
||||
- **`.git/config`** — local only, populated by `rtk git submodule init`. Local URL overrides live here
|
||||
and never propagate to another clone.
|
||||
|
||||
The submodule's own `.git` directory lives at `.git/modules/<name>/` in the superproject and is
|
||||
linked to the submodule's working tree by a `.git` pointer file.
|
||||
|
||||
## `.gitmodules` keys
|
||||
|
||||
| Key | Purpose |
|
||||
|---|---|
|
||||
| `submodule.<name>.path` | Working tree path |
|
||||
| `submodule.<name>.url` | Remote URL |
|
||||
| `submodule.<name>.branch` | Branch used by `update --remote` |
|
||||
| `submodule.<name>.update` | Default update procedure |
|
||||
| `submodule.<name>.shallow` | Recommend a shallow clone |
|
||||
|
||||
## `.git/config` keys
|
||||
|
||||
| Key | Purpose |
|
||||
|---|---|
|
||||
| `submodule.<name>.url` | Local URL override |
|
||||
| `submodule.<name>.update` | Local procedure override |
|
||||
| `submodule.fetchJobs` | Default parallelism for `update --jobs` |
|
||||
| `submodule.recurse` | Auto-recurse submodule updates on `pull`/`push`/etc. |
|
||||
|
||||
## Rebind a URL or branch
|
||||
|
||||
```bash
|
||||
rtk git submodule sync --recursive # push .gitmodules URLs into .git/config
|
||||
rtk git submodule set-url <path> <url> # change the canonical URL
|
||||
rtk git submodule set-branch -b <branch> <path> # set the branch used by update --remote
|
||||
```
|
||||
|
||||
Run `sync` after an upstream rename: existing clones keep the stale URL in `.git/config` until
|
||||
they do.
|
||||
|
||||
## Override a URL locally (private mirror)
|
||||
|
||||
```bash
|
||||
rtk git submodule init
|
||||
# edit .git/config: submodule.<name>.url = <mirror-url>
|
||||
rtk git submodule update
|
||||
```
|
||||
|
||||
Local-only, invisible to collaborators, and overwritten by the next `sync`.
|
||||
|
||||
## Relative URLs
|
||||
|
||||
A `../foo.git` entry in `.gitmodules` resolves against the superproject's default remote URL, not
|
||||
against the filesystem. It is portable across hosts that mirror the same layout and broken
|
||||
everywhere else.
|
||||
|
||||
## Custom `update` commands are security-gated
|
||||
|
||||
A `.gitmodules` entry of `update = !some-command` is never copied into `.git/config` by
|
||||
`rtk git submodule init`. That is deliberate: it stops a hostile clone from silently executing
|
||||
arbitrary code. Setting it locally in `.git/config` is the only way to enable it.
|
||||
|
||||
## Relocate an embedded `.git` directory
|
||||
|
||||
```bash
|
||||
rtk git submodule absorbgitdirs [<path>...]
|
||||
```
|
||||
|
||||
Moves a submodule's own `.git` directory into `.git/modules/<name>/` and leaves a `.git` pointer
|
||||
file behind. Needed when a nested repository was created or copied in without going through
|
||||
`rtk git submodule add`.
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
name: git-workflow
|
||||
|
||||
description: >
|
||||
Use when a human's local git request is general or ambiguous — it routes to the owning
|
||||
domain skill: `git-commits`, `git-branches`, `git-history`, `git-remotes`, `git-submodules`
|
||||
or `git-worktrees`. An unambiguous request goes straight to its domain skill instead. Not an
|
||||
agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`.
|
||||
|
||||
metadata:
|
||||
version: "1.0.2"
|
||||
category: git
|
||||
source_keys:
|
||||
- nvie-gitflow-post
|
||||
- atlassian-gitflow-tutorial
|
||||
- gitflow-cheatsheet
|
||||
- context7-git-htmldocs
|
||||
- org-git-conventions
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
- Session context built during one multi-step request — branch names, the chosen base, the commit
|
||||
strategy — persists for that request and then clears. Do not re-ask the user for a decision they
|
||||
already gave you earlier in the same workflow.
|
||||
- Run parent-repo commands through `rtk git <command>`, never bare `git <command>`. This is a
|
||||
mandated org wrapper, not a style preference. Submodule-specific commands run from inside the
|
||||
submodule's own directory instead.
|
||||
|
||||
## Domains
|
||||
|
||||
Route to the domain that owns the operation, and in sequence when a request spans two — a rebase
|
||||
that ends in a force-push is `git-commits`, then `git-remotes`. An unambiguous request should have
|
||||
gone straight to the domain skill; this one exists for the ones that did not.
|
||||
|
||||
| The request is about | Domain |
|
||||
|---|---|
|
||||
| Writing, amending, squashing, or cherry-picking a commit, and its message | `git-commits` |
|
||||
| Rebasing onto a new base, or undoing a commit with `reset` | `git-commits` |
|
||||
| Creating, switching, deleting, renaming, tracking, or merging a local branch | `git-branches` |
|
||||
| Stashing work in progress to move between branches | `git-branches` |
|
||||
| When a change landed, which commit broke something, what to revert or backport | `git-history` |
|
||||
| Anything touching a remote — remote config, fetch, push, pull — even unnamed | `git-remotes` |
|
||||
| A nested repository pinned inside this one by a recorded commit | `git-submodules` |
|
||||
| Several branches checked out at once, in separate directories, without stashing | `git-worktrees` |
|
||||
|
||||
`git-orchestrate` executes whatever this resolves to (step 5); the table only decides which domain
|
||||
owns the request.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Parse intent** — extract the operation and, from the table above, the domain that owns it,
|
||||
plus any options the user named.
|
||||
2. **Check the hard rules** — if the request creates, amends, or rewrites a commit, pushes, or
|
||||
touches hooks, config, or credentials, read `references/hard-rules.md`. Raise the relevant rule
|
||||
before acting, not after.
|
||||
3. **Read the repo** — current branch, working-tree state, and which branching model the repo
|
||||
follows (`git-branches` infers this from branch names: Gitflow if `develop`/`release/*` exists,
|
||||
GitHub Flow otherwise); the last of those decides which tips are worth offering.
|
||||
4. **Gate destructive operations** — before force-push, branch deletion, rebase, or
|
||||
force-checkout, show what will happen and ask "Proceed?". Cancel gracefully if the user
|
||||
declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not
|
||||
confirmations — never offer "Proceed?" for a force-push of `main`/`master`.
|
||||
5. **Invoke the `git-orchestrate` agent** with `operation`, `parameters` (user-provided or
|
||||
inferred), `context` (step 3 plus the session context), and `confirm: true` only for a
|
||||
destructive op the user approved in step 4.
|
||||
6. **Clarify when the orchestrator asks for more** — put its question to the user in plain
|
||||
language ("Which branch should this be based on?") and loop back to step 5 with the answer.
|
||||
7. **Report the outcome** — on success, the result and what changed, in plain language; on
|
||||
failure, the error reason and a recovery action.
|
||||
|
||||
## Interaction style
|
||||
|
||||
The caller is a human, so the interaction is the point. Explain each step and why it happens ("I'm
|
||||
squashing your last 3 commits into one clean commit" beats "Squashing commits"), show progress as
|
||||
you go, and prefer natural language to raw command lines.
|
||||
|
||||
Match tips to the repo's branching model rather than offering generic advice: on a Gitflow repo,
|
||||
feature branches come off `develop` and `main` tracks only released code; on a trunk-based or
|
||||
GitHub Flow repo, short-lived branches off `main` keep merges small and reviewable.
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- org-git-conventions
|
||||
---
|
||||
|
||||
# Org git hard rules
|
||||
|
||||
Non-negotiable regardless of what the user asks for. Surface the relevant one proactively rather
|
||||
than waiting for the user to hit it — a human invoking this skill directly never sees the
|
||||
orchestrator's copy of these rules, so raise them here.
|
||||
|
||||
- Never skip hooks with `--no-verify` — hooks are the automated QA gate, and bypassing them breaks
|
||||
the pipeline for everyone downstream.
|
||||
- Never force-push `main` or `master`.
|
||||
- Keep commits atomic — each commit should represent one logical, independently reviewable and
|
||||
reversible change.
|
||||
- Every commit must leave the repository in a working state (buildable/testable where practical).
|
||||
- Commit messages explain **why**, not **what** — the diff already documents what changed.
|
||||
- Never commit secrets, credentials, or environment-specific config.
|
||||
- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.).
|
||||
- Reference related issues, ADRs, or design documents using Git trailers when applicable.
|
||||
|
||||
If a user's request conflicts with one of these (e.g. "force-push main to fix this"), explain the
|
||||
rule and propose a safe alternative instead of complying. Do not comply and note the rule
|
||||
afterwards.
|
||||
@@ -1,60 +0,0 @@
|
||||
---
|
||||
# Research sources referenced by this skill
|
||||
# Each entry documents where the skill's guidance came from.
|
||||
---
|
||||
|
||||
## nvie-gitflow-post
|
||||
|
||||
**Description:** Original 2010 post by Vincent Driessen introducing the Gitflow branching model, including a 2020 reflection note recommending GitHub Flow for continuous delivery teams.
|
||||
|
||||
**Source:** https://nvie.com/posts/a-successful-git-branching-model/
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
|
||||
|
||||
**Contributing files:**
|
||||
- SKILL.md (Interaction style — branching-model-aware tips)
|
||||
|
||||
## atlassian-gitflow-tutorial
|
||||
|
||||
**Description:** Atlassian's comprehensive Gitflow tutorial covering all five branch types, lifecycle steps, and CLI usage.
|
||||
|
||||
**Source:** https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
|
||||
|
||||
**Contributing files:**
|
||||
- SKILL.md (Interaction style — branching-model-aware tips)
|
||||
|
||||
## gitflow-cheatsheet
|
||||
|
||||
**Description:** Visual cheatsheet for the git-flow CLI commands (git-flow-avh fork), covering all subcommands for feature, release, and hotfix branches.
|
||||
|
||||
**Source:** https://danielkummer.github.io/git-flow-cheatsheet/
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
|
||||
|
||||
**Contributing files:**
|
||||
- SKILL.md (Interaction style — branching-model-aware tips)
|
||||
|
||||
## context7-git-htmldocs
|
||||
|
||||
**Description:** Official Git HTML documentation from the git/htmldocs repository — covers all commands, concepts, and internals.
|
||||
|
||||
**Source:** context7:/git/htmldocs
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/overview.md (whole-document reference)
|
||||
|
||||
**Contributing files:**
|
||||
- SKILL.md (Workflow — general git operation vocabulary)
|
||||
|
||||
## org-git-conventions
|
||||
|
||||
**Description:** This org's internal git conventions (hard rules on hooks, force-push, atomic commits, secrets, Conventional Commits, trailers, and the `rtk git` wrapper requirement). Originally maintained as a standalone instruction file loaded into every agent's context; embedded directly into this skill because that central file has been removed from the repo, and skill content must stay self-contained after plugin installation.
|
||||
|
||||
**Source:** org-internal (formerly `core/instructions/git.md` in this repo, prior to its removal)
|
||||
|
||||
- **Research doc:** none — org convention, not part of the plugin's research corpus (no `plugins/git/docs/research/` topic file backs this entry)
|
||||
|
||||
**Contributing files:**
|
||||
- references/hard-rules.md (whole file — the eight hard rules and the conflict-handling rule)
|
||||
- SKILL.md (Gotchas — `rtk git` wrapper note)
|
||||
@@ -1,68 +0,0 @@
|
||||
---
|
||||
name: git-worktrees
|
||||
|
||||
description: >
|
||||
Use when working on several branches at once without stashing —
|
||||
manages the full lifecycle of a git worktree.
|
||||
Not ordinary branch switching or checkout -> `git-branches`.
|
||||
Not interactive multi-step git guidance -> `git-workflow`.
|
||||
|
||||
metadata:
|
||||
version: "1.0.2"
|
||||
category: git
|
||||
source_keys:
|
||||
- git-scm-worktree-docs
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **A branch can be checked out in only one worktree at a time.** `git worktree add` on an already-checked-out branch fails; `--force` is the only override, so use it only deliberately.
|
||||
- **Never `rm -rf` a worktree directory.** That strands metadata in `$GIT_DIR/worktrees/`. Use `rtk git worktree remove`, or `rtk git worktree prune` afterwards.
|
||||
- **Submodules break worktree support.** A worktree containing submodules cannot be moved at all, and needs `--force` to remove.
|
||||
- **`extensions.worktreeConfig = true` is a one-way door.** Without it, `git config --worktree` errors; with it, that flag writes to the worktree's own `config.worktree` file, and `core.bare`/`core.worktree` are forced there too. It also breaks older Git. Leave it off unless per-worktree config is needed.
|
||||
|
||||
## Step 1 — Dispatch
|
||||
|
||||
| Operation | Run |
|
||||
|---|---|
|
||||
| Create on a branch that already exists locally | `rtk git worktree add <path> <branch>` |
|
||||
| Create on a new branch | `rtk git worktree add -b <branch> <path>` |
|
||||
| Create on the branch named after the path basename | `rtk git worktree add <path>` — checks that branch out if it exists, else creates it from HEAD |
|
||||
| Create and reset an existing branch to HEAD — discards its commits | `rtk git worktree add -B <branch> <path>` |
|
||||
| Create a local branch tracking a remote one | `rtk git worktree add --track -b <branch> <path> <remote>/<branch>` — always correct. `git worktree add <path> <branch>` expands to exactly this, but **only** under the conditions in `references/worktrees.md` |
|
||||
| Throwaway experiment, no branch | `rtk git worktree add -d <path>` — detached HEAD |
|
||||
| **Never** `git worktree add <path> <remote>/<branch>` | That ref resolves, so the shortcut never fires and you get **a detached HEAD, no branch, no upstream**. Commits there go unreachable once HEAD moves, and `git push` needs an explicit refspec. Use the tracking row above |
|
||||
| List | `git worktree list -v` to read, or `git worktree list --porcelain -z` to parse — both bare (ADR-0023): rtk re-renders the output and drops the porcelain flags |
|
||||
| Lock or unlock | `rtk git worktree lock [--reason <str>] <path>` / `rtk git worktree unlock <path>` |
|
||||
| Move | `rtk git worktree move <from> <to>` |
|
||||
| Remove | `rtk git worktree remove <path>` |
|
||||
| Prune stale metadata | `rtk git worktree prune --dry-run`, then without the flag |
|
||||
| Repair after a manual move | `rtk git worktree repair` — in the main worktree if *it* moved, or inside a linked worktree that moved. `rtk git worktree repair <path>...` — from any worktree, naming each moved linked worktree's new path |
|
||||
|
||||
If the operation needs anything the table does not carry — the full `add` flag
|
||||
table, orphan branches, sparse-checkout, locking for removable media, remote
|
||||
disambiguation across several remotes, how to name a worktree unambiguously,
|
||||
worktree config keys, or the worked emergency-fix and PR-review patterns — read
|
||||
`references/worktrees.md`.
|
||||
|
||||
Gates:
|
||||
|
||||
- **`move`, `remove` — the main worktree cannot be moved or removed.** Only linked worktrees, the ones `git worktree add` created, are candidates.
|
||||
- **`add`, `move`, `remove` — escalate force flags one step at a time.** `-f` overrides a safeguard such as an unclean tree; `move` and `remove` need `-ff` on top of that when the worktree is locked. Confirm with the user before either — both discard state.
|
||||
- **`add` — lock at creation, not after.** `rtk git worktree add --lock` is atomic, where add-then-`lock` leaves a window in which the worktree is unprotected.
|
||||
|
||||
## Step 2 — Report
|
||||
|
||||
```yaml
|
||||
worktrees:
|
||||
- path: <directory-path>
|
||||
branch: <branch-name>
|
||||
commit: <short-hash>
|
||||
locked: <true/false>
|
||||
lock_reason: <reason or empty>
|
||||
```
|
||||
|
||||
Derive those fields from `git worktree list --porcelain -z` — bare, not `rtk`:
|
||||
rtk drops both flags and never emits `locked`/`lock_reason`. For a single
|
||||
operation, report its outcome instead — `created: true`, `moved: true`,
|
||||
`removed: true`.
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
# Research sources referenced by this skill
|
||||
# Each entry documents where the skill's guidance came from.
|
||||
---
|
||||
|
||||
## git-scm-worktree-docs
|
||||
|
||||
**Description:** Git SCM official documentation for `git worktree` command — creating, listing, locking, moving, removing, pruning, and repairing linked worktrees; shared vs. per-worktree state; worktree-scoped config.
|
||||
|
||||
**Source:** https://git-scm.com/docs/git-worktree
|
||||
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/worktrees.md (whole-document reference — covers `## Concept Overview`, `## Key Commands`, `## Workflow Patterns`, `## Common Gotchas`, `## Configuration`)
|
||||
|
||||
**Contributing files:**
|
||||
- SKILL.md (Gotchas, Step 1 dispatch table and per-operation gates, Step 2 report format)
|
||||
- references/worktrees.md (shared vs. per-worktree state, `add` command forms, full `add` flag table, orphan branches, sparse-checkout, removable media, remote disambiguation, `repair` invocation directory, configuration, workflow patterns)
|
||||
@@ -1,178 +0,0 @@
|
||||
---
|
||||
topic: worktrees
|
||||
source_keys:
|
||||
- git-scm-worktree-docs
|
||||
---
|
||||
|
||||
# Git worktrees
|
||||
|
||||
## Shared vs. per-worktree state
|
||||
|
||||
All worktrees share one object store, one config, and most refs under `refs/`. Each worktree keeps
|
||||
its own `HEAD`, index, and per-worktree metadata (`ORIG_HEAD`, `MERGE_HEAD`, `refs/bisect/`,
|
||||
`refs/worktree/`, `refs/rewritten/`) under `$GIT_DIR/worktrees/<name>/`. Exactly one **main
|
||||
worktree** exists per repo — the one `git init` or `git clone` produced — and it cannot be removed
|
||||
or moved. Every other worktree is a **linked worktree** created by `git worktree add`.
|
||||
|
||||
## Identifying a worktree
|
||||
|
||||
`lock`, `move`, `remove` and `repair` accept a full path, a unique basename, or a unique partial
|
||||
path. An ambiguous name errors rather than picking one; `git worktree list` shows the identifiers
|
||||
that are usable.
|
||||
|
||||
## `add` forms
|
||||
|
||||
```bash
|
||||
rtk git worktree add <path> <branch> # <branch> exists locally: check it out — non-destructive
|
||||
rtk git worktree add -b <branch> <path> # create a new branch; fails if it exists
|
||||
rtk git worktree add <path> # branch named after $(basename <path>): checked out
|
||||
# if it exists, else created from HEAD
|
||||
rtk git worktree add -B <branch> <path> # create the branch, or reset an existing one to HEAD,
|
||||
# discarding the commits it carried
|
||||
rtk git worktree add --track -b <branch> <path> <remote>/<branch>
|
||||
# new local branch tracking the remote — always works
|
||||
rtk git worktree add <path> <branch> # <branch> absent locally and in exactly one remote:
|
||||
# Git expands this to the --track -b form above
|
||||
rtk git worktree add -d <path> # detached HEAD, no branch
|
||||
```
|
||||
|
||||
The same `git worktree add <path> <branch>` spelling appears twice above and does two
|
||||
different things: it checks out a local branch when one exists, and only otherwise falls
|
||||
through to the remote-tracking shortcut. Read the local branch list before relying on either.
|
||||
|
||||
**Do not write `git worktree add <path> <remote>/<branch>`.** A remote-tracking ref resolves as a
|
||||
commit-ish, so the tracking shortcut never fires and the worktree lands on a **detached HEAD with
|
||||
no local branch and no upstream** — commits there go unreachable once HEAD moves or the worktree is
|
||||
removed, and `git push` fails without an explicit refspec. That spelling is correct only as the
|
||||
final argument of the `--track -b` form.
|
||||
|
||||
## Full `add` flag table
|
||||
|
||||
| Flag | Meaning |
|
||||
|---|---|
|
||||
| `-b <branch>` | Create and check out a new branch; fails if it exists |
|
||||
| `-B <branch>` | Like `-b` but resets the branch if it already exists |
|
||||
| `-d` / `--detach` | Detach HEAD; useful for throwaway experiments |
|
||||
| `--orphan` | Create empty unborn branch — **Git 2.42+**; earlier versions exit 129 with `error: unknown option 'orphan'`. Fallback below |
|
||||
| `--no-checkout` | Suppress initial checkout (for sparse-checkout setup) |
|
||||
| `--guess-remote` | Look for a matching remote-tracking branch by path basename |
|
||||
| `--lock [--reason <str>]` | Lock immediately on creation (atomic; avoids race vs. add-then-lock) |
|
||||
| `-f` / `--force` | Allow when branch is already checked out elsewhere |
|
||||
| `--relative-paths` | Link via relative paths (portable across moves) |
|
||||
|
||||
Using `-` as `<commit-ish>` is shorthand for `@{-1}` (the branch checked out before the current one), e.g. `git worktree add <path> -`.
|
||||
|
||||
## New unborn branch
|
||||
|
||||
```bash
|
||||
rtk git worktree add --orphan -b <branch> <path>
|
||||
```
|
||||
Creates an empty branch with no commits. **`--orphan` needs Git 2.42 or later** — it was added
|
||||
upstream in 2.42, and on 2.39.5 this fails with `error: unknown option 'orphan'` and exit 129.
|
||||
Check `rtk git --version` before reaching for it.
|
||||
|
||||
Fallback on older Git, verified on 2.39.5 — detach first, then orphan the linked worktree in place,
|
||||
which leaves the main worktree on its own branch throughout:
|
||||
|
||||
```bash
|
||||
rtk git worktree add -d <path> # linked worktree, detached HEAD
|
||||
cd <path>
|
||||
rtk git switch --orphan <branch> # unborn branch: empty index, empty working tree
|
||||
```
|
||||
|
||||
`git worktree list` then shows the new worktree at `0000000 [<branch>]` until its first commit.
|
||||
Do not substitute `git switch --orphan` in the *main* worktree: it clears that checkout, which is
|
||||
the disruption worktrees exist to avoid.
|
||||
|
||||
## Sparse-checkout worktree
|
||||
|
||||
Suppress the initial checkout to configure sparse-checkout first:
|
||||
```bash
|
||||
rtk git worktree add --no-checkout ../sparse main
|
||||
cd ../sparse
|
||||
rtk git sparse-checkout init --cone
|
||||
rtk git sparse-checkout set src/
|
||||
rtk git checkout main
|
||||
```
|
||||
|
||||
## Worktree on removable media
|
||||
|
||||
```bash
|
||||
rtk git worktree add --lock --reason "external SSD" <path> <branch>
|
||||
rtk git worktree unlock <path> # when reconnected
|
||||
```
|
||||
|
||||
## Remote-branch disambiguation
|
||||
|
||||
```bash
|
||||
rtk git worktree add --track -b <branch> <path> <remote>/<branch> # explicit: no guessing at all
|
||||
rtk git worktree add <path> <branch> # shortcut: needs one clear remote
|
||||
```
|
||||
**The bare-name shortcut needs exactly one remote.** It fires only when `<branch>` is not found
|
||||
locally, none of `-b`/`-B`/`--detach` were given, and a tracking branch of that name exists in
|
||||
exactly one remote. When several remotes carry the name, `checkout.defaultRemote` picks one for
|
||||
disambiguation purposes; with no such setting the shortcut has no single remote to resolve against
|
||||
and does not apply. When the remote is ambiguous or unknown, use the explicit `--track -b` form.
|
||||
|
||||
`--guess-remote` covers the *other* spelling — `git worktree add <path>` with no `<commit-ish>` at
|
||||
all. It bases the new branch on the remote-tracking branch matching `$(basename <path>)` when
|
||||
exactly one remote has it, and marks that branch as upstream. Its default comes from the
|
||||
`worktree.guessRemote` config.
|
||||
|
||||
## Repair after a manual move
|
||||
|
||||
```bash
|
||||
rtk git worktree repair # the MAIN worktree moved: run it there to reconnect every linked
|
||||
# worktree back to the main worktree
|
||||
rtk git worktree repair # a LINKED worktree moved: run it inside that recently-moved worktree
|
||||
rtk git worktree repair <path>... # reconnect a specific linked worktree — runnable from any worktree,
|
||||
# naming each moved tree's new path
|
||||
```
|
||||
|
||||
Which form applies depends on what moved:
|
||||
|
||||
| What moved | Remedy |
|
||||
|---|---|
|
||||
| The main worktree (or bare repo) | `rtk git worktree repair` in the main worktree |
|
||||
| One linked worktree | `rtk git worktree repair` inside that worktree |
|
||||
| Several linked worktrees | `rtk git worktree repair <path>...` from any worktree, listing each new path |
|
||||
| Both main and linked worktrees | `rtk git worktree repair <path>...` in the main worktree, naming each linked worktree's new path — this restores the connections in both directions |
|
||||
|
||||
Only the no-argument form is tied to the current directory. The `<path>...` form is not — it
|
||||
reestablishes the connection to every path you name, run from any worktree.
|
||||
|
||||
## Configuration
|
||||
|
||||
| Key | Effect |
|
||||
|---|---|
|
||||
| `worktree.guessRemote` | Default for `--guess-remote` on `git worktree add` |
|
||||
| `worktree.useRelativePaths` | Default for `--relative-paths` on `git worktree add` (link via relative paths — portable across moves) |
|
||||
| `gc.worktreePruneExpire` | How long before stale worktree metadata is pruned by `git gc` |
|
||||
| `extensions.worktreeConfig` | Enable per-worktree config scope (`config.worktree` file) — see Gotchas in SKILL.md |
|
||||
| `checkout.defaultRemote` | Disambiguates which remote to use when a branch name matches multiple remotes during `worktree add` |
|
||||
|
||||
## Workflow patterns
|
||||
|
||||
**Emergency fix without disrupting current work** — nothing is stashed, and the main worktree is
|
||||
untouched throughout:
|
||||
|
||||
```bash
|
||||
rtk git worktree add -b emergency-fix ../temp main
|
||||
cd ../temp
|
||||
# fix, then commit
|
||||
rtk git commit -a -m "fix: critical production bug"
|
||||
cd -
|
||||
rtk git worktree remove ../temp
|
||||
```
|
||||
|
||||
**Review a PR branch alongside your own work** — both branches stay checked out, so there is no
|
||||
context switch:
|
||||
|
||||
```bash
|
||||
rtk git worktree add ../review-pr-123 origin/feature-xyz # detached HEAD — read-only review
|
||||
rtk git worktree add --track -b feature-xyz ../review-pr-123 origin/feature-xyz # if you will commit
|
||||
# open ../review-pr-123 in a second editor window or terminal
|
||||
```
|
||||
|
||||
Pick the second form the moment you intend to push anything back: the first leaves no branch to
|
||||
push and no upstream to push to.
|
||||
@@ -1,38 +0,0 @@
|
||||
---
|
||||
name: pc-author
|
||||
description: >
|
||||
Use when the user wants to create or edit `.pre-commit-config.yaml` — add,
|
||||
remove, or configure hooks — even when they name only the tool ("add
|
||||
shellcheck"). Not running, installing, or updating hooks -> `pc-run`.
|
||||
allowed-tools: Bash Read Write Edit
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
category: devtools
|
||||
source_keys:
|
||||
- context7-pre-commit-com
|
||||
- pre-commit-com
|
||||
- context7-pre-commit-hooks
|
||||
- pre-commit-hooks-github
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
- `rev` must be an immutable tag or commit SHA, never a branch name. A branch looks like it works and then breaks `pre-commit autoupdate` silently.
|
||||
- `pre-commit validate-config` checks YAML structure only — it never confirms a hook `id` exists upstream, so a config it accepts can still fail on first use.
|
||||
|
||||
## Route
|
||||
|
||||
| Condition | Flow | Read |
|
||||
|---|---|---|
|
||||
| No `.pre-commit-config.yaml` in the repo | Create | `references/create-config.md` |
|
||||
| `.pre-commit-config.yaml` exists | Modify | `references/modify-config.md` |
|
||||
|
||||
Read only the file matching the resolved flow — each is self-contained.
|
||||
|
||||
The target is always `.pre-commit-config.yaml`, the config that consumes hooks. A request to publish hooks for other repos to consume means `.pre-commit-hooks.yaml`, a different file this skill does not author.
|
||||
|
||||
## Gates common to both flows
|
||||
|
||||
1. State the proposed config or edit in full and wait for confirmation before writing. Hook choices are opinions imposed on everyone else's commit loop, not defaults to assume.
|
||||
2. Run `pre-commit validate-config` after every write. On a non-zero exit, show the error and resolve it before reporting done — never leave a config that cannot be parsed.
|
||||
3. Never edit a `rev` value. Report staleness and hand the bump to `pc-run`, which runs `autoupdate` against the hook repos themselves.
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- context7-pre-commit-com
|
||||
- pre-commit-com
|
||||
---
|
||||
|
||||
# Creating a `.pre-commit-config.yaml`
|
||||
|
||||
Reached from `SKILL.md`'s Route table when the repo has no config yet. Self-contained — the modify
|
||||
flow's file is not needed here. `SKILL.md`'s three common gates still apply.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Detect what languages are actually in the repo with a shallow extension scan, rather than
|
||||
inferring them from the project's name or README:
|
||||
|
||||
```bash
|
||||
rtk git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn
|
||||
```
|
||||
|
||||
2. Read `references/hooks-by-language.md` and map the detected extensions to recommended hooks.
|
||||
Take the repo URL, `rev` and args from that file rather than from memory — a `rev` that does not
|
||||
exist is the most common way a fresh config fails on its first run.
|
||||
|
||||
For a deliberately minimal starting point instead of a full recommendation set,
|
||||
`pre-commit sample-config > .pre-commit-config.yaml` prints a small starter config to build on.
|
||||
|
||||
3. State the proposed config in full and wait for the user's confirmation.
|
||||
|
||||
4. Write `.pre-commit-config.yaml`, then run `pre-commit validate-config`. If it exits non-zero,
|
||||
show the error, fix it in place, and re-validate.
|
||||
@@ -1,92 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- context7-pre-commit-com
|
||||
- pre-commit-com
|
||||
- context7-pre-commit-hooks
|
||||
- pre-commit-hooks-github
|
||||
---
|
||||
|
||||
# Hook Recommendations by Language / Context
|
||||
|
||||
Use this table when creating a config from scratch or recommending hooks to add.
|
||||
Always check the existing config for duplicates before proposing.
|
||||
|
||||
Fixer hooks (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json` and the like) rewrite
|
||||
files but do NOT re-stage them, so the commit is still blocked and the user has to stage and commit
|
||||
again. Say so when proposing one — otherwise the first blocked commit reads as the hook being
|
||||
broken.
|
||||
|
||||
## `pre-commit/pre-commit-hooks` (rev `v6.0.0`)
|
||||
|
||||
| Hook ID | Language / Context |
|
||||
|---------|---------------------|
|
||||
| `end-of-file-fixer` | Universal |
|
||||
| `trailing-whitespace` | Universal |
|
||||
| `check-merge-conflict` | Universal |
|
||||
| `detect-private-key` | Universal |
|
||||
| `check-added-large-files` | Universal |
|
||||
| `check-case-conflict` | Universal |
|
||||
| `mixed-line-ending` | Universal |
|
||||
| `no-commit-to-branch` | Universal — defaults to blocking `main`+`master` with no args; add `args: [--branch, <name>]` only to protect additional branch names |
|
||||
| `check-ast` | Python (`.py`) |
|
||||
| `check-builtin-literals` | Python (`.py`) |
|
||||
| `check-json` | JSON (`.json`) |
|
||||
| `pretty-format-json` | JSON (`.json`) |
|
||||
| `check-yaml` | YAML (`.yaml`, `.yml`) — for Kubernetes/Helm with custom tags add `args: ['--unsafe']` and `exclude: ^helm/templates/` |
|
||||
| `check-toml` | TOML (`.toml`) |
|
||||
|
||||
Full repo URL: `https://github.com/pre-commit/pre-commit-hooks`. For Python formatting, check if `black`, `ruff`, or `isort` is already configured in `pyproject.toml` before recommending them.
|
||||
|
||||
## Other repos
|
||||
|
||||
| Hook ID | Repo | Rev | Notes |
|
||||
|---------|------|-----|-------|
|
||||
| `shellcheck` | `https://github.com/jumanjihouse/pre-commit-hooks` | `3.0.0` | **Unverified — not in research corpus, verify upstream before use.** Recommended args: `args: [--severity=warning]` |
|
||||
| `gitleaks` | `https://github.com/gitleaks/gitleaks` | `v8.30.1` | **Unverified — not in research corpus, verify upstream before use.** |
|
||||
| `conventional-pre-commit` | `https://github.com/compilerla/conventional-pre-commit` | `v2.4.0` | Stage `commit-msg`; also add `default_install_hook_types: [pre-commit, commit-msg]` to the top-level config if not already present |
|
||||
|
||||
## Meta-validation (add last, after all other repos)
|
||||
|
||||
```yaml
|
||||
- repo: meta
|
||||
hooks:
|
||||
- id: check-hooks-apply # catches hooks that match no files
|
||||
- id: check-useless-excludes # catches exclude patterns that match no files
|
||||
```
|
||||
|
||||
## Local hooks (repo: local)
|
||||
|
||||
Use for repo-specific scripts that don't belong in an external hook repo.
|
||||
|
||||
```yaml
|
||||
- repo: local
|
||||
hooks:
|
||||
- id: run-tests
|
||||
name: Run test suite
|
||||
entry: bash tests/run-tests.sh
|
||||
language: unsupported_script
|
||||
pass_filenames: false
|
||||
always_run: true
|
||||
stages: [pre-push]
|
||||
```
|
||||
|
||||
`language: system` and `language: script` are deprecated names for the first two below.
|
||||
New local hooks use `unsupported` and `unsupported_script`.
|
||||
|
||||
Language choices for local hooks:
|
||||
- `unsupported` — system PATH tool (pre-commit does not manage env)
|
||||
- `unsupported_script` — script at a repo-relative path
|
||||
- `fail` — always-fail guard; `entry` text becomes the error message
|
||||
- `python` — isolated venv; use `additional_dependencies` for pip packages
|
||||
- `node` — isolated node env; `additional_dependencies` are npm packages
|
||||
- `ruby` — isolated gem env; `additional_dependencies` are gems
|
||||
- `golang` — builds from source; `additional_dependencies` are Go module paths
|
||||
- `rust` — Cargo build
|
||||
- `docker` — Docker image built from `entry`; use when no other language fits
|
||||
- `docker_image` — pulls a pre-built Docker image by `entry`
|
||||
- `conda` — Conda environment; conda-native hooks
|
||||
- `coursier` — Coursier (Scala/JVM) environment; JVM hooks
|
||||
|
||||
## Rev pin freshness
|
||||
|
||||
The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since the "Rev staleness" check in `references/modify-config.md` treats these tables as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against these tables.
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- context7-pre-commit-com
|
||||
- pre-commit-com
|
||||
---
|
||||
|
||||
# Modifying an existing `.pre-commit-config.yaml`
|
||||
|
||||
Reached from `SKILL.md`'s Route table when the repo already has a config. Self-contained — the
|
||||
create flow's file is not needed here. `SKILL.md`'s three common gates still apply.
|
||||
|
||||
Read the existing `.pre-commit-config.yaml` before editing. Note any stale `rev` values (see
|
||||
**Rev staleness** below) but do not change them.
|
||||
|
||||
## Adding a hook
|
||||
|
||||
1. Run a shallow extension scan, so the addition is judged against the languages actually present:
|
||||
|
||||
```bash
|
||||
rtk git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn
|
||||
```
|
||||
|
||||
2. Read `references/hooks-by-language.md` for the correct repo URL, `rev` and recommended args
|
||||
before writing anything.
|
||||
|
||||
3. Check for duplicates. If the same hook ID, or an equivalent tool, is already configured, say so
|
||||
and stop rather than adding a second one.
|
||||
|
||||
4. To sanity-check a hook against the repo's real files before committing to it, smoke-test it:
|
||||
|
||||
```bash
|
||||
pre-commit try-repo <repo-url> <hook-id> --verbose
|
||||
```
|
||||
|
||||
Use a local path in place of the URL for a hook under development. This runs the hook without
|
||||
writing anything.
|
||||
|
||||
5. If the hook's source repo is already a block in the config, add the hook under that block.
|
||||
Otherwise append a new repo block.
|
||||
|
||||
6. State the proposed addition, wait for confirmation, write, and run `pre-commit validate-config`.
|
||||
On a non-zero exit, show the error, fix it, and re-validate.
|
||||
|
||||
## Removing a hook
|
||||
|
||||
1. Identify the hook entry and its parent repo block.
|
||||
|
||||
2. State what will be removed — the hook ID, and whether the parent repo block goes with it because
|
||||
it would be left with zero hooks. Wait for confirmation.
|
||||
|
||||
3. Remove the hook entry. If the repo block now has no hooks left, remove the whole block: an empty
|
||||
`hooks: []` fails `validate-config`.
|
||||
|
||||
4. Write, then run `pre-commit validate-config`. On a non-zero exit, **revert the edit**, show the
|
||||
error, and stop. A removal is not safely fixable in place the way a malformed new hook block is,
|
||||
so recovering the prior state beats patching forward.
|
||||
|
||||
## Configuring top-level keys
|
||||
|
||||
Only when the user explicitly asks. Valid keys: `fail_fast`, `default_stages`,
|
||||
`default_language_version`, `minimum_pre_commit_version`, `exclude`, `files`,
|
||||
`default_install_hook_types`.
|
||||
|
||||
State the proposed change and wait for confirmation before writing.
|
||||
|
||||
## Rev staleness
|
||||
|
||||
For each repo in the config that also appears in `references/hooks-by-language.md`, compare the
|
||||
two `rev` values. Flag a mismatch as potentially outdated and tell the user to run `pc-run` to
|
||||
autoupdate. Repos absent from the reference cannot be checked — skip them silently. Do not modify
|
||||
any `rev` yourself.
|
||||
|
||||
The reference table's own pins go stale between updates, so treat a mismatch as a prompt to check
|
||||
rather than proof of staleness. `pre-commit autoupdate`, via `pc-run`, is the authoritative answer
|
||||
to what the current `rev` actually is.
|
||||
@@ -1,33 +0,0 @@
|
||||
# Sources
|
||||
|
||||
## context7-pre-commit-com
|
||||
|
||||
- **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/create-config.md, references/modify-config.md, references/hooks-by-language.md
|
||||
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,configuration,cli-reference,hook-authoring}.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## pre-commit-com
|
||||
|
||||
- **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/create-config.md, references/modify-config.md, references/hooks-by-language.md
|
||||
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,configuration,cli-reference,hook-authoring}.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## context7-pre-commit-hooks
|
||||
|
||||
- **URL:** context7:/pre-commit/pre-commit-hooks
|
||||
- **Description:** Official pre-commit-hooks collection — all available hook IDs with options and examples
|
||||
- **Contributing files:** references/hooks-by-language.md
|
||||
- **Research doc:** plugins/git/docs/research/docs/pre-commit/hooks-reference.md § pre-commit-hooks (official collection)
|
||||
- **Status:** `extracted`
|
||||
|
||||
## pre-commit-hooks-github
|
||||
|
||||
- **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 (v6.0.0)
|
||||
- **Contributing files:** references/hooks-by-language.md
|
||||
- **Research doc:** plugins/git/docs/research/docs/pre-commit/hooks-reference.md § pre-commit-hooks (official collection), § Deprecated hooks
|
||||
- **Status:** `extracted`
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
name: pc-run
|
||||
description: >
|
||||
Use when the user wants to run pre-commit hooks, wire them into git, bump hook
|
||||
revs, maintain the cache, or diagnose why a hook fails or never fires. Not
|
||||
creating or editing the pre-commit config -> `pc-author`.
|
||||
|
||||
compatibility: Requires pre-commit installed and available on PATH.
|
||||
|
||||
metadata:
|
||||
version: "1.0.1"
|
||||
category: devtools
|
||||
source_keys:
|
||||
- context7-pre-commit-com
|
||||
- pre-commit-com
|
||||
|
||||
allowed-tools: Bash Read
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
- The `SKIP` env var takes exact hook `id` values, comma-separated with no spaces: `SKIP=check-yaml,gitleaks rtk git commit -m "msg"`. A space after a comma silently skips nothing instead of erroring.
|
||||
- Never bypass a failing hook with `git commit --no-verify` (or `-n`). Hooks are the automated QA gate, so a bypassed commit pushes the failure downstream where it costs more — diagnose it instead.
|
||||
- `- files were modified by this hook` is not a bug. A fixer hook rewrote a staged file, so the staged snapshot is stale and the commit is blocked on purpose. Re-stage and re-run the same commit: `rtk git add -u && rtk git commit`. Do NOT reach for `pre-commit install -f` here — it overwrites `.git/hooks/` and has nothing to do with re-staging.
|
||||
|
||||
## Gate — `pre-commit clean`
|
||||
|
||||
Confirm with the user before running `pre-commit clean`, on every path that reaches it — including when it turns up as the fix for a stale or broken environment. It wipes the whole cache at `~/.cache/pre-commit`, which is machine-wide and shared by every repo on the box, forcing every hook environment to be re-downloaded.
|
||||
|
||||
> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
|
||||
|
||||
`pre-commit gc` drops only unused environments and needs no confirmation — prefer it when the goal is just to reclaim disk.
|
||||
|
||||
## Route
|
||||
|
||||
Determine intent from the user's request, then execute the matching operation. Where the matching row names a `references/` file, read that one file and no other — each flow file is self-contained.
|
||||
|
||||
| User intent | 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` — read `references/install.md` |
|
||||
| "pre-create environments", "warm cache" | `pre-commit install-hooks` — builds every hook environment without running a hook |
|
||||
| "remove hooks", "uninstall", "tear down" | `pre-commit uninstall` — removes pre-commit from `.git/hooks/` |
|
||||
| "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` — read `references/autoupdate.md` |
|
||||
| "gc", "garbage collect" | `pre-commit gc` — drops unused cached environments only, safe at any time |
|
||||
| "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — read `references/clean.md` |
|
||||
| "hooks aren't running", "hook never fires", "why did a hook fail", a hook failure whose cause is unclear | Diagnose — read `references/failure-patterns.md` |
|
||||
|
||||
If the intent is ambiguous, default to `pre-commit run --all-files` — do not stop to ask, and do
|
||||
not fall through to a narrower row on a guess.
|
||||
|
||||
## Run
|
||||
|
||||
Default to `pre-commit run --all-files`; never silently narrow to staged files. Run `pre-commit run` (staged only) or `pre-commit run <hook-id>` (one named hook) when the user asks for it.
|
||||
|
||||
When hooks fail:
|
||||
|
||||
1. Name the hook and the specific cause. Be concrete — "gitleaks blocked `config.json` (high-entropy string on line 12)", not "gitleaks failed".
|
||||
2. Suggest one concrete next step. Common causes and their concrete fixes are in `references/failure-patterns.md` — read it whenever the output does not already name the fix.
|
||||
3. Do not auto-fix code files, and do not edit `.pre-commit-config.yaml` — those belong to the user or to `pc-author`.
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- context7-pre-commit-com
|
||||
- pre-commit-com
|
||||
---
|
||||
|
||||
# Bumping hook revs with `autoupdate`
|
||||
|
||||
Reached from `SKILL.md`'s Route table when the user asks to update hook versions or bump revs. Self-contained.
|
||||
|
||||
```bash
|
||||
pre-commit autoupdate
|
||||
```
|
||||
|
||||
This rewrites `.pre-commit-config.yaml` in place, so re-read the file afterwards and report which `rev` values changed. It is the one operation in this skill that writes that file, and the exception is deliberate: the rewrite is pre-commit's own, resolved against the hook repos, not a hand edit — which is why `pc-author` hands rev bumps here rather than making them itself.
|
||||
|
||||
Add `--freeze` when the user wants exact SHAs pinned for reproducibility.
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- context7-pre-commit-com
|
||||
- pre-commit-com
|
||||
---
|
||||
|
||||
# Wiping the pre-commit cache
|
||||
|
||||
Reached from `SKILL.md`'s Route table when the user asks to clean the cache or rebuild environments from scratch. The confirmation gate on `pre-commit clean` stays in `SKILL.md`, because it must fire on every path that reaches this command, not only this one.
|
||||
|
||||
## Gate
|
||||
|
||||
`pre-commit clean` runs only after the confirmation gate in `SKILL.md` clears — that gate, its exact wording, and the `pre-commit gc` alternative live there and are not restated here.
|
||||
|
||||
```bash
|
||||
pre-commit clean
|
||||
```
|
||||
@@ -1,109 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- context7-pre-commit-com
|
||||
- pre-commit-com
|
||||
---
|
||||
|
||||
# Hook Failure Patterns
|
||||
|
||||
Common hook failure causes and concrete next-step suggestions.
|
||||
|
||||
## Hook modified files — commit blocked
|
||||
|
||||
Cause: A fixer hook (e.g. `trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json`) modified staged files. The commit is blocked because the staged version is now stale.
|
||||
|
||||
Fix: Re-stage and recommit.
|
||||
```bash
|
||||
rtk git add -u
|
||||
rtk git commit -m "same message"
|
||||
```
|
||||
|
||||
Do NOT reach for `pre-commit install -f` here. That flag overwrites existing hook files in `.git/hooks/`; it has nothing to do with re-staging.
|
||||
|
||||
## 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:
|
||||
- If it's a false positive: add a `# gitleaks:allow` inline comment, or add the path to `.gitleaksignore`.
|
||||
- If it's a real secret: remove it from the file, rotate the credential, then commit.
|
||||
|
||||
## 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.
|
||||
|
||||
## `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.
|
||||
|
||||
## `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.
|
||||
|
||||
Fix: The user (or `pc-author`) must add `args: [--autofix]` to the hook override in `.pre-commit-config.yaml`.
|
||||
|
||||
## Environment stale or broken
|
||||
|
||||
Cause: A hook's cached environment is corrupted or out of date.
|
||||
|
||||
Fix: `pre-commit clean` is gated. It wipes the machine-wide cache at `~/.cache/pre-commit`, shared by every repo on the box, so get explicit confirmation before running it — "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
|
||||
|
||||
```bash
|
||||
pre-commit clean # gated — confirm with the user first
|
||||
pre-commit install-hooks # rebuild everything
|
||||
```
|
||||
|
||||
Or less destructively, needing no confirmation:
|
||||
```bash
|
||||
pre-commit gc # remove only unused environments
|
||||
```
|
||||
|
||||
## Hooks don't run on `git commit`
|
||||
|
||||
Cause: `pre-commit install` was never run in this clone.
|
||||
|
||||
Fix: `pre-commit install`. Git hooks are per-clone — they are not committed to the repo.
|
||||
|
||||
## Hook runs but matches wrong files (or no files)
|
||||
|
||||
Cause: The `files:` pattern uses `re.search()` not full-string match. A pattern that looks correct may match unexpectedly.
|
||||
|
||||
Diagnosis: `identify-cli <filename>` shows the type tags for a file. Verify `types:` filters against these.
|
||||
|
||||
## stages mismatch — hook never fires
|
||||
|
||||
Cause: Hook is defined for a stage (e.g. `pre-push`) but `pre-commit install` was not run with `-t pre-push`.
|
||||
|
||||
Fix:
|
||||
```bash
|
||||
pre-commit install -t pre-commit -t pre-push -t commit-msg
|
||||
```
|
||||
|
||||
Or add `default_install_hook_types` to `.pre-commit-config.yaml` and re-run `pre-commit install`.
|
||||
|
||||
## `validate-config` schema error
|
||||
|
||||
Common causes: missing `id` under a hook block, missing `rev` under a non-local repo block, a `repo: local` hook missing `language` or `entry`, or an indentation error (valid YAML but invalid pre-commit schema).
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
source_keys:
|
||||
- context7-pre-commit-com
|
||||
- pre-commit-com
|
||||
---
|
||||
|
||||
# Installing hooks into `.git/hooks/`
|
||||
|
||||
Reached from `SKILL.md`'s Route table when the user asks to install or set up hooks. Self-contained.
|
||||
|
||||
Only run this flow when the user explicitly asks for it. Installing rewrites their clone's `.git/hooks/`; it is never a side effect of another request.
|
||||
|
||||
## Gate — existing hook files
|
||||
|
||||
Check `ls .git/hooks/` first. With hook files already there, `pre-commit install` does not refuse — it silently enters migration mode and runs both. Only `-f` replaces them, and `pre-commit uninstall` cannot restore whatever `-f` overwrote.
|
||||
|
||||
So when hook files are present, put the choice to the user in these terms, including the irreversibility, and wait for an answer before passing `-f`:
|
||||
|
||||
> "Existing hook files found in `.git/hooks/`. Plain `pre-commit install` runs both; `-f` overwrites them permanently and `pre-commit uninstall` cannot restore them. Plain install, or overwrite?"
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
Re-run with `-t` flags when `default_install_hook_types` changed, or when hooks in a non-default stage never fire — a hook whose stage was never installed cannot run:
|
||||
|
||||
```bash
|
||||
pre-commit install -t pre-commit -t pre-push -t commit-msg
|
||||
```
|
||||
@@ -1,33 +0,0 @@
|
||||
# Sources
|
||||
|
||||
## context7-pre-commit-com
|
||||
|
||||
- **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/install.md, references/autoupdate.md, references/clean.md, references/failure-patterns.md
|
||||
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## pre-commit-com
|
||||
|
||||
- **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/install.md, references/autoupdate.md, references/clean.md, references/failure-patterns.md
|
||||
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## context7-pre-commit-hooks
|
||||
|
||||
- **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/git/docs/research/docs/pre-commit/hooks-reference.md § "pre-commit-hooks (official collection)"
|
||||
- **Status:** `extracted`
|
||||
|
||||
## pre-commit-hooks-github
|
||||
|
||||
- **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/git/docs/research/docs/pre-commit/hooks-reference.md § "pre-commit-hooks (official collection)"
|
||||
- **Status:** `extracted`
|
||||
Reference in New Issue
Block a user