<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<article lang="en" id="git-check-ref-format(1)">
<articleinfo>
    <title>git-check-ref-format(1)</title>
        <indexterm>
                <primary>git-check-ref-format(1)</primary>
        </indexterm>
</articleinfo>
<simplesect id="_name">
<title>NAME</title>
<simpara>git-check-ref-format - Make sure ref name is well formed</simpara>
</simplesect>
<simplesect id="_synopsis">
<title>SYNOPSIS</title>
<simpara><emphasis>git check-ref-format</emphasis> &lt;refname&gt;</simpara>
</simplesect>
<simplesect id="_description">
<title>DESCRIPTION</title>
<simpara>Checks if a given <emphasis>refname</emphasis> is acceptable, and exits non-zero if
it is not.</simpara>
<simpara>A reference is used in git to specify branches and tags.  A
branch head is stored under <literal>$GIT_DIR/refs/heads</literal> directory, and
a tag is stored under <literal>$GIT_DIR/refs/tags</literal> directory.  git
imposes the following rules on how refs are named:</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>
It can include slash <literal>/</literal> for hierarchical (directory)
  grouping, but no slash-separated component can begin with a
  dot <literal>.</literal>;
</simpara>
</listitem>
<listitem>
<simpara>
It cannot have two consecutive dots <literal>..</literal> anywhere;
</simpara>
</listitem>
<listitem>
<simpara>
It cannot have ASCII control character (i.e. bytes whose
  values are lower than \040, or \177 <literal>DEL</literal>), space, tilde <literal>~</literal>,
  caret <literal>&#94;</literal>, colon <literal>:</literal>, question-mark <literal>?</literal>, asterisk <literal>*</literal>,
  or open bracket <literal>[</literal> anywhere;
</simpara>
</listitem>
<listitem>
<simpara>
It cannot end with a slash <literal>/</literal>.
</simpara>
</listitem>
</orderedlist>
<simpara>These rules makes it easy for shell script based tools to parse
refnames, pathname expansion by the shell when a refname is used
unquoted (by mistake), and also avoids ambiguities in certain
refname expressions (see <xref linkend="git-rev-parse(1)"/>).  Namely:</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>
double-dot <literal>..</literal> are often used as in <literal>ref1..ref2</literal>, and in some
  context this notation means <literal>&#94;ref1 ref2</literal> (i.e. not in
  ref1 and in ref2).
</simpara>
</listitem>
<listitem>
<simpara>
tilde <literal>~</literal> and caret <literal>&#94;</literal> are used to introduce postfix
  <emphasis>nth parent</emphasis> and <emphasis>peel onion</emphasis> operation.
</simpara>
</listitem>
<listitem>
<simpara>
colon <literal>:</literal> is used as in <literal>srcref:dstref</literal> to mean "use srcref&#8217;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>
</orderedlist>
</simplesect>
<simplesect id="_git">
<title>GIT</title>
<simpara>Part of the <xref linkend="git(1)"/> suite</simpara>
</simplesect>
</article>
