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.
git check-ref-format refs/heads/feature/login
git check-ref-format --branch feature/login
Try it
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.
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
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:
--branchalso rejects names that start with a dash. - Case sensitivity is not checked.
Featureandfeatureare different refs, but on case-insensitive file systems they can collide when stored as loose files. --normalizeis not a repair tool. It only fixes slashes; a name with spaces stays invalid.- Same rules everywhere:
git branch,git tag,git update-refandgit pushall use this check internally.
Related
git update-ref,git branch,git tag, Refspec- Lessons: Refs and HEAD, Branches