| '\" t |
| .\" Title: git-check-ref-format |
| .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] |
| .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> |
| .\" Date: 02/19/2019 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.21.0.rc2 |
| .\" Language: English |
| .\" |
| .TH "GIT\-CHECK\-REF\-FOR" "1" "02/19/2019" "Git 2\&.21\&.0\&.rc2" "Git Manual" |
| .\" ----------------------------------------------------------------- |
| .\" * Define some portability stuff |
| .\" ----------------------------------------------------------------- |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .\" http://bugs.debian.org/507673 |
| .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .\" ----------------------------------------------------------------- |
| .\" * set default formatting |
| .\" ----------------------------------------------------------------- |
| .\" disable hyphenation |
| .nh |
| .\" disable justification (adjust text to left margin only) |
| .ad l |
| .\" ----------------------------------------------------------------- |
| .\" * MAIN CONTENT STARTS HERE * |
| .\" ----------------------------------------------------------------- |
| .SH "NAME" |
| git-check-ref-format \- Ensures that a reference name is well formed |
| .SH "SYNOPSIS" |
| .sp |
| .nf |
| \fIgit check\-ref\-format\fR [\-\-normalize] |
| [\-\-[no\-]allow\-onelevel] [\-\-refspec\-pattern] |
| <refname> |
| \fIgit check\-ref\-format\fR \-\-branch <branchname\-shorthand> |
| .fi |
| .sp |
| .SH "DESCRIPTION" |
| .sp |
| Checks if a given \fIrefname\fR is acceptable, and exits with a non\-zero status if it is not\&. |
| .sp |
| 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)\&. |
| .sp |
| Git imposes the following rules on how references are named: |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 1.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 1." 4.2 |
| .\} |
| They can include slash |
| \fB/\fR |
| for hierarchical (directory) grouping, but no slash\-separated component can begin with a dot |
| \fB\&.\fR |
| or end with the sequence |
| \fB\&.lock\fR\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 2.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 2." 4.2 |
| .\} |
| They must contain at least one |
| \fB/\fR\&. This enforces the presence of a category like |
| \fBheads/\fR, |
| \fBtags/\fR |
| etc\&. but the actual names are not restricted\&. If the |
| \fB\-\-allow\-onelevel\fR |
| option is used, this rule is waived\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 3.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 3." 4.2 |
| .\} |
| They cannot have two consecutive dots |
| \fB\&.\&.\fR |
| anywhere\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 4.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 4." 4.2 |
| .\} |
| They cannot have ASCII control characters (i\&.e\&. bytes whose values are lower than \e040, or \e177 |
| \fBDEL\fR), space, tilde |
| \fB~\fR, caret |
| \fB^\fR, or colon |
| \fB:\fR |
| anywhere\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 5.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 5." 4.2 |
| .\} |
| They cannot have question\-mark |
| \fB?\fR, asterisk |
| \fB*\fR, or open bracket |
| \fB[\fR |
| anywhere\&. See the |
| \fB\-\-refspec\-pattern\fR |
| option below for an exception to this rule\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 6.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 6." 4.2 |
| .\} |
| They cannot begin or end with a slash |
| \fB/\fR |
| or contain multiple consecutive slashes (see the |
| \fB\-\-normalize\fR |
| option below for an exception to this rule) |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 7.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 7." 4.2 |
| .\} |
| They cannot end with a dot |
| \fB\&.\fR\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 8.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 8." 4.2 |
| .\} |
| They cannot contain a sequence |
| \fB@{\fR\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 9.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 9." 4.2 |
| .\} |
| They cannot be the single character |
| \fB@\fR\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'10.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP "10." 4.2 |
| .\} |
| They cannot contain a |
| \fB\e\fR\&. |
| .RE |
| .sp |
| 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)): |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 1.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 1." 4.2 |
| .\} |
| A double\-dot |
| \fB\&.\&.\fR |
| is often used as in |
| \fBref1\&.\&.ref2\fR, and in some contexts this notation means |
| \fB^ref1 ref2\fR |
| (i\&.e\&. not in |
| \fBref1\fR |
| and in |
| \fBref2\fR)\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 2.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 2." 4.2 |
| .\} |
| A tilde |
| \fB~\fR |
| and caret |
| \fB^\fR |
| are used to introduce the postfix |
| \fInth parent\fR |
| and |
| \fIpeel onion\fR |
| operation\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 3.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 3." 4.2 |
| .\} |
| A colon |
| \fB:\fR |
| is used as in |
| \fBsrcref:dstref\fR |
| 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 |
| \fIgit cat\-file\fR: "git cat\-file blob v1\&.3\&.3:refs\&.c"\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 4.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 4." 4.2 |
| .\} |
| at\-open\-brace |
| \fB@{\fR |
| is used as a notation to access a reflog entry\&. |
| .RE |
| .sp |
| 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 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\&. |
| .SH "OPTIONS" |
| .PP |
| \-\-[no\-]allow\-onelevel |
| .RS 4 |
| Controls whether one\-level refnames are accepted (i\&.e\&., refnames that do not contain multiple |
| \fB/\fR\-separated components)\&. The default is |
| \fB\-\-no\-allow\-onelevel\fR\&. |
| .RE |
| .PP |
| \-\-refspec\-pattern |
| .RS 4 |
| 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 |
| \fB*\fR |
| in the refspec (e\&.g\&., |
| \fBfoo/bar*/baz\fR |
| or |
| \fBfoo/bar*baz/\fR |
| but not |
| \fBfoo/bar*/baz*\fR)\&. |
| .RE |
| .PP |
| \-\-normalize |
| .RS 4 |
| Normalize |
| \fIrefname\fR |
| 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 |
| is a deprecated way to spell |
| \fB\-\-normalize\fR\&.) |
| .RE |
| .SH "EXAMPLES" |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| Print the name of the previous thing checked out: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $ git check\-ref\-format \-\-branch @{\-1} |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| Determine the reference name to use for a new branch: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $ ref=$(git check\-ref\-format \-\-normalize "refs/heads/$newbranch")|| |
| { echo "we do not like \(aq$newbranch\(aq as a branch name\&." >&2 ; exit 1 ; } |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .RE |
| .SH "GIT" |
| .sp |
| Part of the \fBgit\fR(1) suite |