man1/git-check-ref-format.1

   1 '\" t
   2 .\"     Title: git-check-ref-format
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2023-06-01
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.41.0
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-CHECK\-REF\-FORMAT" "1" "2023\-06\-01" "Git 2\&.41\&.0" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-check-ref-format \- Ensures that a reference name is well formed
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit check\-ref\-format\fR [\-\-normalize]
  36        [\-\-[no\-]allow\-onelevel] [\-\-refspec\-pattern]
  37        <refname>
  38 \fIgit check\-ref\-format\fR \-\-branch <branchname\-shorthand>
  39 .fi
  40 .sp
  41 .SH "DESCRIPTION"
  42 .sp
  43 Checks if a given \fIrefname\fR is acceptable, and exits with a non\-zero status if it is not\&.
  44 .sp
  45 A reference is used in Git to specify branches and tags\&. 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 gc\fR)\&.
  46 .sp
  47 Git imposes the following rules on how references are named:
  48 .sp
  49 .RS 4
  50 .ie n \{\
  51 \h'-04' 1.\h'+01'\c
  52 .\}
  53 .el \{\
  54 .sp -1
  55 .IP "  1." 4.2
  56 .\}
  57 They can include slash
  58 \fB/\fR
  59 for hierarchical (directory) grouping, but no slash\-separated component can begin with a dot
  60 \fB\&.\fR
  61 or end with the sequence
  62 \fB\&.lock\fR\&.
  63 .RE
  64 .sp
  65 .RS 4
  66 .ie n \{\
  67 \h'-04' 2.\h'+01'\c
  68 .\}
  69 .el \{\
  70 .sp -1
  71 .IP "  2." 4.2
  72 .\}
  73 They must contain at least one
  74 \fB/\fR\&. This enforces the presence of a category like
  75 \fBheads/\fR,
  76 \fBtags/\fR
  77 etc\&. but the actual names are not restricted\&. If the
  78 \fB\-\-allow\-onelevel\fR
  79 option is used, this rule is waived\&.
  80 .RE
  81 .sp
  82 .RS 4
  83 .ie n \{\
  84 \h'-04' 3.\h'+01'\c
  85 .\}
  86 .el \{\
  87 .sp -1
  88 .IP "  3." 4.2
  89 .\}
  90 They cannot have two consecutive dots
  91 \fB\&.\&.\fR
  92 anywhere\&.
  93 .RE
  94 .sp
  95 .RS 4
  96 .ie n \{\
  97 \h'-04' 4.\h'+01'\c
  98 .\}
  99 .el \{\
 100 .sp -1
 101 .IP "  4." 4.2
 102 .\}
 103 They cannot have ASCII control characters (i\&.e\&. bytes whose values are lower than \e040, or \e177
 104 \fBDEL\fR), space, tilde
 105 \fB~\fR, caret
 106 \fB^\fR, or colon
 107 \fB:\fR
 108 anywhere\&.
 109 .RE
 110 .sp
 111 .RS 4
 112 .ie n \{\
 113 \h'-04' 5.\h'+01'\c
 114 .\}
 115 .el \{\
 116 .sp -1
 117 .IP "  5." 4.2
 118 .\}
 119 They cannot have question\-mark
 120 \fB?\fR, asterisk
 121 \fB*\fR, or open bracket
 122 \fB[\fR
 123 anywhere\&. See the
 124 \fB\-\-refspec\-pattern\fR
 125 option below for an exception to this rule\&.
 126 .RE
 127 .sp
 128 .RS 4
 129 .ie n \{\
 130 \h'-04' 6.\h'+01'\c
 131 .\}
 132 .el \{\
 133 .sp -1
 134 .IP "  6." 4.2
 135 .\}
 136 They cannot begin or end with a slash
 137 \fB/\fR
 138 or contain multiple consecutive slashes (see the
 139 \fB\-\-normalize\fR
 140 option below for an exception to this rule)
 141 .RE
 142 .sp
 143 .RS 4
 144 .ie n \{\
 145 \h'-04' 7.\h'+01'\c
 146 .\}
 147 .el \{\
 148 .sp -1
 149 .IP "  7." 4.2
 150 .\}
 151 They cannot end with a dot
 152 \fB\&.\fR\&.
 153 .RE
 154 .sp
 155 .RS 4
 156 .ie n \{\
 157 \h'-04' 8.\h'+01'\c
 158 .\}
 159 .el \{\
 160 .sp -1
 161 .IP "  8." 4.2
 162 .\}
 163 They cannot contain a sequence
 164 \fB@{\fR\&.
 165 .RE
 166 .sp
 167 .RS 4
 168 .ie n \{\
 169 \h'-04' 9.\h'+01'\c
 170 .\}
 171 .el \{\
 172 .sp -1
 173 .IP "  9." 4.2
 174 .\}
 175 They cannot be the single character
 176 \fB@\fR\&.
 177 .RE
 178 .sp
 179 .RS 4
 180 .ie n \{\
 181 \h'-04'10.\h'+01'\c
 182 .\}
 183 .el \{\
 184 .sp -1
 185 .IP "10." 4.2
 186 .\}
 187 They cannot contain a
 188 \fB\e\fR\&.
 189 .RE
 190 .sp
 191 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)):
 192 .sp
 193 .RS 4
 194 .ie n \{\
 195 \h'-04' 1.\h'+01'\c
 196 .\}
 197 .el \{\
 198 .sp -1
 199 .IP "  1." 4.2
 200 .\}
 201 A double\-dot
 202 \fB\&.\&.\fR
 203 is often used as in
 204 \fBref1\&.\&.ref2\fR, and in some contexts this notation means
 205 \fB^ref1 ref2\fR
 206 (i\&.e\&. not in
 207 \fBref1\fR
 208 and in
 209 \fBref2\fR)\&.
 210 .RE
 211 .sp
 212 .RS 4
 213 .ie n \{\
 214 \h'-04' 2.\h'+01'\c
 215 .\}
 216 .el \{\
 217 .sp -1
 218 .IP "  2." 4.2
 219 .\}
 220 A tilde
 221 \fB~\fR
 222 and caret
 223 \fB^\fR
 224 are used to introduce the postfix
 225 \fInth parent\fR
 226 and
 227 \fIpeel onion\fR
 228 operation\&.
 229 .RE
 230 .sp
 231 .RS 4
 232 .ie n \{\
 233 \h'-04' 3.\h'+01'\c
 234 .\}
 235 .el \{\
 236 .sp -1
 237 .IP "  3." 4.2
 238 .\}
 239 A colon
 240 \fB:\fR
 241 is used as in
 242 \fBsrcref:dstref\fR
 243 to mean "use srcref\(cqs value and store it in dstref" in fetch and push operations\&. It may also be used to select a specific object such as with
 244 \fIgit cat\-file\fR: "git cat\-file blob v1\&.3\&.3:refs\&.c"\&.
 245 .RE
 246 .sp
 247 .RS 4
 248 .ie n \{\
 249 \h'-04' 4.\h'+01'\c
 250 .\}
 251 .el \{\
 252 .sp -1
 253 .IP "  4." 4.2
 254 .\}
 255 at\-open\-brace
 256 \fB@{\fR
 257 is used as a notation to access a reflog entry\&.
 258 .RE
 259 .sp
 260 With the \fB\-\-branch\fR 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 \fBgit check\-ref\-format \-\-branch $name\fR implements may be stricter than what \fBgit check\-ref\-format refs/heads/$name\fR 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 \fB\-\-branch\fR option in a repository, the input is first expanded for the \(lqprevious checkout syntax\(rq \fB@{\-n}\fR\&. For example, \fB@{\-1}\fR 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 \(lqprevious checkout operation\(rq might result in a commit object name when the N\-th last thing checked out was not a branch\&.
 261 .SH "OPTIONS"
 262 .PP
 263 \-\-[no\-]allow\-onelevel
 264 .RS 4
 265 Controls whether one\-level refnames are accepted (i\&.e\&., refnames that do not contain multiple
 266 \fB/\fR\-separated components)\&. The default is
 267 \fB\-\-no\-allow\-onelevel\fR\&.
 268 .RE
 269 .PP
 270 \-\-refspec\-pattern
 271 .RS 4
 272 Interpret <refname> as a reference name pattern for a refspec (as used with remote repositories)\&. If this option is enabled, <refname> is allowed to contain a single
 273 \fB*\fR
 274 in the refspec (e\&.g\&.,
 275 \fBfoo/bar*/baz\fR
 276 or
 277 \fBfoo/bar*baz/\fR
 278 but not
 279 \fBfoo/bar*/baz*\fR)\&.
 280 .RE
 281 .PP
 282 \-\-normalize
 283 .RS 4
 284 Normalize
 285 \fIrefname\fR
 286 by removing any leading slash (\fB/\fR) 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\&. (\fB\-\-print\fR
 287 is a deprecated way to spell
 288 \fB\-\-normalize\fR\&.)
 289 .RE
 290 .SH "EXAMPLES"
 291 .sp
 292 .RS 4
 293 .ie n \{\
 294 \h'-04'\(bu\h'+03'\c
 295 .\}
 296 .el \{\
 297 .sp -1
 298 .IP \(bu 2.3
 299 .\}
 300 Print the name of the previous thing checked out:
 301 .sp
 302 .if n \{\
 303 .RS 4
 304 .\}
 305 .nf
 306 $ git check\-ref\-format \-\-branch @{\-1}
 307 .fi
 308 .if n \{\
 309 .RE
 310 .\}
 311 .sp
 312 .RE
 313 .sp
 314 .RS 4
 315 .ie n \{\
 316 \h'-04'\(bu\h'+03'\c
 317 .\}
 318 .el \{\
 319 .sp -1
 320 .IP \(bu 2.3
 321 .\}
 322 Determine the reference name to use for a new branch:
 323 .sp
 324 .if n \{\
 325 .RS 4
 326 .\}
 327 .nf
 328 $ ref=$(git check\-ref\-format \-\-normalize "refs/heads/$newbranch")||
 329 { echo "we do not like \*(Aq$newbranch\*(Aq as a branch name\&." >&2 ; exit 1 ; }
 330 .fi
 331 .if n \{\
 332 .RE
 333 .\}
 334 .sp
 335 .RE
 336 .SH "GIT"
 337 .sp
 338 Part of the \fBgit\fR(1) suite