git-check-ref-format

Check the format of the specified reference name

$ git check-ref-format [refs/head/refname]

$ git check-ref-format --branch @{-1}

$ git check-ref-format --normalize [refs/head/refname]

git check-ref-format [options...] <refname>

-q, --quiet
    Suppress error output; exit 1 silently on invalid refname.

--allow-onelevel
    Permit single-level refnames like master (default forbids).

--normalize
    Normalize refname relative to .git/refs/ and print canonical form.

--print, -p
    Print normalized refname on success instead of just exiting 0.

--verify, -v
    Strictly verify; disallow names invalid as branches or tags.

--allow-branch
    With --verify, allow branch-like names (e.g., starting/ending with '-').

--allow-mixed-case
    Permit mixed-case letters in refnames (default: lowercase only).

--allow-leading-dot
    Allow components starting with '.' (default forbids).

--allow-twolevel
    Require exactly two-level refnames (default allows more).

-t <type>, --type=<type>
    Check if refname matches specific type like 'head', 'tag'.

The git check-ref-format command verifies if a given string conforms to Git's reference name (refname) format rules. Git refnames identify branches, tags, and other pointers in the .git/refs/ hierarchy, such as refs/heads/master or refs/tags/v1.0.

This utility is primarily used internally by other Git commands to ensure refnames are safe and follow conventions before operations like creating or updating refs. Standalone usage allows scripting to check validity without side effects.

It enforces rules like: components separated by '/', no uppercase letters (unless allowed), no leading/trailing dots or dashes, no double dots ('..'), no '@{' or '~', and specific forbidden characters. Invalid formats cause non-zero exit (usually 1), optionally printing errors unless quiet mode is used. Normalization mode resolves and canonicalizes paths relative to refs/.

Common in hooks, CI scripts, or tools generating refnames dynamically. Enhances repository integrity by preventing malformed refs that could lead to errors or security issues.

Does not check ref existence, only format. Normalization assumes current repo context. Strict modes (--verify) reject more names than defaults.

0: valid refname.
1: invalid format.
128: usage error; 129+: other.

git check-ref-format "refs/heads/master" → exits 0.
git check-ref-format --normalize "heads/main" → prints refs/heads/main.

Introduced in Git 1.0 (2005) as a low-level helper for ref validation. Evolved with Git's refname rules; options like --normalize added in 1.7.x for better scripting support. Widely used internally since Git 1.5.

git-update-ref(1), git-symbolic-ref(1), git-for-each-ref(1), git-check-attr(1)