check-ref-format Git Command Guide

The git check-ref-format command is used to check if a given reference name is acceptable according to Git’s naming rules, exiting with a non-zero status if the refname is invalid. Reference names must follow specific rules to avoid ambiguities and shell parsing issues.

git check-ref-format Syntax:

git check-ref-format [--normalize]
       [--[no-]allow-onelevel] [--refspec-pattern]
       <refname>

git check-ref-format --branch <branchname-shorthand>

Options:

Option	Description
—normalize	Normalize refname by removing leading slashes and collapsing consecutive slashes
—[no-]allow-onelevel	Controls whether one-level refnames are accepted
—refspec-pattern	Interpret as a reference name pattern for a refspec

Parameters:

Parameter	Description
	Reference name to validate
	Branch name to validate (with —branch option)

Caution

Git has strict rules for reference names to prevent ambiguities in expressions and shell expansion; always validate names before using them programmatically.

git check-ref-format Command Samples:

Validate a reference name

git check-ref-format refs/heads/feature_branch

Checks if the refname is valid, exits with 0 if valid, non-zero if invalid.

Normalize a reference name

git check-ref-format --normalize "refs/heads//feature/branch"

Removes extra slashes and outputs the normalized form if valid.

Check branch name validity

git check-ref-format --branch new_feature

Validates if the name can be used as a branch name.

Allow one-level refs

git check-ref-format --allow-onelevel single_level

Permits validation of single-level reference names without slashes.

Use as refspec pattern

git check-ref-format --refspec-pattern "refs/heads/feature_*"

Allows a single * wildcard for patterns in refspecs.

Tip

Use before creating branches or tags to avoid invalid reference names that cause issues later.

How do I validate a reference name?

To validate a reference name, use:

git check-ref-format <refname>

How can I normalize a reference name?

To normalize a reference name, run:

git check-ref-format --normalize <refname>

How do I check if a name is valid for a branch?

To check if a name is valid for a branch, execute:

git check-ref-format --branch <branchname>

How can I allow one-level reference names?

To allow one-level reference names, use:

git check-ref-format --allow-onelevel <refname>

How do I validate refspec patterns?

To validate refspec patterns, run:

git check-ref-format --refspec-pattern <pattern>

Applications of the git check-ref-format command

1. Validating user input for branch names in automation scripts
2. Checking reference names before creating tags programmatically
3. Normalizing user-provided refnames to canonical form
4. Debugging invalid reference name errors in Git operations
5. Implementing safe reference creation in Git tools and workflows
6. Testing branch name conventions before enforcement
7. Sanitizing reference names from external sources