git-check-ref-format.1   [plain text]

'\" t
.\"     Title: git-check-ref-format
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 04/06/2011
.\"    Manual: Git Manual
.\"    Source: Git 1.7.4.4
.\"  Language: English
.\"
.TH "GIT\-CHECK\-REF\-FOR" "1" "04/06/2011" "Git 1\&.7\&.4\&.4" "Git Manual"
.\" -----------------------------------------------------------------
.\" * 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 <refname>
\fIgit check\-ref\-format\fR \-\-print <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 under the $GIT_DIR/refs/heads directory, and a tag is stored under the $GIT_DIR/refs/tags directory (or, if refs are packed by git gc, as entries in the $GIT_DIR/packed\-refs file)\&. 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
/
for hierarchical (directory) grouping, but no slash\-separated component can begin with a dot
\&.\&.
.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
/\&. This enforces the presence of a category like
heads/,
tags/
etc\&. but the actual names are not restricted\&.
.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
\&.\&.
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
DEL), space, tilde
~, caret
^, colon
:, question\-mark
?, asterisk
*, or open bracket
[
anywhere\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}
They cannot end with a slash
/
nor a dot
\&.\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  6." 4.2
.\}
They cannot end with the sequence
\&.lock\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  7." 4.2
.\}
They cannot contain a sequence
@{\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 8.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  8." 4.2
.\}
They cannot contain a
\e\&.
.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 avoids 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
\&.\&.
is often used as in
ref1\&.\&.ref2, and in some contexts this notation means
^ref1 ref2
(i\&.e\&. not in
ref1
and in
ref2)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
A tilde
~
and caret
^
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
:
is used as in
srcref:dstref
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
@{
is used as a notation to access a reflog entry\&.
.RE
.sp
With the \-\-print option, if \fIrefname\fR is acceptable, it prints the canonicalized name of a hypothetical reference with that name\&. That is, it prints \fIrefname\fR with any extra / characters removed\&.
.sp
With the \-\-branch option, it expands the \(lqprevious branch syntax\(rq @{\-n}\&. For example, @{\-1} is a way to refer the last branch you were on\&. 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\&.
.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 branch:
.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 \-\-print "refs/heads/$newbranch") ||
die "we do not like \(aq$newbranch\(aq as a branch name\&."
.fi
.if n \{\
.RE
.\}
.sp
.RE
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite