GIT-CHECK-REF-FOR(1)
NAME
git-check-ref-format - Ensures that a reference name is well formed
SYNOPSIS
git check-ref-format <refname> git check-ref-format --print <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 under the $GIT_DIR/refs/heads directory, and a tag is stored
under the $GIT_DIR/refs/tags directory (or, if refs are packed by git
gc, as entries in the $GIT_DIR/packed-refs file). git imposes the
following rules on how references are named: - 1. They can include slash / for hierarchical (directory) grouping, but no slash-separated component can begin with a dot ..
- 2. They must contain at least one /. This enforces the presence of a
category like heads/, tags/ etc. but the actual names are not
restricted. - 3. They cannot have two consecutive dots .. anywhere.
- 4. They cannot have ASCII control characters (i.e. bytes whose values
are lower than \040, or \177 DEL), space, tilde ~, caret ^, colon
:, question-mark ?, asterisk *, or open bracket [ anywhere. - 5. They cannot end with a slash / nor a dot ..
- 6. They cannot end with the sequence .lock.
- 7. They cannot contain a sequence @{.
- 8. They cannot contain a \.
- 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 avoids ambiguities in certain
reference name expressions (see git-rev-parse(1)):
1. A double-dot .. is often used as in ref1..ref2, and in some
contexts this notation means ^ref1 ref2 (i.e. not in ref1 and in
ref2).- 2. A tilde ~ and caret ^ are used to introduce the postfix nth parent and peel onion operation.
- 3. A colon : is used as in srcref:dstref to mean "use srcref's value
and store it in dstref" in fetch and push operations. It may also
be used to select a specific object such as with git cat-file: "git cat-file blob v1.3.3:refs.c". - 4. at-open-brace @{ is used as a notation to access a reflog entry.
- With the --print option, if refname is acceptable, it prints the canonicalized name of a hypothetical reference with that name. That is, it prints refname with any extra / characters removed.
- With the --branch option, it expands the "previous branch syntax"
@{-n}. For example, @{-1} is a way to refer the last branch you were
on. 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.
EXAMPLES
- o Print the name of the previous branch:
- $ git check-ref-format --branch @{-1}
- o Determine the reference name to use for a new branch:
$ ref=$(git check-ref-format --print "refs/heads/$newbranch") || die "we do not like '$newbranch' as a branch name."
GIT
- Part of the git(1) suite