Conventional Branch

Conventional branch

Creates or validates Git branch names that follow the Conventional Branch format, detects the repository base branch, checks out the base, and creates the new branch when requested.

When to invoke

• "Create a conventional branch for this task."
• "Name a branch for this bug fix."
• "Check whether this branch name follows the spec."
• "Create feature/issue-123-add-oauth from the default branch."
• "What branch type should I use?"

Branch format

<type>/<description>

main, master, and develop are trunk branches. Do not create new branches with those names; branch off them instead.

Naming rules

• Lowercase only; no uppercase letters.
• Use alphanumerics, hyphens, and dots: a-z, 0-9, -, ..
• Allow dots only in release/ version descriptions.
• Do not use underscores, spaces, or special characters.
• Do not use consecutive hyphens --, consecutive dots .., or hyphen-dot adjacency -. or .-.
• Do not start or end the description with a hyphen or dot.
• Prefer kebab-case with 2-5 words and about 50 characters total.

Procedure

1. Determine branch type from the task; default to feature when uncertain.
2. Build the description from the task and include ticket or issue numbers, such as feature/issue-123-add-oauth, when supplied.
3. Normalize the name: lowercase, replace underscores and spaces with hyphens, collapse repeated hyphens, strip leading/trailing hyphens and dots.
4. Validate against the naming rules.
5. Detect the base branch using the remote default, then local trunks in priority order develop, main, master.
6. If asked to create the branch, check out and update the base, then create the branch.

git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'
for b in develop main master; do
  git show-ref --verify --quiet "refs/heads/$b" && echo "$b" && break
done
git checkout <base>
git pull origin <base>
git checkout -b <type>/<description>
git push -u origin <branch-name>

Only run git push -u origin <branch-name> when the user asks to push or publish.

Examples

Related primitives

Branch and commit alignment examples

Use feature/* with feat: commits where possible. Good descriptions include fix-header, fix-header-overflow, and update-ci-config; weak descriptions include fix-bug and new-feature.

Output template

### Conventional branch result

**Status:** created | name only | invalid | blocked
**Base branch:** `<base>`
**Branch name:** `<type>/<description>`

**Validation**
- Type: pass | fail
- Description format: pass | fail
- Trunk handling: pass | fail

**Commands run**
- `git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'`
- `git checkout <base>`
- `git pull origin <base>`
- `git checkout -b <type>/<description>`

**Next step:** `git push -u origin <branch-name>` when ready.

Quality gate

• Branch name follows <type>/<description> or is an existing trunk branch.
• Type is feature, feat, bugfix, fix, hotfix, release, or chore.
• Description is lowercase kebab-case with no invalid dot or hyphen sequences.
• Dots appear only for release/ versions.
• The base branch was detected before creating a branch.
• Push was not run unless requested.

References

• Conventional Branch
• Conventional Commits