logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

git-check-ref-format.1 (8004B)


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