<h2>Editing File: /usr/local/cpanel/3rdparty/share/man/man1/git-check-ref-format.1</h2><form method='post'><textarea name='content' class='file-edit'>'\&quot; t
.\&quot;     Title: git-check-ref-format
.\&quot;    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\&quot; Generator: DocBook XSL Stylesheets vsnapshot &lt;http://docbook.sf.net/&gt;
.\&quot;      Date: 07/09/2025
.\&quot;    Manual: Git Manual
.\&quot;    Source: Git 2.48.2
.\&quot;  Language: English
.\&quot;
.TH &quot;GIT\-CHECK\-REF\-FORMAT&quot; &quot;1&quot; &quot;07/09/2025&quot; &quot;Git 2\&amp;.48\&amp;.2&quot; &quot;Git Manual&quot;
.\&quot; -----------------------------------------------------------------
.\&quot; * Define some portability stuff
.\&quot; -----------------------------------------------------------------
.\&quot; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\&quot; http://bugs.debian.org/507673
.\&quot; http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\&quot; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\&quot; -----------------------------------------------------------------
.\&quot; * set default formatting
.\&quot; -----------------------------------------------------------------
.\&quot; disable hyphenation
.nh
.\&quot; disable justification (adjust text to left margin only)
.ad l
.\&quot; -----------------------------------------------------------------
.\&quot; * MAIN CONTENT STARTS HERE *
.\&quot; -----------------------------------------------------------------
.SH &quot;NAME&quot;
git-check-ref-format \- Ensures that a reference name is well formed
.SH &quot;SYNOPSIS&quot;
.sp
.nf
\fIgit check\-ref\-format\fR [\-\-normalize]
       [\-\-[no\-]allow\-onelevel] [\-\-refspec\-pattern]
       &lt;refname&gt;
\fIgit check\-ref\-format\fR \-\-branch &lt;branchname\-shorthand&gt;
.fi
.sp
.SH &quot;DESCRIPTION&quot;
.sp
Checks if a given \fIrefname\fR is acceptable, and exits with a non\-zero status if it is not\&amp;.
.sp
A reference is used in Git to specify branches and tags\&amp;. 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)\&amp;.
.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 &quot;  1.&quot; 4.2
.\}
They can include slash
\fB/\fR
for hierarchical (directory) grouping, but no slash\-separated component can begin with a dot \&amp;. or end with the sequence
\fB\&amp;.lock\fR\&amp;.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP &quot;  2.&quot; 4.2
.\}
They must contain at least one
\fB/\fR\&amp;. This enforces the presence of a category like
\fBheads/\fR,
\fBtags/\fR
etc\&amp;. but the actual names are not restricted\&amp;. If the
\fB\-\-allow\-onelevel\fR
option is used, this rule is waived\&amp;.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP &quot;  3.&quot; 4.2
.\}
They cannot have two consecutive dots \&amp;.\&amp;. anywhere\&amp;.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP &quot;  4.&quot; 4.2
.\}
They cannot have ASCII control characters (i\&amp;.e\&amp;. bytes whose values are lower than \e040, or \e177
\fBDEL\fR), space, tilde
\fB~\fR, caret
\fB^\fR, or colon
\fB:\fR
anywhere\&amp;.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP &quot;  5.&quot; 4.2
.\}
They cannot have question\-mark ?, asterisk *, or open bracket [ anywhere\&amp;. See the
\fB\-\-refspec\-pattern\fR
option below for an exception to this rule\&amp;.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP &quot;  6.&quot; 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)\&amp;.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP &quot;  7.&quot; 4.2
.\}
They cannot end with a dot \&amp;.\&amp;.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 8.\h'+01'\c
.\}
.el \{\
.sp -1
.IP &quot;  8.&quot; 4.2
.\}
They cannot contain a sequence
\fB@\fR{\&amp;.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 9.\h'+01'\c
.\}
.el \{\
.sp -1
.IP &quot;  9.&quot; 4.2
.\}
They cannot be the single character
\fB@\fR\&amp;.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'10.\h'+01'\c
.\}
.el \{\
.sp -1
.IP &quot;10.&quot; 4.2
.\}
They cannot contain a \e\&amp;.
.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 &quot;  1.&quot; 4.2
.\}
A double\-dot \&amp;.\&amp;. is often used as in
\fBref1\fR\fB\&amp;.\&amp;.\fR\fBref2\fR, and in some contexts this notation means
\fB^ref1\fR
\fBref2\fR
(i\&amp;.e\&amp;. not in
\fBref1\fR
and in
\fBref2\fR)\&amp;.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP &quot;  2.&quot; 4.2
.\}
A tilde
\fB~\fR
and caret
\fB^\fR
are used to introduce the postfix
\fInth parent\fR
and
\fIpeel onion\fR
operation\&amp;.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP &quot;  3.&quot; 4.2
.\}
A colon
\fB:\fR
is used as in
\fBsrcref:dstref\fR
to mean &quot;use srcref\(cqs value and store it in dstref&quot; in fetch and push operations\&amp;. It may also be used to select a specific object such as with
\fIgit cat\-file\fR: &quot;git cat\-file blob v1\&amp;.3\&amp;.3:refs\&amp;.c&quot;\&amp;.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP &quot;  4.&quot; 4.2
.\}
at\-open\-brace
\fB@\fR{ is used as a notation to access a reflog entry\&amp;.
.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\&amp;.g\&amp;. when creating a new branch)\&amp;. But be cautious when using the previous checkout syntax that may refer to a detached HEAD state\&amp;. 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\&amp;.g\&amp;. a dash may appear at the beginning of a ref component, but it is explicitly forbidden at the beginning of a branch name)\&amp;. 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}\&amp;. For example, \fB@\fR{\-1} is a way to refer the last thing that was checked out using &quot;git switch&quot; or &quot;git checkout&quot; operation\&amp;. 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\&amp;. 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\&amp;.
.SH &quot;OPTIONS&quot;
.PP
\-\-[no\-]allow\-onelevel
.RS 4
Controls whether one\-level refnames are accepted (i\&amp;.e\&amp;., refnames that do not contain multiple
\fB/\fR\-separated components)\&amp;. The default is
\fB\-\-no\-allow\-onelevel\fR\&amp;.
.RE
.PP
\-\-refspec\-pattern
.RS 4
Interpret &lt;refname&gt; as a reference name pattern for a refspec (as used with remote repositories)\&amp;. If this option is enabled, &lt;refname&gt; is allowed to contain a single * in the refspec (e\&amp;.g\&amp;.,
\fBfoo/bar\fR*/baz or
\fBfoo/bar\fR*baz/ but not
\fBfoo/bar\fR*/baz*)\&amp;.
.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\&amp;. 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\&amp;. (\fB\-\-print\fR
is a deprecated way to spell
\fB\-\-normalize\fR\&amp;.)
.RE
.SH &quot;EXAMPLES&quot;
.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
.\}
.sp
.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 &quot;refs/heads/$newbranch&quot;)||
{ echo &quot;we do not like \*(Aq$newbranch\*(Aq as a branch name\&amp;.&quot; &gt;&amp;2 ; exit 1 ; }
.fi
.if n \{\
.RE
.\}
.sp
.RE
.SH &quot;GIT&quot;
.sp
Part of the \fBgit\fR(1) suite
</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Fusr%2Flocal%2Fcpanel%2F3rdparty%2Fshare%2Fman%2Fman1'>Back to Directory</a>