--- name: git-branches description: > Use when managing the full lifecycle of git branches: create feature/hotfix/release branches (gitflow, GitHub Flow, or custom patterns from config), switch, delete, rename, and track branches, or retrieve branch intent metadata. Handles branch protection safety checks and returns structured results for agent composition. Use even if the user doesn't explicitly mention branch names — they may be asking about "fixing something" or "shipping a feature", which implicitly requires branch management. Do not use when the user needs only commit operations (use git-commits) or history inspection (use git-history). metadata: category: git source_keys: - context7-git-htmldocs - nvie-gitflow-post - atlassian-gitflow-tutorial - gitflow-cheatsheet --- ## Gotchas - **Branches are cheap; deletion is cheap but risky.** Deleting one requires checking if commits on it are reachable elsewhere; always confirm before deleting, as it may lose unmerged work. - **Uncommitted changes can block branch switches.** `git switch` aborts if local modifications conflict with the target branch. Offer to stash changes before switching when this happens, don't force a checkout. - **Tracking relationships matter for coordination.** Agents pushing on behalf of users should always set tracking (`-u origin `) so later pushes/pulls know the target. Without it, commands fail or target the wrong remote branch. - **Gitflow vs. GitHub Flow are not compatible.** Gitflow requires `develop` and `release/*` branches with `--no-ff` merges; GitHub Flow uses only `main` and feature branches with fast-forward. Read the repo's config or ask the orchestrator which pattern to use — don't guess. - **Naming collisions with tags.** A branch and tag can have the same name. Prefer `git switch` over `git checkout` for branch operations — verify which ref you're targeting with `git branch --list ` / `git tag --list ` if the name could be ambiguous, and disambiguate explicitly with `refs/heads/` (branch) or `refs/tags/` (tag) where a command accepts either. - **Never force-push `main` or `master`.** This is a hard refusal, not a confirmation gate — it applies even if the caller passes `confirm: true`. Deleting or renaming `main`/`master` in a way that would require a force-push to reconcile the remote (e.g. force-deleting and recreating it, or renaming it out from under in-flight work) must be rejected outright; explain why and suggest a non-destructive alternative (e.g. a new branch) instead of proceeding. ## Branch Patterns Default to **GitHub Flow** (simpler, modern, CI/CD-friendly). Fall back to **Gitflow** only if the repo's config specifies it or the branch structure shows it in use (presence of `develop` or release branches). **GitHub Flow:** - Base: `main` - Feature branches: `feature/` or `fix/` - Merge: fast-forward when possible (preserves linear history) - Delete after merge **Gitflow:** - Base: `main` (production) + `develop` (integration) - Feature branches: `feature/` (from `develop`) - Release branches: `release/X.Y.Z` (from `develop`, merged to `main` + `develop`) - Hotfix branches: `hotfix/X.Y.Z` (from `main`, merged to `main` + `develop`) - Merge: always use `--no-ff` to preserve branch structure ## Workflow - [ ] **Determine pattern:** Check git plugin config (`.claude/plugins/git/config.json`, if present — see `config.example.json` in the plugin root for the expected shape) for `branching_pattern` (default: `github-flow`). If not set, inspect repo for `develop` branch or `release/*` branches; if present, assume Gitflow. - [ ] **Create branch:** Use `git switch -c `. Base defaults to config's `base_branch` (usually `main` or `develop`). Include intent metadata in branch name or return as structured result (e.g., `{ "branch": "feature/x", "intent": "implement feature X" }`). - [ ] **Track remote:** If pushing, always use `git push -u origin ` to establish tracking. - [ ] **Safety checks before destructive ops:** Before delete/force-push/rebase with history loss, check: (1) Is this branch tracking a remote? Warn if yes. (2) Are there unpushed commits? Warn if yes. (3) Does the orchestrator call include `confirm: true`? Fail if not. For humans, prompt interactively. - [ ] **Return structured results:** Always return branch operations as JSON or structured text: `{ "action": "create", "branch": "feature/x", "base": "main", "tracking": "origin/feature/x", "intent": "implement feature X" }`. Agents need to parse this for subsequent operations. - [ ] **Retrieve intent (`get-intent`):** Git has no native field for free-text branch metadata — this skill doesn't persist it. On `create`, the `intent` value is only ever returned in the structured result; the caller (orchestrator or agent) is responsible for storing it if it needs to be looked up later. On `get-intent`, either parse it back out of the branch name convention (`feature/`) or return `{ "intent": null }` if the caller never persisted the original create-time value — don't fabricate an intent. ### Command mapping for each action - **delete:** `git branch -d ` refuses if the branch has unmerged commits — prefer this by default. `git branch -D ` forces deletion and discards unmerged work; only use it after the safety checks above pass and `confirm: true` is set. For a remote branch: `git push origin --delete `. - **rename:** `git branch -m `. - **list:** `git branch` (local only), `git branch -a` (all local + remote-tracking), `git branch -r` (remote-tracking only), `git branch --merged`/`--no-merged` (filter by merge status into current branch). - **get-intent:** No git command — see Workflow step "Retrieve intent" for how this is resolved. - **track (existing branch):** `git branch --set-upstream-to=origin/` sets tracking without a push; `git branch -vv` shows tracking state for all local branches. - **switch (existing branch):** `git switch ` — switches to an existing local branch (aborts on conflicting local changes, see Gotchas). `git switch -` switches back to the previously checked-out branch. ## Merging Scope: fast-forward/merge-commit mechanics and conflict resolution only. Rebase, cherry-pick, and revert belong to `git-history`. - **Fast-forward:** `git merge ` — advances the pointer with no merge commit if the target hasn't diverged. - **True merge:** `git merge --no-ff ` — forces a merge commit even when fast-forward is possible; required by Gitflow on all supporting-branch merges. - **Squash merge:** `git merge --squash ` stages the combined diff without committing; follow with a manual `git commit`. - **Octopus merge:** `git merge branch-a branch-b branch-c` merges more than two branches at once; fails outright on any conflict, so use sequential two-way merges if conflicts are expected. **Conflict resolution:** when Git can't auto-merge, it inserts conflict markers and stops. Run `git status` to find conflicted files, edit them to resolve the markers, then `git add ` and `git merge --continue`. `git merge --abort` reverts to the pre-merge state. `git mergetool` opens the configured merge tool; `git diff --diff-filter=U` shows only conflicted files. ## Comparing Branches - `git log main..feature` — commits in `feature` not in `main`. - `git log feature..main` — commits in `main` not in `feature` (reverse direction). - `git log --left-right main...feature` — both diverging sets (symmetric diff). - `git diff main...feature` — diff from the common ancestor to `feature`'s tip. - `git merge-base main feature` — print the common ancestor commit. ## Integration with Orchestrator When invoked by `git-orchestrate`, accept requests in the form: ```json { "action": "create|switch|delete|rename|track|list|get-intent", "branch": "", "base": "", "intent": "", "confirm": "" } ``` Return results as: ```json { "success": true, "action": "create|switch|...", "branch": "", "message": "descriptive message", "intent": "", "tracking": "origin/", "error": "", "suggestion": "" } ``` If error is due to uncommitted changes, include `{ "suggestion": "stash changes and retry" }` so the orchestrator can offer automatic recovery.