Why can't branch names contain certain characters?

Git stores branches as file paths in .git/refs/. Characters disallowed in the OS file system (colons, asterisks, spaces, backslashes) are invalid. Additionally, Git reserves some patterns (like '..') for its own ref notation.

What is the Conventional Commits standard for branches?

There is no official Conventional Commits standard for branch names — only for commit messages. Common conventions include type/description (feat/user-auth) or type/ticket-desc (feat/PROJ-123-user-auth).

Does branch name length matter?

Git has no enforced limit, but very long names (~200+ chars) can cause issues on Windows due to MAX_PATH limitations. GitHub and GitLab display truncated names in the UI beyond ~50 characters, so keep branch names concise and descriptive.

Branch Naming Validator | DevTools Surf

DevTools Surf

Example: Branch Naming Validator

A worked example, rendered from real sample data. Sign in to run the tool on your own input.

Input

feature/user-auth
Feature/UserAuth
fix/login_bug
main
hotfix/urgent fix

Output

═══ Summary ═══
Branches checked: 5
Convention: conventional (type/kebab-description)
Pattern: ^(?:feat|fix|chore|docs|refactor|test|perf|build|ci|style|revert|hotfix|release|feature|bugfix)/[a-z0-9]+(?:-[a-z0-9]+)*$
Max length: 60
✗ 2 of 5 pass — 3 need renaming
ℹ Names are checked against git's own ref rules and the convention you picked. Nothing is read from a remote.

═══ Results ═══
✓ feature/user-auth
✗ Feature/UserAuth
• does not match the conventional (type/kebab-description) pattern
• contains uppercase letters — case-insensitive filesystems can collide on these
Suggested: feat/user-auth
✗ fix/login_bug
• does not match the conventional (type/kebab-description) pattern
• uses underscores; hyphens are the usual separator
Suggested: fix/login-bug
✓ main (protected branch, convention not enforced)
✗ hotfix/urgent fix
• git refuses this name: it contains a character git forbids in a ref: space ~ ^ : ? * [ \
• does not match the conventional (type/kebab-description) pattern
Suggested: hotfix/urgent-fix

═══ Rules applied ═══
• Must match: ^(?:feat|fix|chore|docs|refactor|test|perf|build|ci|style|revert|hotfix|release|feature|bugfix)/[a-z0-9]+(?:-[a-z0-9]+)*$
• Must satisfy git check-ref-format: no space ~ ^ : ? * [ \, no "..", no "@{", no trailing ".lock"
• At most 60 characters
• Lowercase with hyphens, so case-insensitive filesystems cannot collide
• Exempt: main, master, develop, dev, staging, production, release

═══ CI check you can commit ═══
  name: Branch name
  on:
    pull_request:
      types: [opened, edited, reopened, synchronize]
  jobs:
    check:
      r
…

About Branch Naming Validator

Branch Naming Validator preview - DevOps / CI-CD tool

Validate branch names against naming conventions and patterns with suggestions. Part of the DevTools Surf developer suite. Browse more tools in the DevOps / CI-CD collection.

Use Cases

Enforce naming conventions in CI pre-push hooks
Validate branch names against Jira ticket format before PR creation
Audit existing branch names for legacy naming inconsistencies
Onboard engineers to the team's branching convention interactively

Tips

Select your team's convention (Conventional Commits, Jira prefix, GitHub Flow) to get context-specific validation rules
The validator flags characters that cause issues on case-insensitive file systems (macOS HFS+) — useful for cross-platform teams
Use the bulk input mode to validate a list of branch names from a CI script or pre-commit hook

Fun Facts

Git branch names are stored as file paths in .git/refs/heads/. Characters invalid in file names on any major OS — including colons, asterisks, and backslashes — are also invalid in branch names for this reason.
The 'feature/', 'bugfix/', 'hotfix/', 'release/' prefix convention was popularized by Vincent Driessen's 'A Successful Git Branching Model' (git-flow) published in 2010. It became one of the most-starred Git articles ever written.
Git enforces 41 distinct naming rules for references, including restrictions on double dots, question marks, control characters, and names ending in .lock. Many of these rules exist to avoid confusion with Git's own internal reference naming.

FAQ

Why can't branch names contain certain characters?: Git stores branches as file paths in .git/refs/. Characters disallowed in the OS file system (colons, asterisks, spaces, backslashes) are invalid. Additionally, Git reserves some patterns (like '..') for its own ref notation.
What is the Conventional Commits standard for branches?: There is no official Conventional Commits standard for branch names — only for commit messages. Common conventions include type/description (feat/user-auth) or type/ticket-desc (feat/PROJ-123-user-auth).
Does branch name length matter?: Git has no enforced limit, but very long names (~200+ chars) can cause issues on Windows due to MAX_PATH limitations. GitHub and GitLab display truncated names in the UI beyond ~50 characters, so keep branch names concise and descriptive.

Related DevOps / CI-CD Tools

CI/CD Pipeline Builder GitHub Actions Generator GitLab CI Generator Jenkins Pipeline Simulator CircleCI Config Builder Travis CI Simulator Coverage Report Analyzer Dependency Checker