GIT-CHECK-REF-FORMAT(1) | Git Manual | GIT-CHECK-REF-FORMAT(1) |
NAME
git-check-ref-format - Ensures that a reference name is well formed
SYNOPSIS
git check-ref-format [--normalize] [--[no-]allow-onelevel] [--refspec-pattern] <refname> git check-ref-format --branch <branchname-shorthand>
DESCRIPTION
Checks if a given refname is acceptable, and exits with a non-zero status if it is not.
A reference is used in Git to specify branches and tags. A branch head is stored in the refs/heads hierarchy, while a tag is stored in the refs/tags hierarchy of the ref namespace (typically in $GIT_DIR/refs/heads and $GIT_DIR/refs/tags directories or, as entries in file $GIT_DIR/packed-refs if refs are packed by git gc).
Git imposes the following rules on how references are named:
These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used unquoted (by mistake), and also avoid ambiguities in certain reference name expressions (see gitrevisions(7)):
With the --branch option, the command takes a name and checks if it can be used as a valid branch name (e.g. when creating a new branch). But be cautious when using the previous checkout syntax that may refer to a detached HEAD state. The rule git check-ref-format --branch $name implements may be stricter than what git check-ref-format refs/heads/$name says (e.g. a dash may appear at the beginning of a ref component, but it is explicitly forbidden at the beginning of a branch name). When run with the --branch option in a repository, the input is first expanded for the “previous checkout syntax” @{-n}. For example, @{-1} is a way to refer the last thing that was checked out using "git switch" or "git checkout" operation. This option should be used by porcelains to accept this syntax anywhere a branch name is expected, so they can act as if you typed the branch name. As an exception note that, the “previous checkout operation” might result in a commit object name when the N-th last thing checked out was not a branch.
OPTIONS
--[no-]allow-onelevel
--refspec-pattern
--normalize
EXAMPLES
$ git check-ref-format --branch @{-1}
$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch")|| { echo "we do not like '$newbranch' as a branch name." >&2 ; exit 1 ; }
GIT
Part of the git(1) suite
11/25/2024 | Git 2.47.1 |