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 [--normalize] [--allow-onelevel] [--strict] [--refspec-gen] [--refspec-parse] refname...

--normalize
    Normalizes the reference name to its canonical form and prints it to standard output. If the name is invalid, an error is printed, and the command exits non-zero.

--allow-onelevel
    Permits single-component reference names (e.g., 'foo') which are otherwise considered invalid by default. Without this option, names like 'master' would be rejected as invalid if not prefixed with 'refs/heads/'.

--strict
    Applies stricter validation rules, disallowing certain common names (like 'HEAD', 'MERGE_HEAD', etc.) unless they are fully qualified (e.g., 'refs/heads/HEAD'). Also disallows names that resemble SHA-1 object IDs.

--refspec-gen
    Generates and prints a canonical refspec string from the input refname, useful for git fetch or git push commands. For example, 'master' might become 'master:refs/heads/master'.

--refspec-parse
    Parses a refspec string and prints its components: source, destination, force flag, and pattern. This helps in understanding how Git interprets complex refspec strings.

The git-check-ref-format command is a low-level utility used to determine if a given string conforms to the rules for a valid Git reference name (refname). These rules are crucial for ensuring consistency, preventing ambiguity, and avoiding potential security issues within the Git repository. A refname typically points to a commit, tag, or other object within the Git object database.

The command exits with 0 if the provided refname is valid and a non-zero status otherwise, making it highly suitable for use in scripts and automated workflows. Beyond simple validation, it can also normalize refnames to their canonical form (e.g., `master` to `refs/heads/master`) or parse/generate refspecs used in fetch and push operations. This functionality aids in the correct construction and interpretation of references, which is essential for tools and scripts interacting deeply with Git's internal object model.

Reference names that start with refs/ (e.g., refs/heads/master, refs/tags/v1.0) are generally recommended. They are more portable and help avoid conflicts with special Git names (like HEAD) or ambiguities that can arise from single-level references.

Git reference names must adhere to specific rules to be considered valid. They cannot contain certain characters (e.g., ~, ^, :, ?, *), sequences (e.g., .., //), or start/end with specific patterns (e.g., .lock, /). Additionally, they cannot contain non-printable ASCII characters or the DEL character. These rules prevent ambiguity, ensure filesystem compatibility across different operating systems, and mitigate security risks.

The --refspec-gen and --refspec-parse options are particularly valuable for developers and scripts that programmatically interact with Git's fetching and pushing mechanisms. Refspecs define how local and remote references are mapped during these operations. These options provide a reliable way to correctly construct and interpret these complex strings, ensuring proper synchronization between repositories.

git-check-ref-format is a fundamental 'plumbing' command within Git, playing a crucial role in maintaining the integrity and consistency of the repository's reference system. Its rules have evolved over time to enhance robustness, prevent name collisions, and ensure security against directory traversal or command injection via malformed reference names. It underpins many higher-level Git commands that interact with, create, or modify references.

git-rev-parse(1), git-for-each-ref(1), gitnamespaces(7)