git-check-ref-format.1 (8004B)
- '\" t
- .\" Title: git-check-ref-format
- .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
- .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
- .\" Date: 2025-03-14
- .\" Manual: Git Manual
- .\" Source: Git 2.49.0
- .\" Language: English
- .\"
- .TH "GIT\-CHECK\-REF\-FORMAT" "1" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
- .\" -----------------------------------------------------------------
- .\" * Define some portability stuff
- .\" -----------------------------------------------------------------
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .\" http://bugs.debian.org/507673
- .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .ie \n(.g .ds Aq \(aq
- .el .ds Aq '
- .\" -----------------------------------------------------------------
- .\" * set default formatting
- .\" -----------------------------------------------------------------
- .\" disable hyphenation
- .nh
- .\" disable justification (adjust text to left margin only)
- .ad l
- .\" -----------------------------------------------------------------
- .\" * MAIN CONTENT STARTS HERE *
- .\" -----------------------------------------------------------------
- .SH "NAME"
- git-check-ref-format \- Ensures that a reference name is well formed
- .SH "SYNOPSIS"
- .sp
- .nf
- \fIgit check\-ref\-format\fR [\-\-normalize]
- [\-\-[no\-]allow\-onelevel] [\-\-refspec\-pattern]
- <refname>
- \fIgit check\-ref\-format\fR \-\-branch <branchname\-shorthand>
- .fi
- .SH "DESCRIPTION"
- .sp
- Checks if a given \fIrefname\fR is acceptable, and exits with a non\-zero status if it is not\&.
- .sp
- A reference is used in Git to specify branches and tags\&. A branch head is stored in the \fBrefs/heads\fR hierarchy, while a tag is stored in the \fBrefs/tags\fR hierarchy of the ref namespace (typically in \fB$GIT_DIR/refs/heads\fR and \fB$GIT_DIR/refs/tags\fR directories or, as entries in file \fB$GIT_DIR/packed\-refs\fR if refs are packed by \fBgit\fR \fBgc\fR)\&.
- .sp
- Git imposes the following rules on how references are named:
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 1.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 1." 4.2
- .\}
- They can include slash
- \fB/\fR
- for hierarchical (directory) grouping, but no slash\-separated component can begin with a dot \&. or end with the sequence \&.\fBlock\fR\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 2.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 2." 4.2
- .\}
- They must contain at least one
- \fB/\fR\&. This enforces the presence of a category like
- \fBheads/\fR,
- \fBtags/\fR
- etc\&. but the actual names are not restricted\&. If the
- \fB\-\-allow\-onelevel\fR
- option is used, this rule is waived\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 3.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 3." 4.2
- .\}
- They cannot have two consecutive dots \&.\&. anywhere\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 4.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 4." 4.2
- .\}
- They cannot have ASCII control characters (i\&.e\&. bytes whose values are lower than \e040, or \e177
- \fBDEL\fR), space, tilde
- \fB~\fR, caret
- \fB^\fR, or colon
- \fB:\fR
- anywhere\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 5.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 5." 4.2
- .\}
- They cannot have question\-mark ?, asterisk *, or open bracket [ anywhere\&. See the
- \fB\-\-refspec\-pattern\fR
- option below for an exception to this rule\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 6.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 6." 4.2
- .\}
- They cannot begin or end with a slash
- \fB/\fR
- or contain multiple consecutive slashes (see the
- \fB\-\-normalize\fR
- option below for an exception to this rule)\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 7.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 7." 4.2
- .\}
- They cannot end with a dot \&.\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 8.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 8." 4.2
- .\}
- They cannot contain a sequence
- \fB@\fR{\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 9.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 9." 4.2
- .\}
- They cannot be the single character
- \fB@\fR\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'10.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP "10." 4.2
- .\}
- They cannot contain a \e\&.
- .RE
- .sp
- 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 \fBgitrevisions\fR(7)):
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 1.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 1." 4.2
- .\}
- A double\-dot \&.\&. is often used as in
- \fBref1\fR\fB\&.\&.\fR\fBref2\fR, and in some contexts this notation means
- \fB^ref1\fR
- \fBref2\fR
- (i\&.e\&. not in
- \fBref1\fR
- and in
- \fBref2\fR)\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 2.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 2." 4.2
- .\}
- A tilde
- \fB~\fR
- and caret
- \fB^\fR
- are used to introduce the postfix
- \fInth parent\fR
- and
- \fIpeel onion\fR
- operation\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 3.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 3." 4.2
- .\}
- A colon
- \fB:\fR
- is used as in
- \fBsrcref:dstref\fR
- to mean "use srcref\(cqs value and store it in dstref" in fetch and push operations\&. It may also be used to select a specific object such as with \*(Aqgit cat\-file\*(Aq: "git cat\-file blob v1\&.3\&.3:refs\&.c"\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 4.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 4." 4.2
- .\}
- at\-open\-brace
- \fB@\fR{ is used as a notation to access a reflog entry\&.
- .RE
- .sp
- With the \fB\-\-branch\fR 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 \fBgit\fR \fBcheck\-ref\-format\fR \fB\-\-branch\fR \fB$name\fR implements may be stricter than what \fBgit\fR \fBcheck\-ref\-format\fR \fBrefs/heads/$name\fR 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 \fB\-\-branch\fR option in a repository, the input is first expanded for the \(lqprevious checkout syntax\(rq \fB@\fR{\-n}\&. For example, \fB@\fR{\-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 \(lqprevious checkout operation\(rq might result in a commit object name when the N\-th last thing checked out was not a branch\&.
- .SH "OPTIONS"
- .PP
- \-\-[no\-]allow\-onelevel
- .RS 4
- Controls whether one\-level refnames are accepted (i\&.e\&., refnames that do not contain multiple
- \fB/\fR\-separated components)\&. The default is
- \fB\-\-no\-allow\-onelevel\fR\&.
- .RE
- .PP
- \-\-refspec\-pattern
- .RS 4
- Interpret <refname> as a reference name pattern for a refspec (as used with remote repositories)\&. If this option is enabled, <refname> is allowed to contain a single * in the refspec (e\&.g\&.,
- \fBfoo/bar\fR*/baz or
- \fBfoo/bar\fR*baz/ but not
- \fBfoo/bar\fR*/baz*)\&.
- .RE
- .PP
- \-\-normalize
- .RS 4
- Normalize
- \fIrefname\fR
- by removing any leading slash (\fB/\fR) characters and collapsing runs of adjacent slashes between name components into a single slash\&. If the normalized refname is valid then print it to standard output and exit with a status of 0, otherwise exit with a non\-zero status\&. (\fB\-\-print\fR
- is a deprecated way to spell
- \fB\-\-normalize\fR\&.)
- .RE
- .SH "EXAMPLES"
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Print the name of the previous thing checked out:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git check\-ref\-format \-\-branch @{\-1}
- .fi
- .if n \{\
- .RE
- .\}
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Determine the reference name to use for a new branch:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ ref=$(git check\-ref\-format \-\-normalize "refs/heads/$newbranch")||
- { echo "we do not like \*(Aq$newbranch\*(Aq as a branch name\&." >&2 ; exit 1 ; }
- .fi
- .if n \{\
- .RE
- .\}
- .RE
- .SH "GIT"
- .sp
- Part of the \fBgit\fR(1) suite