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

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.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, the command takes a name and checks if\r
 129 it can be used as a valid branch name (e.g. when creating a new\r
 130 branch). But be cautious when using the\r
 131 previous checkout syntax that may refer to a detached HEAD state.\r
 132 The rule <emphasis>git check-ref-format --branch $name</emphasis> implements\r
 133 may be stricter than what <emphasis>git check-ref-format refs/heads/$name</emphasis>\r
 134 says (e.g. a dash may appear at the beginning of a ref component,\r
 135 but it is explicitly forbidden at the beginning of a branch name).\r
 136 When run with <emphasis>--branch</emphasis> option in a repository, the input is first\r
 137 expanded for the previous checkout syntax\r
 138 <emphasis>@{-n}</emphasis>.  For example, <emphasis>@{-1}</emphasis> is a way to refer the last thing that\r
 139 was checked out using "git switch" or "git checkout" operation.\r
 140 This option should be\r
 141 used by porcelains to accept this syntax anywhere a branch name is\r
 142 expected, so they can act as if you typed the branch name. As an\r
 143 exception note that, the previous checkout operation might result\r
 144 in a commit object name when the N-th last thing checked out was not\r
 145 a branch.</simpara>\r
 146 </simplesect>\r
 147 <simplesect id="git-check-ref-format(1)__options">\r
 148 <title>OPTIONS</title>\r
 149 <variablelist>\r
 150 <varlistentry>\r
 151 <term>\r
 152 --[no-]allow-onelevel\r
 153 </term>\r
 154 <listitem>\r
 155 <simpara>\r
 156         Controls whether one-level refnames are accepted (i.e.,\r
 157         refnames that do not contain multiple <emphasis>/</emphasis>-separated\r
 158         components).  The default is <emphasis>--no-allow-onelevel</emphasis>.\r
 159 </simpara>\r
 160 </listitem>\r
 161 </varlistentry>\r
 162 <varlistentry>\r
 163 <term>\r
 164 --refspec-pattern\r
 165 </term>\r
 166 <listitem>\r
 167 <simpara>\r
 168         Interpret &lt;refname&gt; as a reference name pattern for a refspec\r
 169         (as used with remote repositories).  If this option is\r
 170         enabled, &lt;refname&gt; is allowed to contain a single <emphasis>*</emphasis>\r
 171         in the refspec (e.g., <emphasis>foo/bar*/baz</emphasis> or <emphasis>foo/bar*baz/</emphasis>\r
 172         but not <emphasis>foo/bar*/baz*</emphasis>).\r
 173 </simpara>\r
 174 </listitem>\r
 175 </varlistentry>\r
 176 <varlistentry>\r
 177 <term>\r
 178 --normalize\r
 179 </term>\r
 180 <listitem>\r
 181 <simpara>\r
 182         Normalize <emphasis>refname</emphasis> by removing any leading slash (<emphasis>/</emphasis>)\r
 183         characters and collapsing runs of adjacent slashes between\r
 184         name components into a single slash.  If the normalized\r
 185         refname is valid then print it to standard output and exit\r
 186         with a status of 0, otherwise exit with a non-zero status.\r
 187         (<emphasis>--print</emphasis> is a deprecated way to spell <emphasis>--normalize</emphasis>.)\r
 188 </simpara>\r
 189 </listitem>\r
 190 </varlistentry>\r
 191 </variablelist>\r
 192 </simplesect>\r
 193 <simplesect id="git-check-ref-format(1)__examples">\r
 194 <title>EXAMPLES</title>\r
 195 <itemizedlist>\r
 196 <listitem>\r
 197 <simpara>\r
 198 Print the name of the previous thing checked out:\r
 199 </simpara>\r
 200 <screen>$ git check-ref-format --branch @{-1}</screen>\r
 201 </listitem>\r
 202 <listitem>\r
 203 <simpara>\r
 204 Determine the reference name to use for a new branch:\r
 205 </simpara>\r
 206 <screen>$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch")||\r
 207 { echo "we do not like '$newbranch' as a branch name." &gt;&amp;2 ; exit 1 ; }</screen>\r
 208 </listitem>\r
 209 </itemizedlist>\r
 210 </simplesect>\r
 211 <simplesect id="git-check-ref-format(1)__git">\r
 212 <title>GIT</title>\r
 213 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
 214 </simplesect>\r
 215 </sect2>\r