
The git branch naming conventions I would use are a lowercase type/short-name pattern, such as fix/empty-password-crash, with an optional ticket number. Git enforces only a short list of hard rules. Everything else is a team agreement, so the useful part is checking that agreement automatically.
I tested the rules on Git 2.56.0 and gh 2.103.3, including a CI check that passed and failed on real pull requests. GitHub’s own flow guide only asks for a short, descriptive name, with examples like increase-test-timeout, so a prefix is my recommendation, not a GitHub rule. For the full flow around these branches, see GitHub flow step by step, and for how branch models differ, see our Git workflows comparison.
In this guide:
- Which names Git itself rejects
- Why
featureandfeature/logincannot both exist, and why case matters- A
type/short-namepattern to adopt- A CI check that enforces the pattern on pull requests
Which Git Branch Naming Conventions Does Git Itself Enforce?
The rules come from git check-ref-format. I ran each name through git check-ref-format --branch.
| Branch name | Result |
|---|---|
feature/login |
OK |
fix/ABC-123-null-pointer |
OK |
Feature/Login |
OK (uppercase is allowed) |
fix login |
Rejected: space |
feat..x |
Rejected: two dots |
feat~1, feat^, feat:x |
Rejected |
feat?, feat*, feat[1] |
Rejected |
feat\x |
Rejected: backslash |
-feat |
Rejected: leading dash |
feat.lock |
Rejected: ends in .lock |
feat/, /feat, feat//x |
Rejected: bad slashes |
feat. and .feat |
Rejected: dot at the end or start |
feat@{x} |
Rejected: contains @{ |
git switch -c -bad fails with '-bad' is not a valid branch name, even when written as ./-bad. Characters like $, ;, &, |, " and backticks all passed the check. Keep that in mind for the CI section.
Why Can’t feature and feature/login Both Exist?
Git stores each branch as a file under .git/refs/heads/, so a branch named feature is a file and feature/login needs feature to be a directory. I hit the clash in both directions:
git branch feature
git branch feature/login
# fatal: cannot lock ref 'refs/heads/feature/login': 'refs/heads/feature' exists
git branch hotfix/a
git branch hotfix
# fatal: cannot lock ref 'refs/heads/hotfix': 'refs/heads/hotfix/a' exists
This is the strongest argument for a prefix scheme. If every branch is type/name, no branch is ever a bare feature or hotfix, and the clash cannot happen.
Does Case Matter in Branch Names?
On my Mac, yes, in a way that surprised me. The file system is APFS, and creating Foo and then foo failed:
git branch Foo
git branch foo
# fatal: a branch named 'foo' already exists
So two people on different systems could create Foo and foo and break when they meet. Use lowercase only. I did not test Linux or Windows, so I will not say how they behave.
How Long Can a Branch Name Be?
Git has no limit of its own that I hit. A 250-character name worked, and a 300-character one failed with File name too long, because each name becomes a file and .lock is appended while it is written. The limit comes from the file system, so treat it as a ceiling, not a target. Names over 40 characters are already hard to read in git branch output.
Which Git Branch Naming Conventions Should You Use?
I would pick this one:
type/short-description
type/123-short-description
typeis a short fixed list:feat,fix,docs,chore.- The description is lowercase words joined by hyphens.
- The ticket number, if you have one, comes first in the description.
Examples that pass: feat/dark-mode, fix/4-empty-password-crash, docs/readme-install-steps. The pattern gives you a fixed prefix to filter on (git branch --list 'fix/*'), and it avoids the clash above.
Git does not enforce any of it. Rename a branch you already created with git branch -m old-name new-name, which I ran locally. I did not test renaming a branch that is already pushed.
How Do You Name a Git Branch From an Issue?
The gh CLI can create a branch linked to an issue. With issue #4, “Login page crashes on empty password”:
gh issue develop 4
# created origin/4-login-page-crashes-on-empty-password
gh issue develop 4 -n fix/4-empty-password-crash
gh issue develop --list 4
The default name is the issue number plus a hyphenated copy of the title. That is long, so the -n flag is worth using to fit your pattern. Both branches showed up in gh issue develop --list 4.
Can You Enforce Git Branch Naming Conventions With CI?
Yes. This workflow fails a pull request when the branch name does not match the pattern:
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"
I merged it into my test repo and opened two pull requests. The PR from chore/add-branch-check passed. The PR from Fix_Login-Bug failed, and the log showed the “must look like” message.
Note that the branch name goes through env: and not straight into the script. Because Git allows $, ; and backticks in names, putting ${{ github.head_ref }} directly inside run: would let a crafted branch name run shell commands. With env:, the shell treats it as text.
A failing check only blocks merging if you make it required (see CODEOWNERS and permissions for the related review rules). I did not test that, since required status checks were outside this run.
What I Did Not Test
I used one Mac (APFS) and one test repository. I did not test Linux or Windows behavior, GitHub rulesets that restrict branch names, required status checks, renaming a pushed branch, or Jira and Linear ticket linking. GitHub’s rulesets docs page I read mentions restricting who can create branches matching a pattern, but it did not describe naming rules, so I will not claim them.
Frequently Asked Questions
Q: What are the best git branch naming conventions?
A: Lowercase type/short-description with hyphens, a short fixed list of types, and an optional ticket number. It avoids the feature vs feature/x clash and is easy to filter.
Q: Can a Git branch name contain a slash?
A: Yes. Slashes group branches like directories. A branch name cannot start or end with one, and it cannot contain two in a row.
Q: Should branch names be uppercase or lowercase?
A: Lowercase. Git allows uppercase, but on my APFS Mac Foo and foo collided.
Q: Should I put the ticket number in the branch name?
A: If you use tickets, yes, near the start: fix/4-empty-password-crash. gh issue develop puts the issue number first by default.
Quick Summary:
- Git forbids spaces,
..,~ ^ : ? * [, backslashes, a leading dash, and a.lockending featureandfeature/logincannot both exist- Use lowercase, because
Fooandfoocollided on APFS - Use
type/short-description, optionally with a ticket number - Enforce it with a CI check, and pass the branch name through
env:
Good git branch naming conventions are only worth having if a check enforces them, so add the workflow before you add the rule to a wiki.
Related guides
- Comparing a Feature Branch with Master in Git
- Setting Up GitLab CI/CD for Different Branches
- Running Specific Steps on the release- Branch with GitHub Actions
- Git vs Github for beginners
- Git Workflows: Git Flow vs GitHub Flow vs Trunk-Based Dev
- Getting Started with GitHub Actions: Your First CI/CD Pipeline