Git Branch Naming Conventions: Patterns and a CI Check

Git branch naming conventions: a type/short-name pattern checked by a CI job

A branch name like fix/4-empty-password-crash is pushed, a pull request opens, and a CI check passes or fails on the name

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 feature and feature/login cannot both exist, and why case matters
  • A type/short-name pattern 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
  • type is 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 .lock ending
  • feature and feature/login cannot both exist
  • Use lowercase, because Foo and foo collided 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

Leave a Reply