Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Plumbing Commands

git check-ref-format command

Reference for git check-ref-format: test whether a branch or tag name is valid, learn the naming rules, use --branch, --normalize and --allow-onelevel.

git check-ref-format checks whether a string is an acceptable reference name. It prints nothing for a valid name and exits with status 0; for an invalid one it exits with status 1. Scripts use it to validate user input before creating a branch or tag, so that the error appears early and with your own message.

Reference names follow strict rules because they become file names, appear on command lines and in URLs, and are embedded in revision syntax. The command knows all of them, so you do not have to reproduce them in your own code.

Terminal
git check-ref-format refs/heads/feature/login
git check-ref-format --branch feature/login

Try it

Bash Valid and invalid names

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Branch mode, normalising, and wildcards

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git check-ref-format [--normalize] [--[no-]allow-onelevel] [--refspec-pattern] <refname>
git check-ref-format --branch <branchname-shorthand>
Name Description
<refname> The full name to test, for example refs/heads/main.
--allow-onelevel Accept names without a slash (such as HEAD or v1). By default at least one / is required.
--refspec-pattern Accept a single * as a wildcard, as used in refspecs.
--normalize Clean the name (remove leading slashes and collapse repeated ones) and print it; fail if the result is invalid.
--branch <name> Check that refs/heads/<name> would be valid and print the name, expanding @{-N} to the previous branch name.

Returns: nothing for a valid name (the normalised or expanded name with --normalize and --branch).

Exit status: 0 for valid, 1 for invalid.

The naming rules

A name is invalid if any of these hold:

  • A component (the part between slashes) starts with a dot or ends with .lock.
  • It contains .. anywhere, or @{.
  • It contains ASCII control characters, space, ~, ^, :, ?, *, [ or backslash.
  • It begins or ends with /, contains //, or ends with a dot.
  • The whole name is just @.
  • With --branch: it begins with a dash (to protect command lines).

Non-ASCII letters are allowed; Git compares names byte for byte, so beware of file systems that rewrite Unicode.

Usage notes

  • Validate the full name (refs/heads/<x>), not just <x>, otherwise a single-level name fails.
  • Branch names are more restricted than ref names: --branch also rejects names that start with a dash.
  • Case sensitivity is not checked. Feature and feature are different refs, but on case-insensitive file systems they can collide when stored as loose files.
  • --normalize is not a repair tool. It only fixes slashes; a name with spaces stays invalid.
  • Same rules everywhere: git branch, git tag, git update-ref and git push all use this check internally.