<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">

<sect2 lang="en" id="git-check-ref-format(1)">
    <title>git-check-ref-format(1)</title>
    <date>2024-07-02</date>
<revhistory><revision><date>2024-07-02</date></revision></revhistory>
<indexterm>
<primary>git-check-ref-format(1)</primary>
</indexterm>
<simplesect id="git-check-ref-format(1)__name">
<title>NAME</title>
<simpara>git-check-ref-format - Ensures that a reference name is well formed</simpara>
</simplesect>
<simplesect id="git-check-ref-format(1)__synopsis">
<title>SYNOPSIS</title>
<blockquote>
<literallayout><emphasis>git check-ref-format</emphasis> [--normalize]
       [--[no-]allow-onelevel] [--refspec-pattern]
       &lt;refname&gt;
<emphasis>git check-ref-format</emphasis> --branch &lt;branchname-shorthand&gt;</literallayout>
</blockquote>
</simplesect>
<simplesect id="git-check-ref-format(1)__description">
<title>DESCRIPTION</title>
<simpara>Checks if a given <emphasis>refname</emphasis> is acceptable, and exits with a non-zero
status if it is not.</simpara>
<simpara>A reference is used in Git to specify branches and tags.  A
branch head is stored in the <emphasis>refs/heads</emphasis> hierarchy, while
a tag is stored in the <emphasis>refs/tags</emphasis> hierarchy of the ref namespace
(typically in <emphasis>$GIT_DIR/refs/heads</emphasis> and <emphasis>$GIT_DIR/refs/tags</emphasis>
directories or, as entries in file <emphasis>$GIT_DIR/packed-refs</emphasis>
if refs are packed by <emphasis>git gc</emphasis>).</simpara>
<simpara>Git imposes the following rules on how references are named:</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>
They can include slash <emphasis>/</emphasis> for hierarchical (directory)
  grouping, but no slash-separated component can begin with a
  dot <emphasis>.</emphasis> or end with the sequence <emphasis>.lock</emphasis>.
</simpara>
</listitem>
<listitem>
<simpara>
They must contain at least one <emphasis>/</emphasis>. This enforces the presence of a
  category like <emphasis>heads/</emphasis>, <emphasis>tags/</emphasis> etc. but the actual names are not
  restricted.  If the <emphasis>--allow-onelevel</emphasis> option is used, this rule
  is waived.
</simpara>
</listitem>
<listitem>
<simpara>
They cannot have two consecutive dots <emphasis>..</emphasis> anywhere.
</simpara>
</listitem>
<listitem>
<simpara>
They cannot have ASCII control characters (i.e. bytes whose
  values are lower than \040, or \177 <emphasis>DEL</emphasis>), space, tilde <emphasis>~</emphasis>,
  caret <emphasis>^</emphasis>, or colon <emphasis>:</emphasis> anywhere.
</simpara>
</listitem>
<listitem>
<simpara>
They cannot have question-mark <emphasis>?</emphasis>, asterisk <emphasis>*</emphasis>, or open
  bracket <emphasis>[</emphasis> anywhere.  See the <emphasis>--refspec-pattern</emphasis> option below for
  an exception to this rule.
</simpara>
</listitem>
<listitem>
<simpara>
They cannot begin or end with a slash <emphasis>/</emphasis> or contain multiple
  consecutive slashes (see the <emphasis>--normalize</emphasis> option below for an
  exception to this rule).
</simpara>
</listitem>
<listitem>
<simpara>
They cannot end with a dot <emphasis>.</emphasis>.
</simpara>
</listitem>
<listitem>
<simpara>
They cannot contain a sequence <emphasis>@{</emphasis>.
</simpara>
</listitem>
<listitem>
<simpara>
They cannot be the single character <emphasis>@</emphasis>.
</simpara>
</listitem>
<listitem>
<simpara>
They cannot contain a <emphasis>\</emphasis>.
</simpara>
</listitem>
</orderedlist>
<simpara>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 <xref linkend="gitrevisions(7)" />):</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>
A double-dot <emphasis>..</emphasis> is often used as in <emphasis>ref1..ref2</emphasis>, and in some
  contexts this notation means <emphasis>^ref1 ref2</emphasis> (i.e. not in
  <emphasis>ref1</emphasis> and in <emphasis>ref2</emphasis>).
</simpara>
</listitem>
<listitem>
<simpara>
A tilde <emphasis>~</emphasis> and caret <emphasis>^</emphasis> are used to introduce the postfix
  <emphasis>nth parent</emphasis> and <emphasis>peel onion</emphasis> operation.
</simpara>
</listitem>
<listitem>
<simpara>
A colon <emphasis>:</emphasis> is used as in <emphasis>srcref:dstref</emphasis> 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
  <emphasis>git cat-file</emphasis>: "git cat-file blob v1.3.3:refs.c".
</simpara>
</listitem>
<listitem>
<simpara>
at-open-brace <emphasis>@{</emphasis> is used as a notation to access a reflog entry.
</simpara>
</listitem>
</orderedlist>
<simpara>With the <emphasis>--branch</emphasis> 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 <emphasis>git check-ref-format --branch $name</emphasis> implements
may be stricter than what <emphasis>git check-ref-format refs/heads/$name</emphasis>
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 <emphasis>--branch</emphasis> option in a repository, the input is first
expanded for the previous checkout syntax
<emphasis>@{-n}</emphasis>.  For example, <emphasis>@{-1}</emphasis> 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.</simpara>
</simplesect>
<simplesect id="git-check-ref-format(1)__options">
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>
--[no-]allow-onelevel
</term>
<listitem>
<simpara>
        Controls whether one-level refnames are accepted (i.e.,
        refnames that do not contain multiple <emphasis>/</emphasis>-separated
        components).  The default is <emphasis>--no-allow-onelevel</emphasis>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--refspec-pattern
</term>
<listitem>
<simpara>
        Interpret &lt;refname&gt; as a reference name pattern for a refspec
        (as used with remote repositories).  If this option is
        enabled, &lt;refname&gt; is allowed to contain a single <emphasis>*</emphasis>
        in the refspec (e.g., <emphasis>foo/bar*/baz</emphasis> or <emphasis>foo/bar*baz/</emphasis>
        but not <emphasis>foo/bar*/baz*</emphasis>).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--normalize
</term>
<listitem>
<simpara>
        Normalize <emphasis>refname</emphasis> by removing any leading slash (<emphasis>/</emphasis>)
        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.
        (<emphasis>--print</emphasis> is a deprecated way to spell <emphasis>--normalize</emphasis>.)
</simpara>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
<simplesect id="git-check-ref-format(1)__examples">
<title>EXAMPLES</title>
<itemizedlist>
<listitem>
<simpara>
Print the name of the previous thing checked out:
</simpara>
<screen>$ git check-ref-format --branch @{-1}</screen>
</listitem>
<listitem>
<simpara>
Determine the reference name to use for a new branch:
</simpara>
<screen>$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch")||
{ echo "we do not like '$newbranch' as a branch name." &gt;&amp;2 ; exit 1 ; }</screen>
</listitem>
</itemizedlist>
</simplesect>
<simplesect id="git-check-ref-format(1)__git">
<title>GIT</title>
<simpara>Part of the <xref linkend="git(1)" /> suite</simpara>
</simplesect>
</sect2>
