doc/source/en/TortoiseGit/git_doc/git-check-ref-format.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">\r
   3 \r
   4 <sect2 lang="en" id="git-check-ref-format(1)">\r
   5     <title>git-check-ref-format(1)</title>\r
   6 <indexterm>\r
   7 <primary>git-check-ref-format(1)</primary>\r
   8 </indexterm>\r
   9 <simplesect id="git-check-ref-format(1)__name">\r
  10 <title>NAME</title>\r
  11 <simpara>git-check-ref-format - Ensures that a reference name is well formed</simpara>\r
  12 </simplesect>\r
  13 <simplesect id="git-check-ref-format(1)__synopsis">\r
  14 <title>SYNOPSIS</title>\r
  15 <blockquote>\r
  16 <literallayout><emphasis>git check-ref-format</emphasis> [--normalize]\r
  17        [--[no-]allow-onelevel] [--refspec-pattern]\r
  18        &lt;refname&gt;\r
  19 <emphasis>git check-ref-format</emphasis> --branch &lt;branchname-shorthand&gt;</literallayout>\r
  20 </blockquote>\r
  21 </simplesect>\r
  22 <simplesect id="git-check-ref-format(1)__description">\r
  23 <title>DESCRIPTION</title>\r
  24 <simpara>Checks if a given <emphasis>refname</emphasis> is acceptable, and exits with a non-zero\r
  25 status if it is not.</simpara>\r
  26 <simpara>A reference is used in Git to specify branches and tags.  A\r
  27 branch head is stored in the <emphasis>refs/heads</emphasis> hierarchy, while\r
  28 a tag is stored in the <emphasis>refs/tags</emphasis> hierarchy of the ref namespace\r
  29 (typically in <emphasis>$GIT_DIR/refs/heads</emphasis> and <emphasis>$GIT_DIR/refs/tags</emphasis>\r
  30 directories or, as entries in file <emphasis>$GIT_DIR/packed-refs</emphasis>\r
  31 if refs are packed by <emphasis>git gc</emphasis>).</simpara>\r
  32 <simpara>Git imposes the following rules on how references are named:</simpara>\r
  33 <orderedlist numeration="arabic">\r
  34 <listitem>\r
  35 <simpara>\r
  36 They can include slash <emphasis>/</emphasis> for hierarchical (directory)\r
  37   grouping, but no slash-separated component can begin with a\r
  38   dot <emphasis>.</emphasis> or end with the sequence <emphasis>.lock</emphasis>.\r
  39 </simpara>\r
  40 </listitem>\r
  41 <listitem>\r
  42 <simpara>\r
  43 They must contain at least one <emphasis>/</emphasis>. This enforces the presence of a\r
  44   category like <emphasis>heads/</emphasis>, <emphasis>tags/</emphasis> etc. but the actual names are not\r
  45   restricted.  If the <emphasis>--allow-onelevel</emphasis> option is used, this rule\r
  46   is waived.\r
  47 </simpara>\r
  48 </listitem>\r
  49 <listitem>\r
  50 <simpara>\r
  51 They cannot have two consecutive dots <emphasis>..</emphasis> anywhere.\r
  52 </simpara>\r
  53 </listitem>\r
  54 <listitem>\r
  55 <simpara>\r
  56 They cannot have ASCII control characters (i.e. bytes whose\r
  57   values are lower than \040, or \177 <emphasis>DEL</emphasis>), space, tilde <emphasis>~</emphasis>,\r
  58   caret <emphasis>^</emphasis>, or colon <emphasis>:</emphasis> anywhere.\r
  59 </simpara>\r
  60 </listitem>\r
  61 <listitem>\r
  62 <simpara>\r
  63 They cannot have question-mark <emphasis>?</emphasis>, asterisk <emphasis>*</emphasis>, or open\r
  64   bracket <emphasis>[</emphasis> anywhere.  See the <emphasis>--refspec-pattern</emphasis> option below for\r
  65   an exception to this rule.\r
  66 </simpara>\r
  67 </listitem>\r
  68 <listitem>\r
  69 <simpara>\r
  70 They cannot begin or end with a slash <emphasis>/</emphasis> or contain multiple\r
  71   consecutive slashes (see the <emphasis>--normalize</emphasis> option below for an\r
  72   exception to this rule)\r
  73 </simpara>\r
  74 </listitem>\r
  75 <listitem>\r
  76 <simpara>\r
  77 They cannot end with a dot <emphasis>.</emphasis>.\r
  78 </simpara>\r
  79 </listitem>\r
  80 <listitem>\r
  81 <simpara>\r
  82 They cannot contain a sequence <emphasis>@{</emphasis>.\r
  83 </simpara>\r
  84 </listitem>\r
  85 <listitem>\r
  86 <simpara>\r
  87 They cannot be the single character <emphasis>@</emphasis>.\r
  88 </simpara>\r
  89 </listitem>\r
  90 <listitem>\r
  91 <simpara>\r
  92 They cannot contain a <emphasis>\</emphasis>.\r
  93 </simpara>\r
  94 </listitem>\r
  95 </orderedlist>\r
  96 <simpara>These rules make it easy for shell script based tools to parse\r
  97 reference names, pathname expansion by the shell when a reference name is used\r
  98 unquoted (by mistake), and also avoid ambiguities in certain\r
  99 reference name expressions (see <xref linkend="gitrevisions(7)" />):</simpara>\r
 100 <orderedlist numeration="arabic">\r
 101 <listitem>\r
 102 <simpara>\r
 103 A double-dot <emphasis>..</emphasis> is often used as in <emphasis>ref1..ref2</emphasis>, and in some\r
 104   contexts this notation means <emphasis>^ref1 ref2</emphasis> (i.e. not in\r
 105   <emphasis>ref1</emphasis> and in <emphasis>ref2</emphasis>).\r
 106 </simpara>\r
 107 </listitem>\r
 108 <listitem>\r
 109 <simpara>\r
 110 A tilde <emphasis>~</emphasis> and caret <emphasis>^</emphasis> are used to introduce the postfix\r
 111   <emphasis>nth parent</emphasis> and <emphasis>peel onion</emphasis> operation.\r
 112 </simpara>\r
 113 </listitem>\r
 114 <listitem>\r
 115 <simpara>\r
 116 A colon <emphasis>:</emphasis> is used as in <emphasis>srcref:dstref</emphasis> to mean "use srcref's\r
 117   value and store it in dstref" in fetch and push operations.\r
 118   It may also be used to select a specific object such as with\r
 119   <emphasis>git cat-file</emphasis>: "git cat-file blob v1.3.3:refs.c".\r
 120 </simpara>\r
 121 </listitem>\r
 122 <listitem>\r
 123 <simpara>\r
 124 at-open-brace <emphasis>@{</emphasis> is used as a notation to access a reflog entry.\r
 125 </simpara>\r
 126 </listitem>\r
 127 </orderedlist>\r
 128 <simpara>With the <emphasis>--branch</emphasis> option, it expands the previous branch syntax\r
 129 <emphasis>@{-n}</emphasis>.  For example, <emphasis>@{-1}</emphasis> is a way to refer the last branch you\r
 130 were on.  This option should be used by porcelains to accept this\r
 131 syntax anywhere a branch name is expected, so they can act as if you\r
 132 typed the branch name.</simpara>\r
 133 </simplesect>\r
 134 <simplesect id="git-check-ref-format(1)__options">\r
 135 <title>OPTIONS</title>\r
 136 <variablelist>\r
 137 <varlistentry>\r
 138 <term>\r
 139 --[no-]allow-onelevel\r
 140 </term>\r
 141 <listitem>\r
 142 <simpara>\r
 143         Controls whether one-level refnames are accepted (i.e.,\r
 144         refnames that do not contain multiple <emphasis>/</emphasis>-separated\r
 145         components).  The default is <emphasis>--no-allow-onelevel</emphasis>.\r
 146 </simpara>\r
 147 </listitem>\r
 148 </varlistentry>\r
 149 <varlistentry>\r
 150 <term>\r
 151 --refspec-pattern\r
 152 </term>\r
 153 <listitem>\r
 154 <simpara>\r
 155         Interpret &lt;refname&gt; as a reference name pattern for a refspec\r
 156         (as used with remote repositories).  If this option is\r
 157         enabled, &lt;refname&gt; is allowed to contain a single <emphasis>*</emphasis>\r
 158         in the refspec (e.g., <emphasis>foo/bar*/baz</emphasis> or <emphasis>foo/bar*baz/</emphasis>\r
 159         but not <emphasis>foo/bar*/baz*</emphasis>).\r
 160 </simpara>\r
 161 </listitem>\r
 162 </varlistentry>\r
 163 <varlistentry>\r
 164 <term>\r
 165 --normalize\r
 166 </term>\r
 167 <listitem>\r
 168 <simpara>\r
 169         Normalize <emphasis>refname</emphasis> by removing any leading slash (<emphasis>/</emphasis>)\r
 170         characters and collapsing runs of adjacent slashes between\r
 171         name components into a single slash.  Iff the normalized\r
 172         refname is valid then print it to standard output and exit\r
 173         with a status of 0.  (<emphasis>--print</emphasis> is a deprecated way to spell\r
 174         <emphasis>--normalize</emphasis>.)\r
 175 </simpara>\r
 176 </listitem>\r
 177 </varlistentry>\r
 178 </variablelist>\r
 179 </simplesect>\r
 180 <simplesect id="git-check-ref-format(1)__examples">\r
 181 <title>EXAMPLES</title>\r
 182 <itemizedlist>\r
 183 <listitem>\r
 184 <simpara>\r
 185 Print the name of the previous branch:\r
 186 </simpara>\r
 187 <screen>$ git check-ref-format --branch @{-1}</screen>\r
 188 </listitem>\r
 189 <listitem>\r
 190 <simpara>\r
 191 Determine the reference name to use for a new branch:\r
 192 </simpara>\r
 193 <screen>$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch") ||\r
 194 die "we do not like '$newbranch' as a branch name."</screen>\r
 195 </listitem>\r
 196 </itemizedlist>\r
 197 </simplesect>\r
 198 <simplesect id="git-check-ref-format(1)__git">\r
 199 <title>GIT</title>\r
 200 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
 201 </simplesect>\r
 202 </sect2>\r