Originally published on DevToolHub.
The git branch naming conventions I would use are a lowercase type/short-description pattern, such as fix/empty-password-crash, with an optional ticket number. Git enforces only a short list of hard rules, so the useful part is checking the rest automatically.
I tested on Git 2.56.0 and gh 2.103.3, including a CI check that passed and failed on real pull requests.
What Git refuses
From git check-ref-format, confirmed with git check-ref-format --branch: spaces, .., ~ ^ :, ? * [, backslashes, a leading dash, a .lock ending, bad slashes, and @{. Uppercase is allowed, and so are $, ;, &, | and backticks.
Why feature and feature/login clash
Each branch is a file under .git/refs/heads/, so a branch cannot be both a file and a directory:
git branch feature git branch feature/login # fatal: cannot lock ref 'refs/heads/feature/login': 'refs/heads/feature' exists It fails in the other order too. A prefix scheme, where every name is type/name, avoids it.
Case
On my APFS Mac, creating Foo and then foo failed with a branch named 'foo' already exists. Use lowercase.
The pattern
type/short-description type/123-short-description type is feat, fix, docs or chore. gh issue develop 4 -n fix/4-empty-password-crash creates a branch linked to issue #4 with that name; the default name is 4-login-page-crashes-on-empty-password.
A CI check
name: branch-name on: pull_request: jobs: check: runs-on: ubuntu-latest steps: - name: Check branch name env: BRANCH: ${{ github.head_ref }} run: | if ! echo "$BRANCH" | grep -Eq '^(feat|fix|docs|chore)/[a-z0-9]+(-[a-z0-9]+)*$'; then echo "Branch '$BRANCH' must look like feat/short-name, fix/..., docs/... or chore/..." exit 1 fi echo "Branch name OK: $BRANCH" The PR from chore/add-branch-check passed and the one from Fix_Login-Bug failed. The name goes through env: because Git allows $ and ; in names, so inlining it in the script could run shell commands.
What I did not test
One Mac, one repo. Not tested: Linux or Windows, rulesets for branch names, required status checks, renaming a pushed branch, Jira or Linear linking.
Full write-up with the complete rules table and FAQ: Git Branch Naming Conventions.

