williamlimasilva/conventional-branch

Conventional Branch

Create Git branches that follow the Conventional Branch specification — a simple, consistent convention for naming Git branches.

Branch Name Format

<type>/<description>

Branch Types

| Type | Alias | Purpose | |------|-------|---------| | feature/ | feat/ | New features or enhancements | | bugfix/ | fix/ | Bug fixes | | hotfix/ | — | Urgent production fixes | | release/ | — | Release preparation (dots allowed in version: release/v1.2.0) | | chore/ | — | Non-code tasks (deps, docs, config) |

Trunk Branches

main, master, and develop are trunk branches — they do not use a prefix. Never create new branches with the same names as trunk branches; branch off them instead.

Naming Rules

• Lowercase only — no uppercase letters anywhere
• Alphanumerics, hyphens, and dots — a-z, 0-9, -, .
• Dots allowed only in release/ version descriptions (e.g., release/v1.2.0)
• No underscores, spaces, or special characters
• No consecutive hyphens (--), dots (..), or hyphen-dot adjacency (-. or .-)
• No leading or trailing hyphens or dots in the description

Valid Examples

main
master
develop
feature/add-login-page
feat/add-login-page
bugfix/fix-header-bug
fix/header-bug
hotfix/security-patch
release/v1.2.0
chore/update-dependencies
feature/issue-123-new-login

Invalid Examples

| Branch | Problem | |--------|---------| | Feature/Add-Login | Uppercase letters | | feature/new--login | Consecutive hyphens | | feature/-new-login | Leading hyphen | | feature/new-login- | Trailing hyphen | | release/v1.-2.0 | Hyphen adjacent to dot | | fix/header bug | Space | | fix/header_bug | Underscore | | unknown/some-task | Unknown prefix type |

Description Guidelines

• Use kebab-case with 2-5 words
• Be descriptive but concise (~50 chars total)
• Good: add-oauth-login, fix-header-overflow, update-ci-config
• Bad: fix-bug, new-feature

Workflow

Follow these steps:

Step 1 — Determine Branch Type

Ask the user (if not already clear):

• Branch type — default to feature when uncertain
• Brief description — what the branch is for

If the user mentions a ticket or issue number, include it in the description (e.g., feature/issue-123-add-oauth).

Step 2 — Validate the Name

Check the assembled name against the Naming Rules above. If any rule fails, fix it:

• Lowercase everything
• Replace underscores and spaces with hyphens
• Collapse consecutive hyphens
• Strip leading/trailing hyphens

Step 3 — Detect the Base Branch

Different repos use different trunk branches. Detect which one this repo uses:

# Prefer the remote's default branch
git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'

If that returns nothing, check which trunk branch exists locally (priority order: develop, main, master):

for b in develop main master; do
  git show-ref --verify --quiet "refs/heads/$b" && echo "$b" && break
done

Step 4 — Create and Checkout

git checkout <base>
git pull origin <base>
git checkout -b <type>/<description>

Step 5 — Confirm

Tell the user:

• The branch name that was created
• That they are now on the new branch
• Remind them: git push -u origin <branch-name> when ready

Relationship with Conventional Commits

Conventional Branch complements Conventional Commits:

| Conventional Branch | Typical Conventional Commit | |---------------------|----------------------------| | feature/add-login | feat: add login page | | bugfix/fix-header | fix: header overflow on mobile | | chore/update-deps | chore: bump lodash to 5.0 | | release/v1.2.0 | chore: release v1.2.0 |

Align the branch type with commit types where possible (e.g., feature/* branches with feat: commits).