Defame1297
20e5627fd7
Three statements were false against the git in use (2.39.5), each verified by
running it.
`git rebase --autosquash HEAD~N` without `-i` is a silent no-op: git prints
"Successfully rebased", the `fixup!` commit survives with the same SHA, and
rewrite-history.md presented that as the preferred flow with `-i` as an optional
review step. The agent reports the squash as done and the `fixup!` subject then
trips this repo's own commit-msg gate. `-i` is now the command, not the alternative.
"Fetch never modifies a local branch, so it is always safe to run" — new text on
this branch — is false: `git fetch origin main:probe` fast-forwarded the local
branch, and a `+` prefix force-updates it, losing commits. The claim is scoped to
the no-refspec form.
`git worktree add --orphan` does not exist before Git 2.42; on 2.39.5 it is
`error: unknown option 'orphan'`, exit 129. The same file gives a version floor for
`--recurse-submodules` three sections earlier. Floor added, with a fallback that
was tested before being documented.
git-workflow claimed "every request resolves to exactly one of these six" while
rebase, reset and stash were owned by no skill — `git reset` appeared nowhere in
the plugin, old tree or new — so "undo my last commit" routed nowhere. The claim is
gone, the router gains rows for all three, and the procedures now exist: plain
rebase with `--onto` and conflict handling, a reset mode table gated on `--hard`,
and stash save/pop/list/drop. `--hard` gets an always-loaded Gotcha, matching the
register the force-push refusal already sets.
Cherry-pick had three claimants pointing at git-history while git-commits owned the
flow, and the two copies were not equivalent — git-history's lacked the destination
check, the rtk prefix and `--abort`. Resolved to git-commits per #112; the weaker
duplicate is replaced by a hand-off.
git-commits' metadata.version was deleted rather than bumped in 14af50b, leaving two
house-contract documents citing a worked v0.1.2 to v0.1.3 transition against a file
declaring no version. Restored to 0.1.3.
Also: the divergent-pull explanation stated a `--ff-only` default that does not
exist (it is a hard error); `--remote` "requires" a configured branch where it uses
one; `git push origin --delete` moved to git-remotes, which owns the remote-side
gates; seven retired `git:<name>` source slugs; git-orchestrate quoted a
git-workflow sentence that no longer exists; git-submodules regains the indirect
trigger that made "add a dependency repo" routable; and commit atomicity is a common
gate rather than reachable only from the create flow.
Refs: #112, #113
3.8 KiB
name, description, metadata
| name | description | metadata | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| git-branches | 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`. |
|
Gotchas
- Uncommitted changes abort a switch.
git switchrefuses 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>andgit tag --list <name>; output from both means the name is ambiguous. Prefergit switchovergit checkout, and where a command accepts either ref, disambiguate withrefs/heads/<name>orrefs/tags/<name>. mainandmasterare a refusal, not a gate. Force-pushing, force-deleting, or renaming them is rejected even when the caller passesconfirm: true— no flag makes the remote's history recoverable. Offer a new branch instead.
Step 1 — Determine the branching pattern
Read branching_pattern from the git plugin config (.claude/plugins/git/config.json; the plugin root's config.example.json shows the shape). Default: github-flow. With no config, infer Gitflow from the presence of a develop or release/* branch, and GitHub Flow otherwise.
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 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.
{
"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.