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

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`.	version category source_keys 1.0.1 git 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 — ADR-0023) 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 and master are a refusal, not a gate. Force-pushing, force-deleting, or renaming them is rejected even when the caller passes confirm: 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 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.

{
  "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.