LinuxCommandLibrary

git-check-ref-format

Check if a reference name is valid

TLDR

Check the format of the specified reference name

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

Print the name of the last branch checked out
$ git check-ref-format --branch @{-1}
copy

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

SYNOPSIS

git check-ref-format [--allow-onelevel] [--refspec-pattern] refname

PARAMETERS

--allow-onelevel
    Allow refnames that do not have at least one / component. Needed when creating the symbolic ref HEAD.

--refspec-pattern
    The given refname is used as a refspec pattern.

refname
    The name of the ref to validate.

DESCRIPTION

The `git-check-ref-format` command validates whether a given reference name (like a branch or tag name) conforms to Git's naming conventions. It's crucial for ensuring reference names are valid and prevents issues with Git operations. The command checks for various criteria, including forbidden characters, naming patterns, and length restrictions.

This command is primarily used by scripts and Git's internal operations to prevent creating invalid references. It helps maintain consistency and avoids conflicts that can arise from malformed names. A valid reference name is essential for Git to correctly manage branches, tags, and other references within a repository. By using `git-check-ref-format`, developers and administrators can enforce naming standards and prevent common errors related to reference naming.

CAVEATS

The `--refspec-pattern` option changes the interpretation of the refname and validates it against refspec rules rather than standard ref name rules.

EXIT STATUS

The command exits with 0 if the reference name is valid, and a non-zero value if it is invalid.

REFERENCE NAME RULES

Git enforces several rules for reference names: They must contain at least one / character unless --allow-onelevel is specified. They cannot start or end with a /. They cannot contain sequences of multiple consecutive /. They cannot contain ASCII control characters, space, tilde ~, caret ^, colon :, question mark ?, asterisk *, or open square bracket [. They cannot contain two consecutive dots .. anywhere. They cannot contain a sequence @{ anywhere. They cannot contain a backslash \. They cannot end with a dot ..lock.

SEE ALSO

Copied to clipboard