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 v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-09-30
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.47.0.rc0.18.ge9356ba3ea
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-CHECK\-REF\-FORMAT" "1" "2024-09-30" "Git 2\&.47\&.0\&.rc0\&.18\&.ge" "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 .SH "DESCRIPTION"
  41 .sp
  42 Checks if a given \fIrefname\fR is acceptable, and exits with a non\-zero status if it is not\&.
  43 .sp
  44 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)\&.
  45 .sp
  46 Git imposes the following rules on how references are named:
  47 .sp
  48 .RS 4
  49 .ie n \{\
  50 \h'-04' 1.\h'+01'\c
  51 .\}
  52 .el \{\
  53 .sp -1
  54 .IP "  1." 4.2
  55 .\}
  56 They can include slash
  57 \fB/\fR
  58 for hierarchical (directory) grouping, but no slash\-separated component can begin with a dot
  59 \fB\&.\fR
  60 or end with the sequence
  61 \fB\&.lock\fR\&.
  62 .RE
  63 .sp
  64 .RS 4
  65 .ie n \{\
  66 \h'-04' 2.\h'+01'\c
  67 .\}
  68 .el \{\
  69 .sp -1
  70 .IP "  2." 4.2
  71 .\}
  72 They must contain at least one
  73 \fB/\fR\&. This enforces the presence of a category like
  74 \fBheads/\fR,
  75 \fBtags/\fR
  76 etc\&. but the actual names are not restricted\&. If the
  77 \fB\-\-allow\-onelevel\fR
  78 option is used, this rule is waived\&.
  79 .RE
  80 .sp
  81 .RS 4
  82 .ie n \{\
  83 \h'-04' 3.\h'+01'\c
  84 .\}
  85 .el \{\
  86 .sp -1
  87 .IP "  3." 4.2
  88 .\}
  89 They cannot have two consecutive dots
  90 \fB\&.\&.\fR
  91 anywhere\&.
  92 .RE
  93 .sp
  94 .RS 4
  95 .ie n \{\
  96 \h'-04' 4.\h'+01'\c
  97 .\}
  98 .el \{\
  99 .sp -1
 100 .IP "  4." 4.2
 101 .\}
 102 They cannot have ASCII control characters (i\&.e\&. bytes whose values are lower than \e040, or \e177
 103 \fBDEL\fR), space, tilde
 104 \fB~\fR, caret
 105 \fB^\fR, or colon
 106 \fB:\fR
 107 anywhere\&.
 108 .RE
 109 .sp
 110 .RS 4
 111 .ie n \{\
 112 \h'-04' 5.\h'+01'\c
 113 .\}
 114 .el \{\
 115 .sp -1
 116 .IP "  5." 4.2
 117 .\}
 118 They cannot have question\-mark
 119 \fB?\fR, asterisk
 120 \fB*\fR, or open bracket
 121 \fB[\fR
 122 anywhere\&. See the
 123 \fB\-\-refspec\-pattern\fR
 124 option below for an exception to this rule\&.
 125 .RE
 126 .sp
 127 .RS 4
 128 .ie n \{\
 129 \h'-04' 6.\h'+01'\c
 130 .\}
 131 .el \{\
 132 .sp -1
 133 .IP "  6." 4.2
 134 .\}
 135 They cannot begin or end with a slash
 136 \fB/\fR
 137 or contain multiple consecutive slashes (see the
 138 \fB\-\-normalize\fR
 139 option below for an exception to this rule)\&.
 140 .RE
 141 .sp
 142 .RS 4
 143 .ie n \{\
 144 \h'-04' 7.\h'+01'\c
 145 .\}
 146 .el \{\
 147 .sp -1
 148 .IP "  7." 4.2
 149 .\}
 150 They cannot end with a dot
 151 \fB\&.\fR\&.
 152 .RE
 153 .sp
 154 .RS 4
 155 .ie n \{\
 156 \h'-04' 8.\h'+01'\c
 157 .\}
 158 .el \{\
 159 .sp -1
 160 .IP "  8." 4.2
 161 .\}
 162 They cannot contain a sequence
 163 \fB@{\fR\&.
 164 .RE
 165 .sp
 166 .RS 4
 167 .ie n \{\
 168 \h'-04' 9.\h'+01'\c
 169 .\}
 170 .el \{\
 171 .sp -1
 172 .IP "  9." 4.2
 173 .\}
 174 They cannot be the single character
 175 \fB@\fR\&.
 176 .RE
 177 .sp
 178 .RS 4
 179 .ie n \{\
 180 \h'-04'10.\h'+01'\c
 181 .\}
 182 .el \{\
 183 .sp -1
 184 .IP "10." 4.2
 185 .\}
 186 They cannot contain a
 187 \fB\e\fR\&.
 188 .RE
 189 .sp
 190 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)):
 191 .sp
 192 .RS 4
 193 .ie n \{\
 194 \h'-04' 1.\h'+01'\c
 195 .\}
 196 .el \{\
 197 .sp -1
 198 .IP "  1." 4.2
 199 .\}
 200 A double\-dot
 201 \fB\&.\&.\fR
 202 is often used as in
 203 \fBref1\&.\&.ref2\fR, and in some contexts this notation means
 204 \fB^ref1 ref2\fR
 205 (i\&.e\&. not in
 206 \fBref1\fR
 207 and in
 208 \fBref2\fR)\&.
 209 .RE
 210 .sp
 211 .RS 4
 212 .ie n \{\
 213 \h'-04' 2.\h'+01'\c
 214 .\}
 215 .el \{\
 216 .sp -1
 217 .IP "  2." 4.2
 218 .\}
 219 A tilde
 220 \fB~\fR
 221 and caret
 222 \fB^\fR
 223 are used to introduce the postfix
 224 \fInth parent\fR
 225 and
 226 \fIpeel onion\fR
 227 operation\&.
 228 .RE
 229 .sp
 230 .RS 4
 231 .ie n \{\
 232 \h'-04' 3.\h'+01'\c
 233 .\}
 234 .el \{\
 235 .sp -1
 236 .IP "  3." 4.2
 237 .\}
 238 A colon
 239 \fB:\fR
 240 is used as in
 241 \fBsrcref:dstref\fR
 242 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 \*(Aqgit cat\-file\*(Aq: "git cat\-file blob v1\&.3\&.3:refs\&.c"\&.
 243 .RE
 244 .sp
 245 .RS 4
 246 .ie n \{\
 247 \h'-04' 4.\h'+01'\c
 248 .\}
 249 .el \{\
 250 .sp -1
 251 .IP "  4." 4.2
 252 .\}
 253 at\-open\-brace
 254 \fB@{\fR
 255 is used as a notation to access a reflog entry\&.
 256 .RE
 257 .sp
 258 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 the \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\&.
 259 .SH "OPTIONS"
 260 .PP
 261 \-\-[no\-]allow\-onelevel
 262 .RS 4
 263 Controls whether one\-level refnames are accepted (i\&.e\&., refnames that do not contain multiple
 264 \fB/\fR\-separated components)\&. The default is
 265 \fB\-\-no\-allow\-onelevel\fR\&.
 266 .RE
 267 .PP
 268 \-\-refspec\-pattern
 269 .RS 4
 270 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
 271 \fB*\fR
 272 in the refspec (e\&.g\&.,
 273 \fBfoo/bar*/baz\fR
 274 or
 275 \fBfoo/bar*baz/\fR
 276 but not
 277 \fBfoo/bar*/baz*\fR)\&.
 278 .RE
 279 .PP
 280 \-\-normalize
 281 .RS 4
 282 Normalize
 283 \fIrefname\fR
 284 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
 285 is a deprecated way to spell
 286 \fB\-\-normalize\fR\&.)
 287 .RE
 288 .SH "EXAMPLES"
 289 .sp
 290 .RS 4
 291 .ie n \{\
 292 \h'-04'\(bu\h'+03'\c
 293 .\}
 294 .el \{\
 295 .sp -1
 296 .IP \(bu 2.3
 297 .\}
 298 Print the name of the previous thing checked out:
 299 .sp
 300 .if n \{\
 301 .RS 4
 302 .\}
 303 .nf
 304 $ git check\-ref\-format \-\-branch @{\-1}
 305 .fi
 306 .if n \{\
 307 .RE
 308 .\}
 309 .RE
 310 .sp
 311 .RS 4
 312 .ie n \{\
 313 \h'-04'\(bu\h'+03'\c
 314 .\}
 315 .el \{\
 316 .sp -1
 317 .IP \(bu 2.3
 318 .\}
 319 Determine the reference name to use for a new branch:
 320 .sp
 321 .if n \{\
 322 .RS 4
 323 .\}
 324 .nf
 325 $ ref=$(git check\-ref\-format \-\-normalize "refs/heads/$newbranch")||
 326 { echo "we do not like \*(Aq$newbranch\*(Aq as a branch name\&." >&2 ; exit 1 ; }
 327 .fi
 328 .if n \{\
 329 .RE
 330 .\}
 331 .RE
 332 .SH "GIT"
 333 .sp
 334 Part of the \fBgit\fR(1) suite