| name | git-branch |
| description | Create repository-compliant branches with efficient issue naming, base selection, and safety checks. |
git-branch
Create a development branch with the fewest checks needed to avoid wrong names, wrong bases, or overwrites.
Naming
- Issue-backed:
<type>/<short-desc>-<issueID>.
- Non-issue:
<type>/<user-provided-name>; never invent an issue ID.
- Types:
feat, fix, refactor, docs, test, perf, chore.
- Preserve a valid user type; otherwise infer from the task, defaulting to
chore.
- Normalize to short lowercase English words separated by
-; remove punctuation, filler words, repeated separators, and non-branch characters.
If the user gives an issue reference, run one gh call:
gh issue view <issueID> --json title,body,number
Use the title for short-desc; fall back to body or user context only when needed. If no issue is mentioned, do not call gh. If gh fails but context is enough, continue and report that issue metadata was not verified.
Validate:
git check-ref-format --branch <branch-name>
Efficient Checks
Prefer one shell call for local checks:
git status --short
git branch --show-current
git branch --list <branch-name>
Add remote/freshness checks only when they affect the result:
git branch --remotes --list '*/<branch-name>'
git fetch origin <base>
git rev-list --left-right --count <base>...origin/<base>
Base policy:
- Default
<base> to main unless repo guidance or the user names another base.
- Same-repo work prefers
origin/<base> over upstream/<base>.
- Use
upstream only for fork workflows or explicit guidance.
- Do not make the new branch track the base;
git-push sets upstream later.
Stop only when the target branch exists, dirty worktree intent is ambiguous, the current/base branch is clearly unsafe, or freshness checks show the selected base is stale.
Create
Use one of:
git switch -c <branch-name> <base>
git switch --no-track -c <branch-name> origin/<base>
Then verify with:
git branch --show-current
Guardrails
- No overwrite, reset, stash, delete, or force operations unless explicitly asked.
- Do not switch to an existing branch without user intent.
- Do not create protected/shared base branches (
main, master, develop, release branches) unless explicitly asked.
- Report skipped freshness checks only when they could matter.
