---

name: create-branch description: Create a git branch following Sentry naming conventions. Use when asked to "create a branch", "new branch", "start a branch", "make a branch", "switch to a new branch", or when starting new work on the default branch. argument-hint: '[optional description of the work]'

Create Branch

Create a git branch following Sentry naming conventions. Keep this workflow non-interactive unless the user explicitly asks to choose the name manually.

Workflow

1. Resolve the work description:

   • If $ARGUMENTS is present, use it
   • Otherwise inspect:

     git diff
     git diff --cached
     git status --short
     

   • If there are local changes, derive a short description from the diff
   • If there are no local changes, use a generic description like repo-maintenance, tooling-update, or work-in-progress

2. Classify the branch type:

Type	Use when
feat	New functionality
fix	Broken behavior now works
ref	Behavior stays the same, structure changes
chore	Maintenance of existing tooling/config
perf	Same behavior, faster
style	Visual or formatting only
docs	Documentation only
test	Tests only
ci	CI/CD config
build	Build system
meta	Repo metadata
license	License changes

When unsure: use feat for new things, ref for restructuring, chore for maintenance.

3. Generate <type>/<short-description>. Keep <short-description> kebab-case, ASCII-only, and ideally 3 to 6 words.

4. Choose the base without prompting:

   git branch --show-current
   git remote | grep -qx origin && echo origin || git remote | head -1
   git symbolic-ref refs/remotes/<remote>/HEAD 2>/dev/null | sed 's|refs/remotes/<remote>/||' | tr -d '[:space:]'
   

   • If default branch detection fails, fall back to main, then master, then the current branch
   • If on a detached HEAD, branch from the current commit
   • If already on a non-default branch, branch from the current branch
   • Only switch to the default branch when the user explicitly asks

5. Avoid collisions by appending -2, -3, and so on until the name is unused locally and remotely.

6. Create the branch:

   git checkout -b <branch-name>
   

   Report the final branch name, but do not stop for confirmation.

References

• Sentry Branch Naming