git check-ref-format

Is 'feature/$thing' a legal branch name? Ask this.

🎯 What & why

Validates whether a string is a legal Git ref name, by exactly the rules Git itself enforces. The honest answer to 'can I name a branch this?' without trial-and-error.

🧠 Mental model

A small filter: feed it a candidate name, get exit 0 if Git would accept it, non-zero otherwise. Refs must have at least one '/' (e.g. refs/heads/foo) unless --allow-onelevel; the rules ban '..', '~', '^', ':', '?', '*', '[', backslashes, leading/trailing dots, '@{', and more.

🛠️ Synopsis

git check-ref-format [--normalize] [--allow-onelevel] [--refspec-pattern] <refname>
git check-ref-format --branch <branchname-shorthand>
git check-ref-format --print <refname>

Returns exit 0 if the name is valid, non-zero otherwise. With --print
or --normalize, also writes a cleaned form to stdout. With --branch,
expands @{-N}, @{upstream}, etc., to the actual branch name.

🎚️ Switches & options

Flag	What it does
`--allow-onelevel`	Accept single-component names like 'foo' (no '/'). Without it, refs must look like 'refs/heads/foo' or at least 'heads/foo'.
`--refspec-pattern`	Allow exactly one '' as a wildcard component, for refspecs like 'refs/heads/'. Otherwise '*' is rejected.
`--normalize`	Strip leading slashes and collapse runs of '/'; print the cleaned name on stdout. Combine with --print's behavior implicitly.
`--print`	Print a normalized version of a valid ref; equivalent to --normalize for printing purposes.
`--branch <name>`	Expand a branch shorthand: '@{-1}' becomes the previously checked-out branch, '@{u}' the upstream, etc. Returns the resolved name on stdout.

💡 Use cases

Sanitize user input in a script before creating a branch or tag from it.
Resolve '@{-1}' to a real branch name in shell glue (no parsing of git checkout - output).
Validate refspec patterns generated by tooling before passing them to fetch/push.
Normalize a path-like ref string (strip stray slashes) before storing it.

🧪 Examples

Validate a branch shorthand

git check-ref-format --allow-onelevel feature/login || echo invalid

Resolve previous branch

prev=$(git check-ref-format --branch @{-1})

Normalize a sloppy name

git check-ref-format --normalize 'refs//heads///foo'

Allow refspec wildcard

git check-ref-format --refspec-pattern 'refs/heads/*'

🎓 Recommendations

Use --branch instead of parsing git rev-parse --abbrev-ref output when you want the @{-N} or @{u} forms — it's purpose-built and cheaper.
Pair --allow-onelevel with explicit prefixing in your script: validate the shorthand, then prepend 'refs/heads/' yourself.
Run candidate names through this before any 'git branch' or 'git tag' to give users a clean error instead of Git's terse rejection.

🪤 Common pitfalls

Without --allow-onelevel, plain names like 'main' or 'foo' fail — easy to forget when validating short branch names.
The rules ban a lot more than people expect: '@{', consecutive dots, trailing '.lock', and ASCII control characters all cause rejection.
--normalize doesn't lowercase or substitute characters; it only collapses slashes and strips leading ones. It won't rescue an otherwise-illegal name.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.